Skip to main content
POST
Register 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.

Body

application/json

The MCP server to register.

name
string
required

Display name. The slug agents reference is derived from it, so pick something stable.

Example:

"Acme Orders"

url
string
required

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.

Example:

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

authType
enum<string>
required

How Claudia should authenticate. bearer and apiKey require credentials; none, forwarded_user and oauth require that it be omitted.

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

"bearer"

verified
boolean
required

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.

Example:

true

credentials
string

The secret to authenticate with, in full. Stored encrypted and never returned. Required for bearer and apiKey, refused for every other auth type.

Example:

"sk-live-9f3c2b7a"

customHeaders
object

Extra headers to send on every call. Names are lowercased on save; reserved names are dropped rather than rejected.

Example:

Response

The server as registered.

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"