Update an MCP server
Change a registered server. Omitted fields keep what is stored, so send only what changes. Two rules are worth knowing before you call: switching authType requires sending credentials in the same request, and customHeaders replaces the stored map wholesale rather than merging into it. Servers CloudHumans owns cannot be changed.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
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.
MCP server to operate on, as returned by listMcpServers.
Body
What to change on an MCP server. Every field is optional and an omitted one keeps what is stored.
New display name. Changing it recomputes the slug agents reference.
"Acme Orders"
New MCP endpoint, http or https. Changing it invalidates a previous probe: send verified again after re-probing.
"https://mcp.acme.com/mcp"
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.
none, bearer, apiKey, forwarded_user, oauth "bearer"
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.
"sk-live-9f3c2b7a"
Replaces the stored headers wholesale — send the full map you want, or an empty object to remove all of them. Omit to keep them.
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.
true
Response
The server as stored after the change.
An MCP server your agents can call tools on.
Use this id to update, delete or re-probe this server.
"6683f1c2a4b19e0012ab34cd"
Display name, as shown in the Tools screen.
"Acme Orders"
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.
"acme_orders"
The MCP endpoint agents call. Used exactly as stored once verified is true.
"https://mcp.acme.com/mcp"
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.
none, bearer, apiKey, forwarded_user, oauth "bearer"
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.
true
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.
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.
true
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.
false
When the server was registered (ISO-8601). Absent on platform-owned servers, which are not stored per tenant.
"2026-08-10T14:32:05Z"
When it last changed (ISO-8601). Absent until the first change.
"2026-08-10T18:20:41Z"