Claude Code oder Codex CLI mit dem Dokumentations-MCP-Reader verbinden

Der Dokumentations-MCP-Reader von mayo ist ein öffentlicher, schreibgeschützter Endpoint: Er stellt nur den Snapshot der bereits veröffentlichten Guides bereit, niemals eine Schreiboberfläche. Er unterscheidet sich vom MCP-Server human-docs, den der Autor lokal nutzt (dieser schreibt den Entwurf in das eigene Checkout): Hier verbindest du einen Client mit POST /api/docs/mcp, dem entfernten HTTP-Endpoint.

Was du vor dem Start brauchst

• Ein Bearer-Token mit dem Scope docs:read, bereitgestellt von der Person, die das Projekt administriert. Es ist niemals dein persönliches Produkt-Token: Es ist eine eigene Anmeldeinformation für den Dokumentations-Reader.
• Das Token muss in einer Umgebungsvariable auf deinem Rechner gespeichert werden (hier DOCS_MCP_READER_TOKEN genannt), niemals in einer versionierten Konfigurationsdatei.
• Die Endpoint-URL: https://app.mayoeasyorder.com/api/docs/mcp.

export DOCS_MCP_READER_TOKEN="<dein-token>"

Schritt 1 — Client konfigurieren

Claude Code

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

Erwartetes Ergebnis: claude mcp list listet den Server mayo-docs auf.

Codex CLI

Füge Folgendes zu deiner ~/.codex/config.toml hinzu:

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

Erwartetes Ergebnis: Beim Start listet Codex CLI mayo-docs unter den konfigurierten MCP-Servern auf.

Schritt 2 — Verbindung prüfen

Rufe vom konfigurierten Client aus das Tool docs_status auf (keine Argumente). Die Antwort enthält die Felder productRevision, snapshotRevision, languages, guideCount, publishedAt, guideIds, deploymentReceipt, publishedJobIds und guides. Wenn noch nichts veröffentlicht wurde, kommen die Felder leer zurück (null/[]/0): Das ist kein Fehler, sondern der legitime Zustand vor der Veröffentlichung.

Alternativ kannst du direkt per HTTP prüfen:

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

Erwartetes Ergebnis: eine 200-Antwort mit einem JSON-RPC-Payload, das das Ergebnis von docs_status in der oben beschriebenen Form enthält.

Schritt 3 — Die übrigen Lese-Tools nutzen

Sobald du verbunden bist, stehen dir vier Tools zur Verfügung, alle schreibgeschützt:

Wenn etwas nicht funktioniert

• 401 unauthorized — der Bearer fehlt, ist fehlerhaft, unbekannt, oder die Reader-Konfiguration auf dem Ziel wurde komplett abgelehnt: Prüfe, ob du DOCS_MCP_READER_TOKEN korrekt exportiert hast, bevor du den Client startest.
• 403 forbidden_scope — das Token ist gültig, hat aber nicht den Scope docs:read: Fordere bei der Person, die das Projekt administriert, ein Token mit dem richtigen Scope an.
• 503 docs_disabled — der Reader ist auf dem Ziel deaktiviert: Das ist kein Problem deines Clients, melde es der Person, die das Projekt administriert.
• 429 rate_limited — du hast das Aufruflimit für deine Anmeldeinformation im Ein-Minuten-Fenster überschritten: Die Antwort enthält Retry-After.

Dies ist die schnelle, aufgabenorientierte Fassung. Für den vollständigen Vertrag des Endpoints (Limits, Prüfreihenfolge, Fehlercodes, Log-Format) siehe das operative Runbook docs/references/runbooks/docs-publishing.md und die API-Referenz docs/references/api/docs-mcp.md, die weiterhin die maßgebliche Quelle bleiben.