Register an MCP server
Add a server so its tools become available to this tenant’s agents. Probe the endpoint with validateMcpServer first: a passing probe is what lets you send verified: true, which is what makes the runtime call the url exactly as you wrote it.
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.
Body
The MCP server to register.
Display name. The slug agents reference is derived from it, so pick something stable.
"Acme Orders"
The MCP endpoint, http or https. Sent as written — include the full path the server answers on (commonly ending in /mcp) and set verified after probing it.
"https://mcp.acme.com/mcp"
How Claudia should authenticate. bearer and apiKey require credentials; none, forwarded_user and oauth require that it be omitted.
none, bearer, apiKey, forwarded_user, oauth "bearer"
Whether the url is a complete MCP endpoint. Set true only after validateMcpServer answered valid: true for this exact url, auth type, credential and headers; leaving it false makes the runtime append /mcp to the url.
true
The secret to authenticate with, in full. Stored encrypted and never returned. Required for bearer and apiKey, refused for every other auth type.
"sk-live-9f3c2b7a"
Extra headers to send on every call. Names are lowercased on save; reserved names are dropped rather than rejected.
Response
The server as registered.
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"