Skip to content

List the registered MCP servers

GET
/admin/ai/mcp-clients

Returns every MCP server registered for this install to call, enabled or not, sorted by name, with no paging.

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. Without one you get 403, and signed-out callers get 401.

Each entry has the saved settings and the last health check result. The stored secret is never included; auth_secret_set says whether one is saved. Tool grants aren’t included (use listMCPClientToolGrants), and created_at and updated_at are always 0001-01-01T00:00:00Z for now.

The list shows what’s saved and doesn’t contact any server. 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. A health result can be out of date. Server errors get a plain-text 500.

The registered servers.

object
items
required

Every registration, enabled or not, sorted by name. Empty when there are none.

Array<object>

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