Skip to content

Register an MCP server

POST
/admin/ai/mcp-clients

Saves a new MCP server registration and returns it. Nothing contacts the server or grants its tools; each tool is granted separately.

You need mcp.client.admin or system.admin for the whole install; a permission held only for a team doesn’t count, and neither does ai.admin. A body that can’t be decoded into the request shape, such as one with a number where a string goes, gets a plain-text 400, even when you aren’t signed in. Otherwise signed-out callers get 401 and callers without the permission 403.

Fields you leave out get their defaults, and an empty transport, auth_kind or privacy_class also gets the default; the new server is disabled unless you send enabled: true. name and url aren’t checked beyond being strings, so an empty value is saved. A name that exactly matches an existing one, case and spaces included, gets 409. Any other value outside the allowed lists gets a plain-text 500 and nothing is saved. Limits and the interval are stored as 32-bit numbers and must be above 0: within that range, 0 or less also gets the plain-text 500, and a value outside it isn’t kept as sent.

Calls go through a client the app configured at startup for each server name enabled then, with the address, auth, secret and per-second limit saved at that time. A name with no client configured then can’t be called until a restart, and changing those settings doesn’t change the configured client until a restart. Health checking separately picks the servers enabled when it starts and checks each one at the interval saved then, using the client already configured for its name, if there is one. Registering isn’t recorded in the audit log.

The settings for a new registration. Only name and url are needed; every other field gets the default shown, and an empty transport, auth_kind or privacy_class gets it too.

object
name
required

The name to register under, which can’t be changed later. It must not exactly match an existing one; it isn’t otherwise checked, so an empty name is accepted.

string
>= 1 characters <= 128 characters
url
required

The server’s JSON-RPC address. It isn’t checked or contacted when saved.

string
>= 1 characters
transport

Saved but not used yet; calls always go over HTTP.

string
default: http
Allowed values: http stdio
auth_kind

How calls authenticate; see MCPServer. mtls isn’t supported yet.

string
default: none
Allowed values: none bearer header mtls
auth_secret_ref

Write-only: the bearer token or header value itself, stored as sent and never returned. Despite the name, it isn’t a reference to a secret store. An empty value saves no secret.

string format: password
auth_header_name

The header for the secret when auth_kind is header.

string
privacy_class

Your statement of where the server runs; nothing checks it.

string
default: cloud
Allowed values: local cloud
enabled

Defaults to false. Even when true, a name the app configured no client for at startup can’t be called until a restart.

boolean
rate_limit_per_second

Calls and health checks per second, used from the next restart.

integer
default: 2 >= 1
rate_limit_per_minute

Saved but not used yet.

integer
default: 60 >= 1
health_check_interval_s

Seconds between health checks, used from the next restart.

integer
default: 60 >= 1

The saved registration.

One registered MCP server, as saved. The stored secret is never included, whatever your permissions.

object
id
required

The registration’s ID, set when it’s saved.

string format: uuid
name
required

The name the server was registered under, matched exactly, case included. Tool calls and usage records refer to the server by it, and it can’t be changed.

string
>= 1 characters <= 128 characters
url
required

The address tool calls and health checks are posted to, as JSON-RPC over HTTP. It isn’t checked when saved.

string
>= 1 characters
transport
required

Saved and returned, but not used yet: calls always go over HTTP, even for stdio.

string
Allowed values: http stdio
auth_kind
required

How calls authenticate: none; bearer, an Authorization: Bearer header with the secret; or header, the secret in the header named by auth_header_name. mtls is saved but not supported yet: it doesn’t set up mutual TLS, and the secret isn’t sent.

string
Allowed values: none bearer header mtls
auth_secret_set
required

True when a secret is saved for this server. It doesn’t mean the secret works. The secret itself is never returned.

boolean
auth_header_name

The header that carries the secret when auth_kind is header. Left out when empty.

string
nullable
privacy_class
required

Your statement of where the server runs; nothing checks it. While the privacy lock is on, as read when the app started, tool calls for restricted or embargoed assets go only to local servers.

string
Allowed values: local cloud
enabled
required

Whether tool calls to this server are allowed, checked on every call. Calls also need the client the app configured at startup for the server’s name, so a name that had none then can’t be called until a restart.

boolean
rate_limit_per_second
required

The average rate, per second, at which this app instance starts the calls and health checks it sends to the server, which share it; up to the same number can start together in a burst. It limits when they start, not how many are still in progress. It isn’t a strict cap for every second or a limit across app instances. The value in use is the one from when the app started.

integer
>= 1
rate_limit_per_minute
required

Saved and returned, but not used yet.

integer
>= 1
health_check_interval_s
required

Seconds between health checks, using the value saved when health checks started with the app. Each check can take up to half the interval, in whole seconds, so an interval of 1 leaves no time and the check fails.

integer
>= 1
last_health_check_at

Not filled in yet: it’s always left out.

string format: date-time
nullable
last_health_status

The saved result of the last health check, which asks the server for its tool list: healthy when the reply could be read as a tool list, degraded when the request couldn’t be built from the saved address or the server answered with a client error or a JSON-RPC error, unreachable otherwise (no reply in time, a server error, a 429 or a reply that couldn’t be read). It doesn’t show that any granted tool works. Left out until a result is saved. Health checking separately picks the servers enabled when it starts and checks each one at the interval saved then, using the client already configured for its name, if there is one.

string
nullable
Allowed values: healthy degraded unreachable
last_health_error

The error saved by the last failed check, which can include text from the server’s reply. A longer error is cut after 500 bytes and ends with an ellipsis. Left out when no error is saved.

string
nullable
created_at
required

Not filled in yet: always 0001-01-01T00:00:00Z.

string format: date-time
updated_at
required

Not filled in yet: always 0001-01-01T00:00:00Z.

string format: date-time

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Conflict (slug taken, would create cycle, etc.)

object
error
required

Human-readable error summary

string
Example
the request could not be completed