MCP servers

With an ai section in the config, your docs server also speaks the Model Context Protocol. Coding agents such as Claude Code, Cursor and VS Code connect to it over HTTP.

• Docs MCP at /mcp: search and read your guides and API reference.
• API MCP at /mcp/<api id>: every operation of that API becomes a tool that calls your API with the agent's own credentials.

Like Ask AI, both need a server: Nest with mountOrbitDocs, Next server mode, or the self-hosted platform. See Ask AI needs a server.

Turn them onCopy Anchor Link

They are on as soon as the config has an ai section. The mcp options choose what is served:

ai: {
  provider: 'anthropic',
  model: 'claude-sonnet-5-5',
  apiKeyEnv: 'ANTHROPIC_API_KEY',
  mcp: {
    docs: true,
    apis: ['payments'],
    tools: 'per-operation',
  },
},

The MCP servers use no LLM: the provider settings only matter for Ask AI. They still need the ai section.

Connect a clientCopy Anchor Link

The servers use the Streamable HTTP transport and are stateless. With docs at https://docs.acme.com (add your base path if you have one):

claude mcp add --transport http acme-docs https://docs.acme.com/mcp
claude mcp add --transport http acme-api https://docs.acme.com/mcp/payments --header "x-api-key: $ACME_API_KEY"

Put these snippets in one of your guides, so your readers can connect in one step.

Docs MCPCopy Anchor Link

All three are marked read-only. The server tells clients to call search_docs first, then read_page. Search uses the same index as Ask AI.

URLs are absolute when site.url is set, so agents can cite them. Set it.

API MCPCopy Anchor Link

/mcp/<api id> lists one tool per operation:

• Name: the operationId in snake case (createBooking becomes create_booking), or the operation's URL slug when there is none. Names are unique and at most 64 characters.
• Description: the summary, METHOD /path and the start of the description.
• Input: path, query and header parameters by name, plus body for the request body. Schemas are inlined so each tool stands alone.
• Hints: GET and HEAD tools are marked read-only, DELETE tools destructive, so clients can ask before running them.

Which server it callsCopy Anchor Link

The tool calls the first server of the API's spec (servers in the config, or the spec's own), with server variables set to their defaults. A relative server URL is resolved against site.url.

CredentialsCopy Anchor Link

The docs server never holds API credentials. Each tool call forwards the credentials the MCP client sent when it connected:

• Authorization, always.
• The header of each apiKey security scheme in a header (x-api-key, for example).
• Cookie, when a scheme uses a cookie.

Query-string API keys are not forwarded. Agents act as whoever owns the key, with that key's permissions.

Large APIsCopy Anchor Link

Hundreds of tools crowd an agent's context. mcp.tools: 'search-execute' replaces them with two:

Responses over 50,000 characters are cut. Non-2xx responses are returned as tool errors with the status and body.

Private docs and MCPCopy Anchor Link

MCP clients carry no docs session. They only see what an anonymous reader sees:

• The docs MCP searches and lists public pages only.
• An API with access, or under a rule that restricts /reference/<id>/, has no MCP server (404).
• An operation under a rule of its own (such as /reference/<id>/<operation>) is not a tool of its API's MCP server.
• In access.mode: 'private', nothing is public: the docs MCP finds nothing and no API MCP is served.

Next stepsCopy Anchor Link