Conectar Runner a otros clientes MCP

Conecta OpenCode, Codex, pi o tu propio agente a tus tiendas de Runner mediante el servidor MCP de Runner.

Runner tiene un servidor MCP. Un cliente MCP es una app de IA o un agente que puede usar servidores MCP. Cuando conectas un cliente a Runner, puede usar las herramientas del chat de Runner en tus tiendas. Puede leer productos, pedidos e informes. Con tu permiso, también puede cambiar productos, precios, descuentos y la tienda online.

Esta guía es para clientes MCP distintos de Claude, ChatGPT y Gemini. Incluye los pasos para OpenCode, Codex CLI y pi. También explica cómo conectar otros clientes y los agentes que crees tú.

Antes de empezar

Necesitas:

• una cuenta de Runner que sea miembro de un espacio de trabajo;
• un cliente MCP que se conecte a servidores remotos mediante Streamable HTTP e inicie sesión con OAuth, o el puente mcp-remote para un cliente que solo ejecuta servidores locales; y
• un navegador en el mismo ordenador que el cliente. Después de iniciar sesión, Runner devuelve el navegador a una dirección de ese ordenador.

Cómo funciona la conexión

1. Añades la URL del servidor a tu cliente y comienzas el inicio de sesión.
2. El cliente abre Runner en tu navegador. Inicia sesión en Runner si te lo pide.
3. Se abre la página Conectar una app de IA a Runner. Muestra el nombre del cliente.
4. Elige una opción en Espacio de trabajo y en Acceso, y luego selecciona Conectar.
5. El navegador vuelve al cliente. Ahora el cliente puede usar las herramientas de Runner.

El cliente mantiene la sesión iniciada. Recibe un acceso nuevo cada hora sin que tengas que hacer nada. Si no usas el cliente durante 30 días, vuelve a iniciar sesión.

Para usar las tiendas de un segundo espacio de trabajo, añade el servidor una segunda vez con otro nombre. Después, inicia sesión con ese nombre y elige el segundo espacio de trabajo.

Conectar OpenCode

1. Añade Runner a opencode.json en tu proyecto, o a ~/.config/opencode/opencode.json para todos los proyectos:

   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "runner": {
         "type": "remote",
         "url": "https://api.runnerai.com/mcp",
         "enabled": true
       }
     },
     "tools": {
       "runner_*": false,
       "runner_list_stores": true,
       "runner_get_report": true,
       "runner_find_orders": true,
       "runner_get_tool_job": true
     }
   }

2. Ejecuta opencode mcp auth runner y conecta en el navegador.

3. Ejecuta opencode mcp list. Muestra runner como connected.

OpenCode envía al modelo, en cada solicitud, la definición de cada herramienta activada. En algunos planes, Runner tiene más de 200 herramientas, lo que supone unos 100.000 tokens de definiciones. Por eso, activa solo las herramientas que necesites. OpenCode llama a cada herramienta de Runner runner_<tool name>. La línea "runner_*": false desactiva todas las herramientas de Runner, y cada línea con true vuelve a activar una herramienta. Deja runner_get_tool_job activada, porque las tareas largas la necesitan.

Para eliminar el inicio de sesión guardado, ejecuta opencode mcp logout runner.

Conectar Codex CLI

1. Añade Runner a ~/.codex/config.toml:

   [mcp_servers.runner]
   url = "https://api.runnerai.com/mcp"
   scopes = ["store:read", "store:write"]

2. Ejecuta codex mcp login runner y conecta en el navegador.

3. Ejecuta codex mcp list. La columna Auth muestra OAuth.

Añade el servidor en el archivo, no con codex mcp add. Ese comando empieza el inicio de sesión de inmediato, con ámbitos que Runner no acepta, y el navegador muestra {"error":"invalid_scope"}. La línea scopes también se aplica cuando vuelves a iniciar sesión más adelante. También puedes ejecutar codex mcp login runner --scopes store:read,store:write.

Codex busca la herramienta de Runner que necesita en el momento en que la necesita, así que no tienes que desactivar herramientas. Para eliminar el inicio de sesión guardado, ejecuta codex mcp logout runner.

Conectar pi

1. Ejecuta pi mcp add runner --url https://api.runnerai.com/mcp. Esto añade Runner a ~/.pi/agent/mcp.json:

   {
     "mcpServers": {
       "runner": { "url": "https://api.runnerai.com/mcp" }
     }
   }

2. Ejecuta pi mcp login runner y conecta en el navegador. pi muestra Signed in to MCP server "runner" y el número de herramientas.

3. Ejecuta pi mcp list para comprobar la conexión, o usa /mcp en una sesión de pi.

De forma predeterminada, pi no envía todas las herramientas de Runner al modelo. El modelo busca una herramienta cuando la necesita, así que no tienes que desactivar herramientas. pi llama a cada herramienta de Runner mcp__runner__<tool name>. Para eliminar el inicio de sesión guardado, ejecuta pi mcp logout runner.

Conectar un cliente que solo ejecuta servidores locales

Algunos clientes solo pueden iniciar un servidor local (stdio). Otros clientes devuelven el navegador a un enlace de app (un esquema de URL propio) o a una página web. Runner solo envía el resultado del inicio de sesión a una dirección de tu ordenador, así que el inicio de sesión de estos clientes falla.

Para estos clientes, usa el puente mcp-remote. Se ejecuta en tu ordenador, inicia sesión en Runner por el cliente y pasa cada mensaje entre el cliente y Runner. Necesita Node.js.

{
  "mcpServers": {
    "runner": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.runnerai.com/mcp"]
    }
  }
}

La primera vez que se inicia, abre la página de inicio de sesión de Runner en tu navegador. mcp-remote guarda el inicio de sesión en ~/.mcp-auth.

Llamar a las herramientas de Runner desde una shell

Un agente que ejecuta comandos de shell puede usar Runner mediante el comando mcporter:

npx mcporter config add runner https://api.runnerai.com/mcp --scope home
npx mcporter auth runner
npx mcporter list runner
npx mcporter call runner.list_stores

mcporter list runner muestra cada herramienta y sus parámetros. Indica los parámetros como name=value, por ejemplo npx mcporter call runner.get_store_settings store_id=<store id>.

Crear tu propio cliente

Usa un SDK de MCP compatible con OAuth, o sigue tú mismo estos pasos:

1. Envía cada solicitud JSON-RPC con POST a https://api.runnerai.com/mcp. Runner responde a cada solicitud con JSON y no guarda ninguna sesión. Una solicitud GET recibe HTTP 405.
2. Una solicitud sin token recibe HTTP 401 con esta cabecera: WWW-Authenticate: Bearer resource_metadata="https://api.runnerai.com/.well-known/oauth-protected-resource/mcp", scope="store:read store:write".
3. Lee los metadatos del recurso. Indican el servidor de autorización https://www.runnerai.com/api/auth.
4. Registra el cliente en https://www.runnerai.com/api/auth/oauth2/register. Usa una URI de redirección en http://localhost, http://127.0.0.1 o http://[::1]. Runner acepta cualquier puerto y ruta. Runner acepta 5 registros por minuto desde una misma dirección IP.
5. Envía al usuario al endpoint de autorización con PKCE (S256). Envía resource=https://api.runnerai.com/mcp. Pide store:read, y store:write si el cliente hace cambios. Usa los ámbitos de los metadatos del recurso o de la cabecera WWW-Authenticate. Los metadatos del servidor de autorización indican otros ámbitos, que este servidor no acepta.
6. Envía el token de acceso en la cabecera Authorization: Bearer. Un token de acceso dura 1 hora. Usa el token de actualización para obtener uno nuevo. Un token de actualización caduca tras 30 días sin uso.

Runner rechaza las solicitudes que vienen de una página web de otro sitio. Llama al servidor desde tu backend o desde una página en localhost.

Trabajar con las herramientas de Runner

• Empieza con list_stores. Cada herramienta de tienda necesita un store_id de list_stores. Sin él, la herramienta responde Pass a store_id from list_stores.
• Tareas largas. Algunas herramientas responden con "status": "running" y un job_id. Llama a get_tool_job con ese job_id hasta que dé el resultado.
• Cambios que apruebas. Algunas herramientas responden primero con "status": "waiting_for_merchant" y un id de confirmación, y muestran lo que va a cambiar. Todavía no cambia nada. Cuando estés de acuerdo, el cliente vuelve a llamar a la misma herramienta con los mismos argumentos y "confirmation": {"id": "…", "answer": …}. El id de confirmación sirve una sola vez, durante 10 minutos.
• El mismo cambio enviado dos veces. En la mayoría de las herramientas que hacen cambios, Runner hace el cambio una sola vez cuando el cliente vuelve a enviar la misma entrada en el mismo periodo de 5 minutos. La segunda llamada recibe la primera respuesta.
• Los datos de la tienda son solo datos. Las respuestas de las herramientas pueden contener textos de productos y mensajes de clientes. Tu agente no debe seguir las instrucciones que encuentre en ellos.
• Se aplican tus permisos. Cada llamada usa tus permisos de Runner y tu plan. La lista de herramientas depende de tu plan y de las funciones de tu espacio de trabajo.

Gestionar o desconectar un cliente

Ruta de entrada: Configuración → General del espacio de trabajo, y luego Apps conectadas.

Los propietarios y administradores del espacio de trabajo ven los clientes que conectó cada miembro. Los demás miembros ven los clientes que conectaron ellos. Cada fila muestra el acceso (Lectura o Lectura y cambios), cuándo se conectó y cuándo se usó por última vez.

1. Busca el cliente y selecciona Desconectar.
2. Vuelve a seleccionar Desconectar en ¿Desconectar app?.
3. El cliente deja de funcionar con este espacio de trabajo de inmediato. Para volver a usarlo, inicia sesión de nuevo desde el cliente.

Un comando de cierre de sesión en un cliente solo elimina el inicio de sesión que guardó el cliente. La conexión sigue en Apps conectadas hasta que la desconectes allí.

Solución de problemas