Saltar al contenido principal

Conecta tu asistente de IA con Ordering 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.

Conecta con un prompt​

Pega este texto en un agente de terminal del equipo donde corre tu cliente MCP:

Connect me to Ordering.co: clone https://github.com/Ordering-co/ordering-dev-quickstart to ~/ordering-dev-quickstart (or pull it if I already have it), then read its SETUP.md and follow it step by step.
  1. El agente sigue SETUP.md del quickstart, inicia login start --install y te entrega un enlace privado y un código de verificación. /connect/ necesita ese pairing; la URL sola no es un instalador independiente.
  2. Abre el enlace, inicia sesión con Dashboard o Accounts (Billing), elige el proyecto y escribe el código del agente. Usa tu propia cuenta habilitada de administrador o business manager; revisa el aviso de datos y los permisos.
  3. Conserva MCP read salvo que necesites cambios admitidos. La API REST es una opción separada, marcada por defecto, con permisos amplios de tu usuario y sin vencimiento. Desmárcala si no la necesitas: MCP read no convierte REST en solo lectura. Una credencial REST existente del mismo proyecto se conserva con un aviso si no llega otra; desmarcar no la elimina ni la revoca.
  4. Espera el resultado final de login wait en el terminal. El navegador confirma entrega de credenciales, no instalación. El terminal comprueba identidad, launcher y registro de cada cliente detectado. Si el login funcionó y falló la instalación, reintenta ./ordering install y revisa ./ordering clients; no repitas login solo por ese fallo.
  5. Recarga/reinicia tu cliente, acepta su solicitud normal de confianza MCP y pregunta «¿Quién soy en Ordering?». Comprueba que ejecuta whoami con la cuenta/proyecto deseados. Después descubre, describe y lee los últimos cinco pedidos, pidiendo solo los campos necesarios. Un resultado vacío permitido también es válido.

Usa únicamente datos que puedas compartir con el proveedor de IA. No hay sandbox automático; no publiques claves, códigos de pairing, identidades completas ni respuestas de clientes como evidencia.

Requisitos y compatibilidad​

El pairing usa Bash, curl y OpenSSL; el registro global requiere Node.js 22+ y npm. Usa macOS/Linux o clientes dentro de WSL. Una sesión remota/cloud instala en el equipo de ejecución, no en la computadora donde inicias sesión. WSL no configura apps nativas de Windows. Mantén el checkout en su ubicación: si lo mueves o cambias Node, ejecuta install otra vez.

ClienteQué admite el instaladorQué debes verificar después
Claude Code, CodexConfiguración nativa de usuario detectada y launcher stdioRecarga/confianza, herramientas del runtime y llamada autenticada en el cliente
Claude Desktop, Cursor, VS CodeConfiguración global nativa detectadaHabilitación/recarga; VS Code necesita MCP/Copilot en modo Agent
OpenCodeConfiguración según versión; activación del runtime en versión 2Ubicación del runtime e identidad/lectura dentro del cliente
Otros clientes admitidosSolo los detectados por el adaptador fijadoNo implica que todas las apps o LLMs estén probados
PiNecesita un adaptador MCP adicional; se omite automáticamenteInstala y configura su adaptador compatible por separado
Conectores cloud y apps nativas WindowsEl instalador local/WSL no los configuraUsa su conexión específica compatible; el cloud no lee configs locales

Las pruebas de formatos y protocolo con fixtures son distintas de las pruebas con clientes reales. Registra versión de sistema/cliente → detección → lectura del registro → runtime → llamada autenticada → recarga/confianza pendiente. Un registro o una prueba del launcher no demuestra conexión en cada GUI. Consulta la referencia de clientes del quickstart para cobertura y dependencias de release.

Servidor, quickstart y plugin​

  • Servidor MCP: autoriza un catálogo seleccionado según proyecto, rol, alcance y campos admitidos; no expone toda la API.
  • Quickstart: pairing, credenciales locales, launcher, registro de clientes y helper opcional REST/OpenAPI.
  • Plugin y skill: conocimiento opcional de plataforma para Claude Code/Codex, instalado aparte. Sigue el README de su versión para evitar servidores duplicados del plugin antiguo o del proyecto. Instalar quickstart no instala automáticamente el plugin.

Si un repositorio/marketplace rechaza el acceso, usa la alternativa manual o solicita acceso. Una cuenta Ordering no concede acceso GitHub. Nunca introduzcas claves en argumentos de instalación del plugin ni en el chat.

Renovar, recuperar y desconectar​

cd ~/ordering-dev-quickstart
./ordering doctor
./ordering clients
./ordering login --install # renueva con login en navegador

El pairing usa 30 días por defecto; una clave MCP manual usa 7, actualmente hasta 365. Lee el alcance/vencimiento real en doctor y whoami. Recoge el resultado final, reintenta install si falló un registro y recarga los clientes. Verifica la nueva clave antes de revocar la anterior; ante una filtración, revoca de inmediato.

AcciónResultado localAcceso del servidor
uninstallRetira registros sin cambios que pertenecen al launcher; conserva credencialesLas claves siguen válidas
logout / disconnectRetira integración y vacía ambas claves locales MCP/REST; conserva proyectoRevoca cada clave por separado en Dashboard
reset --client codex --installLogout, nuevo pairing y registroLas claves anteriores siguen válidas hasta revocarlas

Lee el resultado del terminal: registros modificados o un fallo al retirar OpenCode quedan para reintento. La instalación conserva otros MCPs, entradas deshabilitadas/conflictivas y backups privados. Una configuración de proyecto con mayor prioridad puede ocultar la global; revísala antes de migrar Ordering explícitamente. No borres otros servidores ni reinicies servicios compartidos. Consulta el diagnóstico del quickstart.

Alternativa desde tu terminal​

El prompt anterior sigue SETUP.md. Si prefieres ejecutar el mismo flujo tú mismo, revisa primero el alcance de configuración global y usa una ubicación estable:

git clone https://github.com/Ordering-co/ordering-dev-quickstart.git ~/ordering-dev-quickstart
cd ~/ordering-dev-quickstart
./ordering login start --client codex --install
./ordering login wait
./ordering doctor
./ordering clients

Usa --client claude para identificar Claude Code. Si el checkout ya existe, actualízalo allí con git pull --ff-only en lugar de sobrescribirlo. Recoge el resultado final y verifica una llamada dentro del cliente; el registro global no prueba todas las apps.

Quickstart y el plugin opcional son públicos en la organización Ordering-co; clonarlos e instalar el marketplace no requiere pertenecer a GitHub. Conectar con datos de un proyecto requiere tu propia cuenta Ordering elegible y consentimiento. MCP también puede conectarse con la alternativa manual sin clonar ninguno.

Contrato del servidor MCP​

Cada proyecto de Ordering.co tiene su propia Server URL del MCP. Copia la URL completa del Dashboard; su formato canónico es:

https://api.ordering.co/mcp/YOUR_PROJECT_CODE

Sustituye YOUR_PROJECT_CODE por el código real del proyecto. El hostname es api.ordering.co y la ruta incluye /mcp/ seguido del código del proyecto. No hay un endpoint compartido sin proyecto. El cliente envía la clave MCP personal como Authorization: Bearer ${ORDERING_MCP_KEY} mediante Streamable HTTP. Conserva la clave en el entorno privado del helper o un gestor de secretos y mantén referencias de entorno en las configuraciones. Una API key REST en X-Api-Key es una credencial distinta para peticiones REST.

Alternativa manual​

Úsala cuando no esté disponible el pairing o el acceso al repositorio, o necesites configurar un cliente específico. Estos pasos requieren un entorno privado de terminal y no configuran un proceso desktop ya abierto.

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.
  • En este método manual, usa Bash o Zsh e inicia el asistente desde esa terminal para que herede la variable de entorno. El launcher del quickstart no necesita esa exportación.
  • 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​

  1. 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.
  2. Coming soon indica que MCP está desactivado en el proyecto. Cuando se habilita, el panel muestra Server URL, Your MCP keys y las instrucciones de conexión. Si el estado no carga, usa Retry antes de consultar a tu administrador.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.

El panel enumera las claves del usuario que inició sesión y muestra si cada una está activa, vencida o revocada. 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​

HerramientaFunción
whoamiIdentifica el proyecto, usuario, rol, alcance y vencimiento de la clave de la conexión.
search_operationsBusca operaciones del catálogo disponibles para tu rol y el alcance de tu clave.
describe_operationDescribe las entradas de una operación, incluidos los campos permitidos para escribir.
read_operationEjecuta una operación de lectura compatible con tus permisos.
write_operationEjecuta 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​

Con el quickstart, renueva con ~/ordering-dev-quickstart/ordering login --install, recoge el resultado final del instalador, recarga los clientes y verifica whoami. Consulta el vencimiento real en doctor o whoami; no supongas el valor por defecto. ./ordering uninstall elimina registros propios sin modificar y conserva las credenciales. ./ordering logout retira esos registros y borra ambas credenciales locales MCP/REST, pero no revoca la clave remota: revoca cada clave por separado en el Dashboard al desconectarte.

  • 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íntomaQué revisar
No puedes abrir Settings o MCP no está disponibleConfirma el acceso de administrador y la disponibilidad del proyecto. No eludas la ruta ni uses una clave ajena.
Falta la variable de entornoExpórtala en la terminal que inicia el cliente y reinicia el cliente. No imprimas el secreto para comprobarlo.
401, token inválido o vencidoUsa 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.
403El 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.
404Copia 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 navegadorMCP 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 desconocidaComprueba el alcance de la clave y descubre las operaciones disponibles. No todas las operaciones de API están en MCP.
Error de validaciónConsulta describe_operation y envía solo parámetros y campos compatibles.
Límite de solicitudes, timeout o API no disponibleRespeta 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.