MCP servers API
External MCP servers whose tools the assistant can call at question time. See
the Live lookup guide. The router's own prefix is
/api/mcp-servers and it is mounted under /api/v1, so the paths begin
/api/v1/api/mcp-servers.
The server object
MCPServerResponse:
| Property | Type | Description |
|---|---|---|
id | uuid | Server id |
name | string | Display name |
description | string | null | Description |
transport | string | streamable_http or sse |
url | string | Endpoint address; may contain ${VAR} placeholders |
credentials_hint | string | null | Masked hint of the stored credential. The credential is never returned |
enabled | boolean | Whether the assistant may use it |
last_validated_at | datetime | null | Last list-tools check |
validation_error | string | null | Why the last check failed |
tool_names | array of string | Tools found by the last check |
created_at | datetime | Created |
auth_mode | string | shared or per_user |
signed_in | boolean | null | For a per_user server: whether the caller has signed in. null for a shared server |
Manage servers
Creating, updating, validating and deleting need an organization admin. Listing and reading need any member.
POST /api/v1/api/mcp-servers
Returns 201 with the server object. 400 with a message when the request is
not valid.
| Property | Type | Required | Description |
|---|---|---|---|
name | string | * | 1 to 100 characters |
url | string | * | Endpoint address |
transport | string | streamable_http (default) or sse | |
description | string | Up to 2000 characters | |
credentials | object | headers (for example {"Authorization": "Bearer ..."}) and url_secrets (values for ${VAR} placeholders in the address) | |
enabled | boolean | Default true | |
validate_connection | boolean | Run a list-tools check on save. Default true | |
auth_mode | string | shared (default) or per_user |
GET /api/v1/api/mcp-servers
A list of server objects for the organization.
GET /api/v1/api/mcp-servers/{connection_id}
One server object, or 404.
PATCH /api/v1/api/mcp-servers/{connection_id}
Update name, url, transport, description, credentials, enabled;
validate_connection (default false) re-runs the check. auth_mode cannot
be changed.
POST /api/v1/api/mcp-servers/{connection_id}/validate
Run the list-tools check again and record the result. Returns the server object.
DELETE /api/v1/api/mcp-servers/{connection_id}
Returns 204.
Per-person sign-in
For servers with auth_mode: "per_user". Any member may call these for
themselves.
POST /api/v1/api/mcp-servers/{connection_id}/sign-in
Body: return_to (a console path; default /manage/sources/live). Returns
{"authorize_url": "..."}. Send the caller's browser there. 400 with a
message when the server uses a shared credential, does not publish how to sign
in, or refuses to register this deployment. 404 for an unknown server.
After the person approves, the server returns them to the callback, which
redirects to return_to on the console with signed_in=<connection_id>, or
with sign_in_error.
DELETE /api/v1/api/mcp-servers/{connection_id}/sign-in
Forget the caller's own sign-in to this server. Returns 204.