Skip to main content
PUT
Update an MCP server

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

tenant
string
required

Tenant whose MCP servers you are managing. Get it from the backoffice GET /auth/v1/me/claudia-projects, which answers with the tenant your credentials cover. A tenant your credentials do not cover is indistinguishable from one that does not exist.

id
string
required

MCP server to operate on, as returned by listMcpServers.

Body

application/json

What to change on an MCP server. Every field is optional and an omitted one keeps what is stored.

name
string

New display name. Changing it recomputes the slug agents reference.

Example:

"Acme Orders"

url
string

New MCP endpoint, http or https. Changing it invalidates a previous probe: send verified again after re-probing.

Example:

"https://mcp.acme.com/mcp"

authType
enum<string>

New auth type. Changing it requires sending credentials in the same request — the new value for bearer/apiKey, or null for none, forwarded_user and oauth.

Available options:
none,
bearer,
apiKey,
forwarded_user,
oauth
Example:

"bearer"

credentials
string | null

New secret, in full. Omit to keep the stored one, send null to clear it (only valid when the resulting auth type stores no secret). Never send back a value read from this API — nothing readable is ever returned.

Example:

"sk-live-9f3c2b7a"

customHeaders
object

Replaces the stored headers wholesale — send the full map you want, or an empty object to remove all of them. Omit to keep them.

Example:
verified
boolean

Whether the url is a complete MCP endpoint. Omit to keep the stored value. Send true only after a passing probe of the exact combination being saved, and false whenever you change url, auth type, credential or headers without re-probing.

Example:

true

Response

The server as stored after the change.

An MCP server your agents can call tools on.

id
string
required

Use this id to update, delete or re-probe this server.

Example:

"6683f1c2a4b19e0012ab34cd"

name
string
required

Display name, as shown in the Tools screen.

Example:

"Acme Orders"

slug
string
required

Stable key derived from the name: lowercased, with every run of non-alphanumeric characters collapsed into _. Agent configurations reference a server by this key, so renaming a server changes it and is not a cosmetic edit. Unique within the tenant.

Example:

"acme_orders"

url
string
required

The MCP endpoint agents call. Used exactly as stored once verified is true.

Example:

"https://mcp.acme.com/mcp"

authType
enum<string>
required

How Claudia authenticates to this server. none sends no credential; bearer sends the stored secret as Authorization: Bearer <secret>; apiKey sends it as x-api-key; forwarded_user stores no secret and forwards the end user's own token at call time; oauth stores no secret either and lets the CloudHumans MCP gateway resolve the contact's custodied session.

Available options:
none,
bearer,
apiKey,
forwarded_user,
oauth
Example:

"bearer"

credentialsStored
boolean
required

Whether a secret is stored for this server. The secret itself is never returned by this API — to change it, send the new value in full. Always false for none, forwarded_user and oauth, which store no secret by design, and for platform-owned servers, whose credential is held by the platform.

Example:

true

customHeaders
object
required

Extra headers sent on every call to this server. Header names are lowercased on save, and the ones owned by the auth and tenant pipeline (authorization, x-api-key, x-tenant, x-authorization, x-account, x-tenant-name) are dropped — send credentials through credentials, not here.

Example:
verified
boolean
required

Whether this url was probed successfully and is used as stored. False keeps the legacy behaviour of appending /mcp to the url at call time, so a server whose url already ends in the MCP path answers 404 until it is verified.

Example:

true

platformOwned
boolean
required

Whether CloudHumans owns this server. Platform-owned servers are provided to every tenant and are listed so agents can reference them, but they cannot be changed or deleted — those attempts answer 422.

Example:

false

createdAt
string | null

When the server was registered (ISO-8601). Absent on platform-owned servers, which are not stored per tenant.

Example:

"2026-08-10T14:32:05Z"

updatedAt
string | null

When it last changed (ISO-8601). Absent until the first change.

Example:

"2026-08-10T18:20:41Z"