---
lastModified: 2026-11-13
title: Conectar o Runner a outros clientes MCP
description: Conecte o OpenCode, o Codex, o pi ou seu próprio agente às suas lojas do Runner pelo servidor MCP do Runner.
seo:
  description: "Conecte o OpenCode, o Codex, o pi ou seu próprio agente às suas lojas do Runner. Adicione uma URL de servidor, entre no Runner pelo navegador e escolha o que o cliente pode fazer."
---

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.

| Configuração | Valor |
| --- | --- |
| URL do servidor | `https://api.runnerai.com/mcp` |
| Transporte | Streamable HTTP. O Runner não oferece suporte ao transporte SSE, que é mais antigo. |
| Login | OAuth no navegador. Você não precisa de uma chave de API. |
| Acesso | `store:read` para ler os dados da loja. `store:write` para fazer alterações. |

## 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.

| Controle ou mensagem | Por que é útil | O que acontece a seguir |
| --- | --- | --- |
| **Volta para** | Mostra o endereço em seu computador que recebe o resultado do login. | Mostra `localhost`, `127.0.0.1` ou `[::1]` e um número de porta. |
| **O Runner não consegue confirmar que app é este. Conecte-o somente se você mesmo iniciou esta conexão.** | O Runner não consegue verificar a identidade de um cliente que você instalou ou criou. | Conecte somente se você iniciou o login a partir do seu cliente. |
| **Workspace** | Uma conexão funciona com as lojas de um workspace. | O cliente só pode usar as lojas do workspace que você escolher. |
| **Leitura** | Sempre ativo. O cliente pode ver os dados da loja, como produtos, pedidos e relatórios. | Não é possível desativá-lo. |
| **Fazer alterações** | Permite que o cliente altere os dados da loja, como produtos, preços e descontos. | Começa desativado. Só aparece quando o cliente pede acesso para fazer alterações. |
| **Conectar** | Dá ao cliente o acesso que você escolheu. | O navegador volta para o cliente. |
| **Cancelar** | Interrompe o login. | O cliente não recebe nenhum acesso. |

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:

   ```json
   {
     "$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`:

   ```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`:

   ```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.

```json
{
  "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`:

```bash
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

| O que você vê | Causa | O que fazer |
| --- | --- | --- |
| `{"error":"invalid_scope"}` no navegador | O cliente pediu escopos que este servidor não aceita. O `codex mcp add` faz isso. | Peça `store:read` e `store:write`. No Codex, adicione a linha `scopes` e execute `codex mcp login runner`. |
| **This redirect URI cannot receive Merchant MCP codes.** | O cliente envia o navegador de volta para um link de app ou uma página web. | Use a ponte `mcp-remote`. |
| **Request the Merchant MCP resource alone.** | O cliente não enviou `resource=https://api.runnerai.com/mcp`. | Atualize o cliente ou use a ponte `mcp-remote`. |
| **Esta solicitação de conexão não está disponível. Inicie a conexão novamente no seu app de IA.** | O link de login é antigo ou já foi usado. | Inicie o login de novo pelo cliente. |
| **Você não é membro de nenhum workspace. Crie um workspace no Runner e inicie a conexão novamente.** | Sua conta não tem nenhum workspace. | Crie um workspace e inicie o login de novo. |
| **This tool needs store\:write. Reconnect Runner and allow changes to the store.** | A conexão tem só o acesso **Leitura**. | Faça logout no cliente, faça login de novo e ative **Fazer alterações**. |
| **This feature is not on for this store yet.** | O recurso não está ativado para seu plano, workspace ou loja. | Faça a tarefa no Runner ou peça ajuda ao suporte do Runner. |
| O provedor do modelo recusa a solicitação: `input_schema does not support oneOf, allOf, or anyOf at the top level` | O cliente envia todas as ferramentas ao modelo, e três ferramentas de impressão sob demanda têm um esquema que alguns provedores de modelos recusam. | Desative `publish_pod_product`, `review_pod_product` e `update_pod_product`, ou ative só as ferramentas de que você precisa. |
| O cliente pede que você faça login de novo | Você desconectou o cliente no Runner ou não o usou por 30 dias. | Faça login de novo pelo cliente. |
| HTTP 429 quando o cliente se registra | Mais de 5 registros em um minuto de um mesmo endereço IP. | Espere um minuto e tente de novo. |
| Uma resposta termina com **Support reference:** e um código | A ferramenta falhou no Runner. | Informe o código ao suporte do Runner. |