Conectar Claude Code o Codex CLI al lector MCP de la documentación

DesarrolladoresCategoría: Guía rápidaIdioma: españolv5fcfd91Verificada en mayo 5fcfd91 el 22 de septiembre de 2026

Antes de empezarRolUn token bearer con scope docs:read, asignado por quien administra el proyecto: sin una credencial válida, cada llamada responde 401.ConfiguraciónEl lector documental debe estar activo en el destino (variable de entorno del lado del servidor, fuera del control de quien lee esta guía): si está apagado, cada solicitud responde 503 docs_disabled antes de cualquier acceso a los datos., Se necesita al menos una revisión de documentación ya publicada para que docs_search, docs_get y docs_list devuelvan resultados no vacíos; sin publicación, docs_status permanece legítimamente vacío.Si no ves esta opción, pide ayuda al administrador de tu cuenta.

El lector MCP de la documentación de mayo es un endpoint público y de solo lectura: expone únicamente la instantánea de las guías ya publicadas, nunca una superficie de escritura. Es distinto del servidor MCP human-docs que usa el autor en local (ese escribe el borrador en su propio checkout): aquí estás conectando un cliente a POST /api/docs/mcp, el endpoint HTTP remoto.

Qué necesitas antes de empezar

Un token bearer con scope docs:read, proporcionado por quien administra el proyecto. Nunca es tu token personal del producto: es una credencial dedicada al lector documental.
El token debe guardarse en una variable de entorno de tu máquina (llamada aquí DOCS_MCP_READER_TOKEN), nunca escrito en un archivo de configuración versionado.
La URL del endpoint: https://app.mayoeasyorder.com/api/docs/mcp.

export DOCS_MCP_READER_TOKEN="<tu-token>"

Paso 1 — Configura el cliente

Claude Code

bash

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

Resultado esperado: claude mcp list muestra el servidor mayo-docs.

Codex CLI

Añade esto a tu ~/.codex/config.toml:

toml

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

Resultado esperado: al arrancar, Codex CLI muestra mayo-docs entre los servidores MCP configurados.

Paso 2 — Verifica la conexión

Desde el cliente configurado, llama a la herramienta docs_status (sin argumentos). La respuesta contiene los campos productRevision, snapshotRevision, languages, guideCount, publishedAt, guideIds, deploymentReceipt, publishedJobIds y guides. Si todavía no se ha publicado nada, los campos vuelven vacíos (null/[]/0): no es un error, es el estado legítimo de pre-publicación.

Como alternativa, verifica mediante HTTP directo:

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

Resultado esperado: una respuesta 200 con un payload JSON-RPC que contiene el resultado de docs_status en la forma descrita arriba.

Paso 3 — Usa las demás herramientas de lectura

Una vez conectado, tienes disponibles cuatro herramientas, todas de solo lectura:


Herramienta	Qué hace
`docs_status`	estado de la instantánea publicada
`docs_search`	búsqueda de texto completo entre las guías publicadas (`query`, `language`, `audience` opcional, `limit` 1-50)
`docs_get`	recupera una guía por `guideId` o por `route` (exactamente uno de los dos), en una `language`
`docs_list`	lista paginada de las guías publicadas (`language`, filtros opcionales `audience`/`category`)

Si algo no funciona

401 unauthorized — el bearer está ausente, mal formado, desconocido, o la configuración del lector en el destino fue rechazada por completo: comprueba que exportaste correctamente DOCS_MCP_READER_TOKEN antes de lanzar el cliente.
403 forbidden_scope — el token es válido pero no tiene el scope docs:read: solicita un token con el scope correcto a quien administra el proyecto.
503 docs_disabled — el lector está apagado en el destino: no es un problema de tu cliente, repórtalo a quien administra el proyecto.
429 rate_limited — has superado el límite de llamadas para tu credencial en la ventana de un minuto: la respuesta incluye Retry-After.

Esta es la versión rápida orientada a la tarea. Para el contrato completo del endpoint (límites, orden de las comprobaciones, códigos de error, formato de los registros) consulta el runbook operativo docs/references/runbooks/docs-publishing.md y la referencia de API docs/references/api/docs-mcp.md, que siguen siendo la fuente autorizada.

Empieza gratis con mayo Explorar la documentación