Connect Claude Code or Codex CLI to the documentation MCP reader

DevelopersCategory: QuickstartLanguage: Englishv5fcfd91Verified on mayo 5fcfd91 on 22 September 2026

Before you startRoleA bearer token with `docs:read` scope, assigned by whoever administers the project: without a valid credential every call returns 401.SettingThe documentation reader must be active on the target (a server-side environment variable, not under the control of whoever reads this guide): if it is off, every request returns 503 docs_disabled before any data access., At least one documentation revision must already be published for docs_search, docs_get and docs_list to return non-empty results; without a publication, docs_status legitimately stays empty.If you cannot see this item, ask your account administrator.

mayo's documentation MCP reader is a public, read-only endpoint: it exposes only the snapshot of already-published guides, never a write surface. It is distinct from the human-docs MCP server the author uses locally (that one writes the draft to their own checkout): here you are connecting a client to POST /api/docs/mcp, the remote HTTP endpoint.

What you need before you start

A bearer token with docs:read scope, provided by whoever administers the project. It is never your personal product token: it is a credential dedicated to the documentation reader.
The token must be saved in an environment variable on your machine (called DOCS_MCP_READER_TOKEN here), never written to a versioned configuration file.
The endpoint URL: https://app.mayoeasyorder.com/api/docs/mcp.

export DOCS_MCP_READER_TOKEN="<your-token>"

Step 1 — Configure the client

Claude Code

bash

claude mcp add --transport http mayo-docs \
  https://app.mayoeasyorder.com/api/docs/mcp \
  --header "Authorization: Bearer $DOCS_MCP_READER_TOKEN"

Expected result: claude mcp list lists the mayo-docs server.

Codex CLI

Add this to your ~/.codex/config.toml:

toml

[mcp_servers.mayo-docs]
url = "https://app.mayoeasyorder.com/api/docs/mcp"
bearer_token_env_var = "DOCS_MCP_READER_TOKEN"

Expected result: on startup, Codex CLI lists mayo-docs among the configured MCP servers.

Step 2 — Verify the connection

From the configured client, call the docs_status tool (no arguments). The response contains the fields productRevision, snapshotRevision, languages, guideCount, publishedAt, guideIds, deploymentReceipt, publishedJobIds and guides. If nothing has been published yet, the fields come back empty (null/[]/0): that is not an error, it is the legitimate pre-publication state.

Alternatively, verify via direct HTTP:

curl -sS "https://app.mayoeasyorder.com/api/docs/mcp" \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: docs_status' \
  -H "authorization: Bearer $DOCS_MCP_READER_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"docs_status","arguments":{},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1.0.0"}}}}'

Expected result: a 200 response with a JSON-RPC payload containing the docs_status result in the shape described above.

Step 3 — Use the other read tools

Once connected, you have four tools available, all read-only:


Tool	What it does
`docs_status`	status of the published snapshot
`docs_search`	full-text search across published guides (`query`, `language`, optional `audience`, `limit` 1-50)
`docs_get`	fetch one guide by `guideId` or by `route` (exactly one of the two), in a given `language`
`docs_list`	paginated list of published guides (`language`, optional `audience`/`category` filters)

If something doesn't work

401 unauthorized — the bearer is missing, malformed, unknown, or the reader's configuration on the target was rejected outright: check that you exported DOCS_MCP_READER_TOKEN correctly before launching the client.
403 forbidden_scope — the token is valid but lacks the docs:read scope: request a token with the correct scope from whoever administers the project.
503 docs_disabled — the reader is turned off on the target: it is not a problem with your client, report it to whoever administers the project.
429 rate_limited — you have exceeded the call cap for your credential within the one-minute window: the response includes Retry-After.

This is the fast, task-oriented version. For the endpoint's full contract (limits, check order, error codes, log format) see the operational runbook docs/references/runbooks/docs-publishing.md and the API reference docs/references/api/docs-mcp.md, which remain the authoritative source.

Start free with mayo Browse documentation