Update an MCP server registration
PATCH /admin/ai/mcp-clients/{id}
Changes the fields you send and keeps the rest. name can’t be
changed.
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. An id that isn’t a UUID, or a body that can’t be
decoded into the request shape, gets a plain-text 400, even when you
aren’t signed in. Otherwise signed-out callers get 401 and callers
without the permission 403.
A field that’s missing or null is kept. Any other value, including
an empty string, is saved as sent, with one exception: an empty
auth_secret_ref keeps the saved secret. So the secret can’t be
cleared here, and changing auth_kind keeps it. An unknown id
gets 404. A value outside the allowed lists or an empty transport,
auth_kind or privacy_class gets a plain-text 500 and nothing
changes. 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.
There’s no version check: if two saves change the same field, the one committed last wins, which isn’t always the one answered last. A field you send is written even if it’s unchanged, and the admin page sends every setting it shows, with the secret only when you type a new one, so its save can replace another save’s changes to those settings. The response is the saved registration, not a check that the server works.
enabled and privacy_class apply from the next tool call. 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. Saving isn’t recorded in the audit
log.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The registration’s ID. A value that isn’t a UUID gets a plain-text 400.
Request Body required
Section titled “Request Body required ”The fields to change. A missing or null field is kept; any other
value replaces the saved one, except that an empty auth_secret_ref
keeps the secret. name and the health fields can’t be changed
here.
object
A new address, used from the next restart. An empty value is saved.
Saved but not used yet.
A new way to authenticate, used from the next restart. The saved secret and header are kept.
Write-only: send a new token or header value to replace the saved
one. A missing, null or empty value keeps it, so it can’t be
cleared here; any other value, even spaces, replaces it. It’s never
returned.
A new header name, used from the next restart. An empty value is saved.
Applies from the next tool call.
Applies from the next tool call that checks it; a call already past that check isn’t stopped. A name the app configured no client for at startup can’t be called until a restart.
Used from the next restart.
Saved but not used yet.
Used from the next restart.
Responses
Section titled “ Responses ”The registration as saved.
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.
Authentication 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 completedResource not found
object
Human-readable error summary
Example
the request could not be completed