MCP Servers API

MCP server connections and their OAuth lifecycle.

📄️List MCP servers

The MCP server registrations visible to the caller: shared company servers and the caller’s own private ones. Env values, client secrets, and stored tokens never appear in responses.

📄️Register MCP server

Registers an external MCP server: its URL, transport, and auth method. Requires company write permission. After registering, enable the server for an application so its agents can call the tools, and for oauth servers have each user connect via `GET /api/v1/mcp-servers/oauth/authorize/`.

📄️Get MCP server

One MCP server registration, when it is shared with the company or privately owned by the caller. Env values, client secrets, and stored tokens never appear in responses.

📄️Update MCP server

Updates a registration. Omitted fields keep their stored values. `env` replaces the stored map wholesale when present. An `oauth` object without `clientSecret` keeps the stored secret. Requires company write permission.

📄️Delete MCP server

Deletes a registration. Per-user OAuth connections to the server are removed with it, and applications that had it enabled simply stop listing it. Requires company write permission.

📄️Get OAuth connection status

Reports whether the server requires a per-user OAuth connection and, when it does, the state of the caller’s stored tokens (`not_connected`, `connected`, `expiring_soon` or `expired`). Use `GET /api/v1/mcp-servers/oauth/authorize/` to start a new connection.

📄️Disconnect OAuth connection

Deletes the caller’s stored OAuth tokens for the server. The assistant then skips the server’s tools until the user reconnects via `GET /api/v1/mcp-servers/oauth/authorize/`. Succeeds even when no connection exists.

📄️Test connectivity

Opens a real client session against the server and lists its tools, so it exercises the configured transport, credentials and, for OAuth servers, the caller’s stored connection. Discovery failures answer `400` with the error message in the same response shape.

📄️Get OAuth connection status for MCP server (deprecated shape)

Deprecated: use `GET /api/v1/mcp-servers/{mcpServerId}/connection/`, which addresses the server in the path instead of a required query parameter. Same payload, same behavior.

📄️Disconnect OAuth connection for MCP server (deprecated shape)

Deprecated: use `DELETE /api/v1/mcp-servers/{mcpServerId}/connection/`, which addresses the server in the path instead of a required query parameter. Same behavior.

📄️List OAuth connection statuses

Covers every MCP server of the caller’s company that is configured for OAuth, servers with other auth methods are omitted. Each entry matches the `GET /api/v1/mcp-servers/{mcpServerId}/connection/` response shape.

📄️Test connectivity to MCP server (deprecated shape)

Deprecated: use `POST /api/v1/mcp-servers/{mcpServerId}/test-connection/`, which addresses the server in the path instead of a required query parameter. This variant behaves identically. Opens a real client session against the server and lists its tools, so it exercises the configured transport, credentials and, for OAuth servers, the caller’s stored connection. Discovery failures answer `400` with the error message in the same response shape.

📄️Start OAuth flow

Discovers the MCP authorization server, registers a client when needed, builds a PKCE authorization request, and answers the provider authorization URL as JSON. The endpoint itself never issues a `302`. After consent the provider redirects back to `/api/oauth/mcp/callback`, which stores the tokens read by `GET /api/v1/mcp-servers/{mcpServerId}/connection/`.