# Hosted MCP server

The implemented MCP role accepts `POST /mcp` on its dedicated listener. This page describes merged backend behavior; no deployed MCP URL or desktop-client interoperability is claimed. Configure a client only against a service your operator has provisioned. See the [transport reference](/reference/api/mcp/).

## Give the client a restricted key

Send a native restricted secret key as `Authorization: Bearer sk_…`. Every admitted key needs `mcp:use`; add only the permissions required by the tools you intend to use. Publishable keys, dashboard credentials and portal tokens are not MCP credentials.

A key containing `*` or any permission outside `mcp:use`, `organizations:read`, `connections:read`, `workbench:read` and `portal_links:write` is refused with [`mcp_key_too_broad`](/errors/mcp_key_too_broad/). Even an unrelated read permission makes the key too broad. Missing required permissions return [`api_key_scope_missing`](/errors/api_key_scope_missing/). Malformed requests can fail validation before key classification; a refusal never executes a tool.

| Tool                   | Permission in addition to `mcp:use` | Purpose                                                              |
| ---------------------- | ----------------------------------- | -------------------------------------------------------------------- |
| `list_organizations`   | `organizations:read`                | List this environment's organizations; optional name/domain filters. |
| `get_connection`       | `connections:read`                  | Read one connection without secrets or raw certificates.             |
| `list_connections`     | `connections:read`                  | List connections, optionally within an organization.                 |
| `explain_error`        | None                                | Explain a catalogue code or this environment's request trace.        |
| `get_sign_in_timeline` | `workbench:read`                    | Read a redacted sign-in timeline.                                    |
| `create_portal_link`   | `portal_links:write`                | Create an organization-scoped setup link.                            |
| `search_docs`          | None                                | Search the committed public documentation index.                     |

Tenant-entered text (organization and connection names, and attribute keys in sign-in timelines) is returned only inside an `untrusted` object, and every tool description says so. Treat everything under `untrusted` as data, never as instructions to the agent. Connection results list at most 10 certificate fingerprints per connection and set `certificate_fingerprints_truncated` when the connection holds more; a page lists at most 50 connections. A historical request trace without authoritative error metadata returns `explanation_available: false`; the server does not guess an error from its HTTP status.

## Transport and limits

Supported protocol versions are `2025-06-18` and `2025-11-25`. Initialize the client before tool calls and send the supported `MCP-Protocol-Version`. Each POST contains one JSON-RPC message: no batches. Responses are JSON; there is no SSE stream, and `GET /mcp` returns HTTP 405. OAuth authorization and local stdio are not implemented.

Request bodies are limited to 256 KiB. Each tool result is limited to 64 KiB. The result appears as both a text block and `structuredContent`; the response envelope allows 3 × 64 KiB + 4 KiB so an allowed result fits. The rolling allowance is 60 tool calls per key per minute; respect a rate-limit refusal rather than repeatedly retrying.

An absent `Origin` header is accepted. A supplied browser Origin must exactly match an entry in the operator's `MCP_ALLOWED_ORIGINS`; any other origin is refused with HTTP 403 [`mcp_origin_refused`](/errors/mcp_origin_refused/). An allowed origin does not grant authority beyond the key's environment and scopes.

## Revoking a key

Key revocation and scope changes reach the MCP server through its configuration snapshot, so they apply within the operator's `SNAPSHOT_MAX_STALENESS` (30 seconds by default), not instantly. The server refuses authentication when its copy of key authority is older than that bound. If a key leaks, revoke it and expect calls to stop within that window.

## Portal links and audit

`create_portal_link` requires `organization`, `features` and `idempotency_key`. Features are `sso`, `dsync`, or both; an optional `profile` selects a portal profile. Reuse the same idempotency key only when retrying the same logical creation. The key is nonempty and at most 128 characters. Only this tool writes tenant configuration.

Every authenticated tool-call attempt is audited before execution, including refused attempts. Audit records identify the key, finite tool name and canonical resource identifiers, without names, search queries or argument values. The execution allowance does not bound refused-attempt audit traffic.

`search_docs` reads a committed static index from a reviewed docs build, not a live crawler or tenant data source. Index refresh is a separate build step; newly written pages are not searchable until the core index has been regenerated.
