Conectar o Runner a outros clientes MCP

Conecte o OpenCode, o Codex, o pi ou seu próprio agente às suas lojas do Runner pelo servidor MCP do Runner.

O Runner tem um servidor MCP. Um cliente MCP é um app de IA ou um agente que pode usar servidores MCP. Quando você conecta um cliente ao Runner, ele pode usar as ferramentas do chat do Runner em suas lojas. Ele pode ler produtos, pedidos e relatórios. Com sua permissão, ele também pode alterar produtos, preços, descontos e a loja virtual.

Este guia é para clientes MCP diferentes do Claude, do ChatGPT e do Gemini. Ele traz os passos para o OpenCode, o Codex CLI e o pi. Também explica como conectar outros clientes e agentes criados por você.

Antes de começar

Você precisa de:

• uma conta do Runner que seja membro de um workspace;
• um cliente MCP que se conecte a servidores remotos via Streamable HTTP e faça login com OAuth, ou a ponte mcp-remote para um cliente que só executa servidores locais; e
• um navegador no mesmo computador do cliente. Depois do login, o Runner envia o navegador de volta para um endereço nesse computador.

Como a conexão funciona

1. Você adiciona a URL do servidor no cliente e inicia o login.
2. O cliente abre o Runner no navegador. Entre no Runner se for solicitado.
3. A página Conectar um app de IA ao Runner é aberta. Ela mostra o nome do cliente.
4. Escolha uma opção em Workspace e em Acesso e selecione Conectar.
5. O navegador volta para o cliente. Agora o cliente pode usar as ferramentas do Runner.

O cliente mantém o login. Ele recebe um novo acesso a cada hora, sem que você precise fazer nada. Se você não usar o cliente por 30 dias, faça login novamente.

Para usar as lojas de um segundo workspace, adicione o servidor uma segunda vez com outro nome. Depois, faça login com esse nome e escolha o segundo workspace.

Conectar o OpenCode

1. Adicione o Runner ao opencode.json do seu projeto, ou ao ~/.config/opencode/opencode.json para todos os projetos:

   {
     "$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. Execute opencode mcp auth runner e conecte no navegador.

3. Execute opencode mcp list. Ele mostra runner como connected.

O OpenCode envia ao modelo, em cada solicitação, a definição de cada ferramenta ativada. Em alguns planos, o Runner tem mais de 200 ferramentas, o que dá cerca de 100.000 tokens de definições. Por isso, ative só as ferramentas de que você precisa. O OpenCode chama cada ferramenta do Runner de runner_<tool name>. A linha "runner_*": false desativa todas as ferramentas do Runner, e cada linha com true ativa uma ferramenta de novo. Mantenha runner_get_tool_job ativada, porque as tarefas longas precisam dela.

Para remover o login salvo, execute opencode mcp logout runner.

Conectar o Codex CLI

1. Adicione o Runner ao ~/.codex/config.toml:

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

2. Execute codex mcp login runner e conecte no navegador.

3. Execute codex mcp list. A coluna Auth mostra OAuth.

Adicione o servidor no arquivo, não com codex mcp add. Esse comando inicia um login na hora, com escopos que o Runner não aceita, e o navegador mostra {"error":"invalid_scope"}. A linha scopes também vale quando você fizer login de novo mais tarde. Você também pode executar codex mcp login runner --scopes store:read,store:write.

O Codex encontra a ferramenta do Runner de que precisa no momento em que precisa dela, então você não precisa desativar ferramentas. Para remover o login salvo, execute codex mcp logout runner.

Conectar o pi

1. Execute pi mcp add runner --url https://api.runnerai.com/mcp. Isso adiciona o Runner ao ~/.pi/agent/mcp.json:

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

2. Execute pi mcp login runner e conecte no navegador. O pi mostra Signed in to MCP server "runner" e o número de ferramentas.

3. Execute pi mcp list para verificar a conexão, ou use /mcp em uma sessão do pi.

Por padrão, o pi não envia todas as ferramentas do Runner ao modelo. O modelo encontra uma ferramenta quando precisa dela, então você não precisa desativar ferramentas. O pi chama cada ferramenta do Runner de mcp__runner__<tool name>. Para remover o login salvo, execute pi mcp logout runner.

Conectar um cliente que só executa servidores locais

Alguns clientes só conseguem iniciar um servidor local (stdio). Outros clientes enviam o navegador de volta para um link de app (um esquema de URL próprio) ou para uma página web. O Runner só envia o resultado do login para um endereço em seu computador, por isso o login desses clientes falha.

Para esses clientes, use a ponte mcp-remote. Ela roda em seu computador, faz login no Runner pelo cliente e passa cada mensagem entre o cliente e o Runner. Ela precisa do Node.js.

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

Na primeira vez que a ponte é iniciada, a página de login do Runner abre no navegador. O mcp-remote guarda o login em ~/.mcp-auth.

Chamar ferramentas do Runner a partir de um shell

Um agente que executa comandos de shell pode usar o Runner pelo 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 mostra cada ferramenta e seus parâmetros. Informe os parâmetros como name=value, por exemplo npx mcporter call runner.get_store_settings store_id=<store id>.

Criar seu próprio cliente

Use um SDK de MCP com suporte a OAuth, ou siga você mesmo estas etapas:

1. Envie cada solicitação JSON-RPC com POST para https://api.runnerai.com/mcp. O Runner responde a cada solicitação com JSON e não mantém sessão. Uma solicitação GET recebe HTTP 405.
2. Uma solicitação sem token recebe HTTP 401 com este cabeçalho: WWW-Authenticate: Bearer resource_metadata="https://api.runnerai.com/.well-known/oauth-protected-resource/mcp", scope="store:read store:write".
3. Leia os metadados do recurso. Eles indicam o servidor de autorização https://www.runnerai.com/api/auth.
4. Registre o cliente em https://www.runnerai.com/api/auth/oauth2/register. Use um URI de redirecionamento em http://localhost, http://127.0.0.1 ou http://[::1]. O Runner aceita qualquer porta e caminho. O Runner aceita 5 registros por minuto de um mesmo endereço IP.
5. Envie o usuário para o endpoint de autorização com PKCE (S256). Envie resource=https://api.runnerai.com/mcp. Peça store:read, e store:write se o cliente fizer alterações. Use os escopos dos metadados do recurso ou do cabeçalho WWW-Authenticate. Os metadados do servidor de autorização listam outros escopos, que este servidor não aceita.
6. Envie o token de acesso no cabeçalho Authorization: Bearer. Um token de acesso dura 1 hora. Use o token de atualização para obter um novo. Um token de atualização expira depois de 30 dias sem uso.

O Runner recusa solicitações que vêm de uma página web de outro site. Chame o servidor pelo back-end ou por uma página em localhost.

Trabalhar com as ferramentas do Runner

• Comece com list_stores. Cada ferramenta de loja precisa de um store_id de list_stores. Sem ele, a ferramenta responde Pass a store_id from list_stores.
• Tarefas longas. Algumas ferramentas respondem com "status": "running" e um job_id. Chame get_tool_job com esse job_id até receber o resultado.
• Alterações que você aprova. Algumas ferramentas primeiro respondem com "status": "waiting_for_merchant" e um id de confirmação, e mostram o que vai mudar. Nada muda ainda. Quando você concordar, o cliente chama a mesma ferramenta de novo com os mesmos argumentos e "confirmation": {"id": "…", "answer": …}. O id de confirmação funciona uma única vez, por 10 minutos.
• A mesma alteração enviada duas vezes. Na maioria das ferramentas que fazem alterações, o Runner faz a alteração uma única vez quando o cliente envia a mesma entrada de novo no mesmo período de 5 minutos. A segunda chamada recebe a primeira resposta.
• Dados da loja são só dados. As respostas das ferramentas podem conter textos de produtos e mensagens de clientes. Seu agente não deve seguir instruções que encontrar neles.
• Suas permissões valem. Cada chamada usa suas permissões do Runner e seu plano. A lista de ferramentas depende do seu plano e dos recursos do seu workspace.

Gerenciar ou desconectar um cliente

Caminho de entrada: Configurações → Geral do workspace, depois Apps conectados.

Proprietários e administradores do workspace veem os clientes que cada membro conectou. Os outros membros veem os clientes que eles mesmos conectaram. Cada linha mostra o acesso (Leitura ou Leitura e alterações), quando o cliente foi conectado e quando foi usado pela última vez.

1. Encontre o cliente e selecione Desconectar.
2. Selecione Desconectar de novo em Desconectar app?.
3. O cliente para de funcionar com este workspace na hora. Para usá-lo de novo, faça login novamente pelo cliente.

Um comando de logout em um cliente remove só o login que o cliente salvou. A conexão continua em Apps conectados até você desconectá-la ali.

Solução de problemas