Conecta Claude Code o Codex mediante MCP

Usa el servidor MCP de Ordering.co para que Claude Code o Codex descubra y ejecute operaciones compatibles con tus permisos del proyecto. Empieza con una clave de solo lectura para comprobar tu identidad y consultar pedidos sin conceder acceso de escritura.

MCP expone un catálogo seleccionado de operaciones de API, no acceso irrestricto a toda la API. Usa Streamable HTTP y una clave MCP personal, no una API key ni un token de sesión del Dashboard.

Antes de empezar

Usa un proyecto y datos a los que tengas autorización para acceder. Prefiere un proyecto que no sea de producción para la primera conexión.
Instala Claude Code o Codex y completa por separado el inicio de sesión del cliente.
Usa una terminal Bash o Zsh para los comandos de esta guía. Inicia el asistente desde esa misma terminal para que herede la variable de entorno.
MCP debe estar habilitado para tu proyecto. El Dashboard muestra su disponibilidad; una URL de ejemplo no lo habilita.

¿Quién puede crear una clave desde el Dashboard?

La ruta de Settings requiere actualmente un administrador (nivel 0). El servidor MCP también admite administradores de negocio habilitados (nivel 2), pero eso no les da acceso a la ruta de Settings. Si no puedes abrirla, consulta el acceso con el administrador del proyecto; no uses la clave de otra persona.

1. Abre MCP y crea tu clave

Inicia sesión en la configuración MCP del Dashboard y confirma el proyecto seleccionado. También puedes navegar por Settings → Apps & developers → API & integrations → MCP (Claude Code & Codex); los nombres pueden aparecer traducidos según el idioma del Dashboard.
Si la página indica que MCP todavía no está disponible, confirma la disponibilidad del proyecto con tu administrador antes de continuar.
Copia la URL del servidor (Server URL) que muestra la página. Es específica de tu proyecto. La guía del Dashboard ya incluye esa URL.
En Tus claves MCP (Your MCP keys), selecciona Crear clave (Create key), escribe un nombre descriptivo y elige su vigencia. El valor actual por defecto es de 7 días y el máximo es de 365; usa las opciones que muestre tu proyecto.
Elige read para esta guía. Si se ofrece write, también incluye lecturas, pero permite cambios compatibles. Concédelo solo cuando necesites esos cambios.
Lee y acepta el aviso de datos antes de crear la clave. Los datos que lea el asistente se envían a su proveedor de IA; usa solo datos que tengas autorización para compartir con ese proveedor.
Copia la clave a un gestor de secretos aprobado. El valor completo se muestra una sola vez. Cierra el diálogo cuando lo hayas guardado de forma segura.

Tus claves pertenecen a tu usuario. No permiten eludir los permisos del proyecto, rol o recurso, ni autenticar llamadas directas a la API REST.

2. Haz que el cliente pueda leer la clave

En Bash o Zsh, ejecuta estas líneas y pega tu clave únicamente cuando se solicite la entrada oculta:

printf 'MCP key (hidden): '
read -r -s ORDERING_MCP_KEY
printf '\n'
export ORDERING_MCP_KEY

Así evitas incluir la clave en un comando o en el historial de la terminal. La variable dura durante esta sesión de shell y sus procesos hijos. Repite este paso en una terminal nueva o después de reemplazar una clave.

Nunca incluyas la clave real en .mcp.json, config.toml, argumentos de comandos, capturas, tickets ni control de versiones. Si usas un perfil de shell para conservarla, recuerda que guarda el valor en texto plano: mantenlo privado, fuera de repositorios y respaldos compartidos, o usa tu gestor de secretos aprobado.

3. Configura tu asistente

En todos los ejemplos, reemplaza https://api.ordering.co/mcp/YOUR_PROJECT_CODE por la URL completa del servidor copiada del Dashboard. Conserva la referencia a la variable de entorno. Elige el método de archivo de configuración o el de CLI de tu cliente, no ambos.

Claude Code

Crea o actualiza .mcp.json en la raíz de tu proyecto local. Si ya contiene otros servidores, agrega ordering sin reemplazarlos:

{
  "mcpServers": {
    "ordering": {
      "type": "http",
      "url": "https://api.ordering.co/mcp/YOUR_PROJECT_CODE",
      "headers": {
        "Authorization": "Bearer ${ORDERING_MCP_KEY}"
      }
    }
  }
}

Como alternativa, desde esa carpeta:

claude mcp add --transport http --scope project ordering \
  https://api.ordering.co/mcp/YOUR_PROJECT_CODE \
  --header 'Authorization: Bearer ${ORDERING_MCP_KEY}'

Conserva las comillas simples del encabezado. Mantienen la referencia a la variable para que Claude Code la expanda al conectarse, en lugar de guardar el secreto en la configuración.

Inicia claude en esa carpeta desde la terminal donde exportaste la clave. Revisa y aprueba el servidor MCP del proyecto cuando se solicite; después ejecuta /mcp dentro de Claude Code para comprobar la conexión. Agregar la configuración no demuestra por sí solo que el servidor sea accesible.

Codex

Agrega esta tabla a ~/.codex/config.toml o a .codex/config.toml en un proyecto de confianza. Si ya existe una entrada ordering, actualízala en vez de duplicar la tabla:

[mcp_servers.ordering]
url = "https://api.ordering.co/mcp/YOUR_PROJECT_CODE"
bearer_token_env_var = "ORDERING_MCP_KEY"

Como alternativa:

codex mcp add ordering \
  --url https://api.ordering.co/mcp/YOUR_PROJECT_CODE \
  --bearer-token-env-var ORDERING_MCP_KEY

bearer_token_env_var es el nombre de la variable, no su valor. Codex la lee y envía la clave como token bearer.

Ejecuta codex mcp list para confirmar el registro. Inicia codex desde la misma terminal y usa /mcp para inspeccionar el servidor. Ver una entrada en la lista no equivale a una solicitud autenticada exitosa; completa las comprobaciones siguientes. Si usas la extensión del IDE, su proceso también debe recibir la variable de entorno.

Estas instrucciones cubren Claude Code y Codex, no los conectores web de claude.ai o ChatGPT. No supongas que esos conectores aceptan esta configuración de clave bearer ni que este servidor ofrece un inicio de sesión OAuth.

4. Comprueba la conexión con solicitudes reales

Pídele a tu asistente:

Who am I in Ordering?

Confirma que realmente llame a whoami y que el proyecto, usuario, rol, alcance y vencimiento de la clave correspondan a la conexión esperada. No compartas la respuesta completa: contiene información personal y del proyecto.

Después pídele:

List the last 5 orders

El asistente debe descubrir la operación pertinente y leer los pedidos más recientes dentro de tus permisos. Una lista vacía puede ser válida; no significa que la autenticación haya fallado. Pídele minimizar la información de clientes y no publiques los resultados como evidencia de configuración. Ninguna de estas consultas requiere escritura.

Herramientas y cobertura de API

Herramienta	Función
`whoami`	Identifica el proyecto, usuario, rol, alcance y vencimiento de la clave de la conexión.
`search_operations`	Busca operaciones del catálogo disponibles para tu rol y el alcance de tu clave.
`describe_operation`	Describe las entradas de una operación, incluidos los campos permitidos para escribir.
`read_operation`	Ejecuta una operación de lectura compatible con tus permisos.
`write_operation`	Ejecuta una escritura admitida explícitamente y con campos permitidos. Solo está disponible para claves con alcance `write`.

Usa el descubrimiento en lugar de adivinar identificadores de operaciones o enviar rutas arbitrarias de API. La API sigue autorizando cada operación y recurso. Una clave de escritura no habilita todos los endpoints REST ni todos los campos de una operación admitida. Este catálogo MCP no expone DELETE ni descargas de archivos; seleccionar write tampoco habilita escrituras fuera del catálogo, como cambios financieros de reembolso.

Mantén habilitada la aprobación del cliente para cada escritura. Los cambios pueden activar efectos operativos, como notificaciones y webhooks. Tras un timeout o error del servidor en una escritura, lee el registro afectado antes de reintentar; no supongas que el reintento se deduplica.

Usa la Referencia de API para integraciones REST directas y su autenticación, no para deducir disponibilidad en MCP. Para la presentación comercial, consulta API y MCP.

Reemplaza o revoca una clave

Antes de que venza una clave, crea su reemplazo en la configuración MCP del mismo proyecto. Una clave vencida puede ofrecer Crear un reemplazo (Create a replacement) con el nombre y alcance precargados; es una clave nueva, no una extensión de la anterior.
Actualiza ORDERING_MCP_KEY en el entorno del proceso y reinicia el asistente para que reciba el nuevo valor. Comprueba whoami otra vez.
Revoca la clave anterior cuando funcione el reemplazo. Si se ha comprometido una clave, revócala inmediatamente en vez de esperar al reemplazo.
Para desconectar, revoca la clave en el Dashboard y elimina la entrada del servidor en el cliente. unset ORDERING_MCP_KEY borra la variable de esta terminal, pero no revoca la clave ni la borra de clientes que ya están ejecutándose.

Solución de problemas

Síntoma	Qué revisar
No puedes abrir Settings o MCP no está disponible	Confirma el acceso de administrador y la disponibilidad del proyecto. No eludas la ruta ni uses una clave ajena.
Falta la variable de entorno	Expórtala en la terminal que inicia el cliente y reinicia el cliente. No imprimas el secreto para comprobarlo.
`401`, token inválido o vencido	Usa una clave MCP del mismo proyecto, no una API key/JWT. Reemplaza una clave vencida o revocada; una clave antigua sin aceptación del aviso de datos también requiere reemplazo.
`403`	El propietario de la clave debe seguir habilitado y ser elegible. La API puede denegar por separado una operación o recurso. El endpoint MCP no acepta solicitudes con un encabezado de navegador `Origin`.
`404`	Copia nuevamente la URL y confirma que MCP esté habilitado para ese proyecto. Tener una URL no establece disponibilidad.
`405` al abrir la URL en un navegador	MCP es un transporte POST, no una página web. Conecta mediante el cliente en lugar de probar con un GET del navegador.
No aparece `write_operation` o la operación es desconocida	Comprueba el alcance de la clave y descubre las operaciones disponibles. No todas las operaciones de API están en MCP.
Error de validación	Consulta `describe_operation` y envía solo parámetros y campos compatibles.
Límite de solicitudes, timeout o API no disponible	Respeta los límites y reintenta las lecturas más tarde. Si una escritura tiene un resultado incierto, consulta el registro antes de reintentar.

Si un cliente rechaza un comando, consulta claude mcp add --help o codex mcp add --help y compara la versión instalada con la documentación vigente de Claude Code MCP o Codex MCP. Al pedir soporte, comparte solo la versión del cliente y el error sin datos sensibles; nunca una clave, encabezado de autorización ni respuesta con datos de clientes.

Antes de empezar​

1. Abre MCP y crea tu clave​

2. Haz que el cliente pueda leer la clave​

3. Configura tu asistente​

Claude Code​

Codex​

4. Comprueba la conexión con solicitudes reales​

Herramientas y cobertura de API​

Reemplaza o revoca una clave​

Solución de problemas​