Report every declared external tool server's health and cost

Answers, per declared MCP tool server, whether it is up, since when, how many consecutive connection attempts have failed and why the last one did — plus how many calls it has been asked to make and how many characters of model context its presence in the budgeted catalogue spends. Health is taken live off an MCP ping while answering, so a server holding an open socket and answering nothing reads as down rather than as connected. The whole sweep is bounded by the request: the pings go out in parallel, so eight silent endpoints cost one ping ceiling between them. A trusted repository’s own servers (its .mcp.json) appear as further rows carrying repository, for every repository root that has servers live on this host right now, and for each of the caller’s own environments whose container runs some.

GET /v1/tool-servers

Report every declared external tool server's health and cost

cURL

curl --request GET \
  --url https://api.example.com/v1/tool-servers \
  --header 'Authorization: Bearer <token>'

200

[
  {
    "name": "matcher",
    "status": "down",
    "since": "2026-08-13T09:12:00.000Z",
    "tools": 0,
    "attempts": 14,
    "calls": 0,
    "catalogueBytes": 0,
    "lastError": "connect: executable file not found in $PATH"
  }
]

Authorizations

Authorization · string · header · required

Enforced on every transport, with no exempt operation. A person's request must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011 — except a request with no token on a laptop's socket from the OS user the kernel names as the host's own, which is that machine's user.

Response

200

application/json

One entry per declared tool server, the person's own in name order, then each repository's by repository and name.

name · string · required

The name the server was declared under, or .mcp.json for a repository whose file does not read or parse, which starts none.

status · enum<string> · required

waiting-for-sign-in is a connection attempt held open for a PERSON: the server demanded OAuth, the host put an authorization URL in front of whoever is watching, and nothing else is wrong. It is reported separately from connecting because the two need opposite reactions — connecting resolves itself, this one resolves only when somebody opens signInUrl — and because the alternative was a five-minute "connecting" whose eventual failure read "context canceled" and never named the sign-in.

Available options: connecting, connected, down, waiting-for-sign-in

tools · integer · required

Required range: x >= 0

attempts · integer · required

Consecutive failures since this server last connected.

Required range: x >= 0

calls · integer<int64> · required

Tool calls this server has been asked to make.

Required range: x >= 0

catalogueBytes · integer · required

Characters of model context this server's catalogue entry spends.

Required range: x >= 0

since · string<date-time>

When the server entered this status — for waiting-for-sign-in, when the host started waiting on the person.

pingMs · integer

Round trip of the live MCP ping taken while answering. Absent when the server is not connected, or when the ping failed — in which case lastError says so.

Required range: x >= 0

lastError · string

Why the last attempt, session or ping failed; on a connected repository server, which of its tools its repository's sessions are not offered because another repository's server of the name defines them differently.

repository · string

The repository root a repository's own server serves (its .mcp.json), or the environment whose container runs it, for a conversation's clone; absent for a server the person declared in config.toml.

signInUrl · string

The authorization page a person must open to finish this server's sign-in. Present only while status is waiting-for-sign-in.

signInExpiresAt · string<date-time>

When this sign-in window closes. Present only while status is waiting-for-sign-in.