Connettere Claude Code o Codex CLI al reader MCP della documentazione

Il reader MCP della documentazione di mayo è un endpoint pubblico e in sola lettura: espone solo lo snapshot delle guide già pubblicate, mai una superficie di scrittura. È distinto dal server MCP human-docs usato dall'autore in locale (quello scrive la bozza sul proprio checkout): qui stai collegando un client a POST /api/docs/mcp, l'endpoint HTTP remoto.

Cosa ti serve prima di iniziare

• Un token bearer con scope docs:read, fornito da chi amministra il progetto. Non è mai il tuo token personale del prodotto: è una credenziale dedicata al reader documentale.
• Il token va salvato in una variabile d'ambiente della tua macchina (qui chiamata DOCS_MCP_READER_TOKEN), mai scritto in un file di configurazione versionato.
• L'URL dell'endpoint: https://app.mayoeasyorder.com/api/docs/mcp.

export DOCS_MCP_READER_TOKEN="<il-tuo-token>"

Passo 1 — Configura il client

Claude Code

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

Esito atteso: claude mcp list elenca il server mayo-docs.

Codex CLI

Aggiungi al tuo ~/.codex/config.toml:

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

Esito atteso: all'avvio, Codex CLI elenca mayo-docs tra i server MCP configurati.

Passo 2 — Verifica la connessione

Dal client configurato, chiama il tool docs_status (nessun argomento). La risposta contiene i campi productRevision, snapshotRevision, languages, guideCount, publishedAt, guideIds, deploymentReceipt, publishedJobIds e guides. Se non c'è ancora nulla di pubblicato, i campi tornano vuoti (null/[]/0): non è un errore, è lo stato legittimo di pre-pubblicazione.

In alternativa, verifica via HTTP diretto:

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"}}}}'

Esito atteso: una risposta 200 con un payload JSON-RPC contenente il risultato di docs_status nella forma descritta sopra.

Passo 3 — Usa gli altri tool di lettura

Una volta connesso, hai a disposizione quattro tool, tutti in sola lettura:

Se qualcosa non funziona

• 401 unauthorized — il bearer è assente, malformato, sconosciuto oppure la configurazione del reader sul target è stata rifiutata per intero: verifica di aver esportato correttamente DOCS_MCP_READER_TOKEN prima di lanciare il client.
• 403 forbidden_scope — il token è valido ma non ha lo scope docs:read: richiedi un token con lo scope corretto a chi amministra il progetto.
• 503 docs_disabled — il reader è spento sul target: non è un problema del tuo client, segnala la cosa a chi amministra il progetto.
• 429 rate_limited — hai superato il tetto di chiamate per la tua credenziale nella finestra di un minuto: la risposta include Retry-After.

Questa è la versione rapida orientata al compito. Per il contratto completo dell'endpoint (limiti, ordine dei controlli, codici di errore, formato dei log) vedi il runbook operativo docs/references/runbooks/docs-publishing.md e il riferimento API docs/references/api/docs-mcp.md, che restano la fonte autorevole.