Skip to content

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.

id
required
string format: uuid

The registration’s ID. A value that isn’t a UUID gets a plain-text 400.

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
url

A new address, used from the next restart. An empty value is saved.

string
>= 1 characters
transport

Saved but not used yet.

string
Allowed values: http stdio
auth_kind

A new way to authenticate, used from the next restart. The saved secret and header are kept.

string
Allowed values: none bearer header mtls
auth_secret_ref

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.

string format: password
auth_header_name

A new header name, used from the next restart. An empty value is saved.

string
privacy_class

Applies from the next tool call.

string
Allowed values: local cloud
enabled

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.

boolean
rate_limit_per_second

Used from the next restart.

integer
>= 1
rate_limit_per_minute

Saved but not used yet.

integer
>= 1
health_check_interval_s

Used from the next restart.

integer
>= 1

The registration as saved.

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

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

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed