Skip to content
Dashboard
Theme
Theme

Hosted MCP server

Restricted keys, tool permissions and transport limits for the implemented MCP role.

View Markdown

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.

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. Even an unrelated read permission makes the key too broad. Missing required permissions return 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.

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. An allowed origin does not grant authority beyond the key’s environment and scopes.

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.

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.