Connecter Claude Code ou Codex CLI au lecteur MCP de la documentation

Le lecteur MCP de la documentation de mayo est un endpoint public et en lecture seule : il expose uniquement l'instantané des guides déjà publiés, jamais une surface d'écriture. Il est distinct du serveur MCP human-docs utilisé par l'auteur en local (celui-ci écrit le brouillon sur son propre checkout) : ici, vous connectez un client à POST /api/docs/mcp, l'endpoint HTTP distant.

Ce dont vous avez besoin avant de commencer

• Un jeton bearer avec le scope docs:read, fourni par la personne qui administre le projet. Ce n'est jamais votre jeton personnel du produit : c'est une identification dédiée au lecteur documentaire.
• Le jeton doit être enregistré dans une variable d'environnement de votre machine (appelée ici DOCS_MCP_READER_TOKEN), jamais écrit dans un fichier de configuration versionné.
• L'URL de l'endpoint : https://app.mayoeasyorder.com/api/docs/mcp.

export DOCS_MCP_READER_TOKEN="<votre-jeton>"

Étape 1 — Configurez le client

Claude Code

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

Résultat attendu : claude mcp list affiche le serveur mayo-docs.

Codex CLI

Ajoutez ceci à votre ~/.codex/config.toml :

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

Résultat attendu : au démarrage, Codex CLI affiche mayo-docs parmi les serveurs MCP configurés.

Étape 2 — Vérifiez la connexion

Depuis le client configuré, appelez l'outil docs_status (sans argument). La réponse contient les champs productRevision, snapshotRevision, languages, guideCount, publishedAt, guideIds, deploymentReceipt, publishedJobIds et guides. Si rien n'a encore été publié, les champs reviennent vides (null/[]/0) : ce n'est pas une erreur, c'est l'état légitime de pré-publication.

Vous pouvez aussi vérifier via une requête HTTP directe :

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

Résultat attendu : une réponse 200 avec un payload JSON-RPC contenant le résultat de docs_status dans la forme décrite ci-dessus.

Étape 3 — Utilisez les autres outils de lecture

Une fois connecté, vous disposez de quatre outils, tous en lecture seule :

Si quelque chose ne fonctionne pas

• 401 unauthorized — le bearer est absent, malformé, inconnu, ou la configuration du lecteur sur la cible a été rejetée entièrement : vérifiez que vous avez bien exporté DOCS_MCP_READER_TOKEN avant de lancer le client.
• 403 forbidden_scope — le jeton est valide mais n'a pas le scope docs:read : demandez un jeton avec le bon scope à la personne qui administre le projet.
• 503 docs_disabled — le lecteur est désactivé sur la cible : ce n'est pas un problème de votre client, signalez-le à la personne qui administre le projet.
• 429 rate_limited — vous avez dépassé le plafond d'appels pour votre identification dans la fenêtre d'une minute : la réponse inclut Retry-After.

Ceci est la version rapide orientée tâche. Pour le contrat complet de l'endpoint (limites, ordre des vérifications, codes d'erreur, format des journaux), voir le runbook opérationnel docs/references/runbooks/docs-publishing.md et la référence API docs/references/api/docs-mcp.md, qui restent la source faisant autorité.