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.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”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
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.
The server’s JSON-RPC address. It isn’t checked or contacted when saved.
Saved but not used yet; calls always go over HTTP.
How calls authenticate; see MCPServer. mtls isn’t supported yet.
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.
The header for the secret when auth_kind is header.
Your statement of where the server runs; nothing checks it.
Defaults to false. Even when true, a name the app configured no client for at startup can’t be called until a restart.
Calls and health checks per second, used from the next restart.
Saved but not used yet.
Seconds between health checks, used from the next restart.
Responses
Section titled “ Responses ”The saved registration.
One registered MCP server, as saved. The stored secret is never included, whatever your permissions.
object
The registration’s ID, set when it’s saved.
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.
The address tool calls and health checks are posted to, as JSON-RPC over HTTP. It isn’t checked when saved.
Saved and returned, but not used yet: calls always go over HTTP, even for stdio.
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.
True when a secret is saved for this server. It doesn’t mean the secret works. The secret itself is never returned.
The header that carries the secret when auth_kind is header. Left out when empty.
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.
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.
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.
Saved and returned, but not used yet.
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.
Not filled in yet: it’s always left out.
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.
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.
Not filled in yet: always 0001-01-01T00:00:00Z.
Not filled in yet: always 0001-01-01T00:00:00Z.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedConflict (slug taken, would create cycle, etc.)
object
Human-readable error summary
Example
the request could not be completed