Conectar um cliente MCP¶

O servidor MCP da Gubee fica em:

https://api.gubee.com.br/mcpservice/mcp

O transporte é Streamable HTTP: uma requisição POST com corpo JSON-RPC 2.0. Não é necessário manter sessão nem enviar cabeçalho de sessão — cada requisição pode abrir uma conexão nova.

A autenticação é OAuth 2.1 contra o Keycloak da Gubee. O token é emitido para o cliente MCP, e não serve para a API de integração, que usa o token do seu app OAuth2: são credenciais distintas, para superfícies distintas.

Conectar o seu assistente¶

Você vai precisar de três coisas, iguais em todos os assistentes:

O quê	Valor
Endereço do servidor	`https://api.gubee.com.br/mcpservice/mcp`
Client ID	`gubee-mcp-desktop`
Client Secret	deixe vazio

E do seu usuário do painel da Gubee — o mesmo com que você entra em admin.gubee.com.br. O assistente enxerga os dados da conta desse usuário, e só dela.

Depois de configurar, o assistente abre o navegador na tela Entrar em Gubee.
Você entra com o usuário e a senha do painel.
Aparece a tela de autorização Gubee MCP, listando o que o assistente poderá consultar (produtos, anúncios, estoque, preços, pedidos, notas fiscais, canais). Autorize.
O navegador volta para o assistente, que passa a mostrar as ferramentas da Gubee.

Com as configurações desta página, o assistente só consulta: alterar preço, estoque, produto, anúncio ou emitir nota exige permissões próprias (veja Alterações). Para testar, pergunte algo como "quais foram os meus 5 últimos pedidos?" ou "quais anúncios estão com erro de integração?".

Passo a passo por assistente¶

Claude (web e Desktop)ChatGPTCodexClaude CodeCursorVS CodeopencodeGemini CLI

Configurações → Conectores → Adicionar conector personalizado.
Nome: Gubee · URL: https://api.gubee.com.br/mcpservice/mcp.
Abra Configurações avançadas antes de salvar e preencha OAuth Client ID gubee-mcp-desktop. Deixe o Client Secret vazio.
Salve e clique em Conectar.

Se aparecer "Não foi possível registrar no serviço de login", o Client ID ficou em branco: edite o conector e preencha em Configurações avançadas.

Nas conversas do ChatGPT (navegador ou aplicativo), um servidor MCP entra como app do modo desenvolvedor. Esse modo depende da conta: plano Plus, Pro, Business, Enterprise ou Edu e, em conta de empresa, liberação de um administrador. Se a opção não aparecer para você, o ChatGPT ainda não permite conectar servidores próprios na sua conta.

No navegador (chatgpt.com): Configurações → Segurança e login → Modo desenvolvedor.
Em Plugins, clique em + e crie um app do modo desenvolvedor.
URL: https://api.gubee.com.br/mcpservice/mcp · autenticação: OAuth.
Client ID gubee-mcp-desktop, secret vazio.

Integrações e MCP, no ChatGPT desktop, é do Codex

A tela Configurações → Integrações e MCP do aplicativo desktop configura servidores para o Codex, não para as conversas do ChatGPT. Um servidor adicionado ali não aparece no chat — o ChatGPT responde que não tem conexão com a Gubee. Para usar pelo Codex, veja a aba Codex.

Vale para o Codex no terminal, na extensão de IDE e dentro do aplicativo ChatGPT desktop — os três leem o mesmo arquivo. A tela Integrações e MCP do desktop não tem campo de Client ID (se você adicionar a Gubee por ela, o login falha); configure pelo arquivo:

Feche o aplicativo.
Abra (ou crie) o config.toml na pasta .codex do seu usuário:
- Windows: C:\Users\<seu usuário>\.codex\config.toml
- macOS e Linux: ~/.codex/config.toml

Se já existir um bloco [mcp_servers.gubee] (criado pela tela), apague-o inteiro, inclusive [mcp_servers.gubee.http_headers]. Cole no fim do arquivo:

[mcp_servers.gubee]
url = "https://api.gubee.com.br/mcpservice/mcp"
scopes = ["ad:view", "invoice:view", "order:view", "platform:view", "price:view", "product:view", "stock:view", "offline_access"]

[mcp_servers.gubee.oauth]
client_id = "gubee-mcp-desktop"
callback_port = 41999
callback_url = "http://127.0.0.1:41999/callback"

Faça o login: no terminal, codex mcp login gubee; no aplicativo, reabra e conecte o servidor gubee em Integrações e MCP.
Use a Gubee numa conversa do Codex — não do chat comum.

Copie o bloco exatamente como está: a porta 41999 e o endereço de retorno precisam ser esses.

Não acrescente oauth_resource

O Codex já envia esse parâmetro sozinho; configurado de novo, ele sai duplicado e o login é recusado (invalid_request: duplicated parameter).

No terminal:

claude mcp add gubee \
  --transport http \
  --client-id gubee-mcp-desktop \
  --callback-port 41999 \
  https://api.gubee.com.br/mcpservice/mcp

Depois abra o Claude Code, rode /mcp, escolha gubee e autentique.

Em ~/.cursor/mcp.json (Windows: C:\Users\<seu usuário>\.cursor\mcp.json):

{
  "mcpServers": {
    "gubee": {
      "url": "https://api.gubee.com.br/mcpservice/mcp",
      "auth": {
        "CLIENT_ID": "gubee-mcp-desktop",
        "scopes": ["ad:view", "invoice:view", "order:view", "platform:view", "price:view", "product:view", "stock:view", "offline_access"]
      }
    }
  }
}

Se o arquivo já tiver outros servidores, acrescente só o bloco "gubee" dentro de "mcpServers".

Na paleta de comandos, MCP: Open User Configuration, e acrescente:

{
  "servers": {
    "gubee": {
      "type": "http",
      "url": "https://api.gubee.com.br/mcpservice/mcp",
      "oauth": { "clientId": "gubee-mcp-desktop" }
    }
  }
}

Se o VS Code pedir um Client Secret, deixe em branco. O login usa a porta 33418 do seu computador: feche o que estiver usando essa porta antes de conectar.

Em ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gubee": {
      "type": "remote",
      "url": "https://api.gubee.com.br/mcpservice/mcp",
      "oauth": { "clientId": "gubee-mcp-desktop" }
    }
  }
}

Depois, no terminal: opencode mcp auth gubee.

Em ~/.gemini/settings.json:

{
  "mcpServers": {
    "gubee": {
      "httpUrl": "https://api.gubee.com.br/mcpservice/mcp",
      "oauth": {
        "enabled": true,
        "clientId": "gubee-mcp-desktop",
        "redirectUri": "http://localhost:7777/oauth/callback",
        "scopes": ["ad:view", "invoice:view", "order:view", "platform:view", "price:view", "product:view", "stock:view", "offline_access"]
      }
    }
  }
}

Depois, dentro do Gemini CLI: /mcp auth gubee.

Dados do comprador¶

Por padrão, nome, documento e endereço do comprador chegam mascarados. Para vê-los sem máscara, acrescente "order:customer-data" à lista de escopos (ou autorize esse item, no assistente que pedir todos) — o acesso a esse dado fica registrado.

Alterações¶

Para o assistente poder alterar a conta, acrescente à lista de escopos as permissões de alteração que quer usar (ou autorize esses itens, no assistente que pedir todos):

Escopo	Libera
`"price:edit"`	`update_price` — preço padrão de um anúncio
`"stock:edit"`	`update_stock` — estoque de um SKU num armazém
`"product:edit"`	`update_product` — nome, descrição e atributos de um produto
`"ad:edit"`	`update_ad` e `manage_ad_tags` — texto e etiquetas de um anúncio
`"invoice:issue"`	`issue_invoice` — nota fiscal de venda de um pedido

Só recebe uma permissão de alteração o usuário que a tem no painel da Gubee. Sem ela, o login funciona igual, sem essa permissão, e a tool correspondente recusa a chamada. Toda alteração passa por pré-visualização e confirmação — veja Alterações pelo MCP.

Se der errado¶

O que aparece	Causa	Como resolver
O ChatGPT responde que não tem conexão com a Gubee	O servidor foi adicionado em Integrações e MCP, que é do Codex	Use o modo desenvolvedor (aba ChatGPT) ou converse pelo Codex
Não foi possível registrar no serviço de login	O Client ID não foi informado; o assistente tentou se cadastrar sozinho	Preencha o Client ID `gubee-mcp-desktop` na configuração
Parâmetro inválido: redirect_uri	A porta ou o endereço de retorno foi alterado	Copie a configuração exatamente como está acima
`authentication_expired` (ou `temporarily_unavailable`) na volta para o assistente	A tela de login ficou aberta tempo demais antes de você entrar	Recomece a conexão pelo assistente e conclua o login em seguida, na aba nova que ele abrir
Página não foi possível conectar em `127.0.0.1` ou `localhost` depois do login	O assistente parou de esperar o retorno	Recomece a conexão pelo assistente
`invalid_scope`	A lista de escopos ficou de fora	Inclua `scopes` como no exemplo
`invalid_request: duplicated parameter`	`oauth_resource` configurado no Codex	Remova essa linha
O assistente conecta mas não mostra ferramentas de um domínio	Esse item não foi autorizado na tela Gubee MCP	Desconecte, conecte de novo e autorize todos os itens
Uma tool de alteração aparece, mas a chamada é recusada por permissão	As tools de alteração aparecem para toda conexão; o escopo de alteração não foi autorizado, ou o seu usuário não tem essa permissão no painel da Gubee	A resposta diz qual permissão falta. Sem a permissão no painel, peça a um administrador da conta; com ela, reconecte autorizando o escopo — ver Alterações pelo MCP

Seu assistente não está na lista? Ele funciona se permitir informar o Client ID e usar um endereço de retorno fixo. Envie à Gubee o nome do assistente e o endereço de retorno que ele usa, para que seja liberado.

Descoberta automática¶

Um cliente MCP descobre sozinho onde autenticar. Ele chama o endpoint sem credencial, lê o WWW-Authenticate do 401, busca o documento apontado e segue para o authorization server. Você não precisa configurar nada disso à mão em um cliente que implemente a especificação.

O 401 traz:

WWW-Authenticate: Bearer resource_metadata="https://api.gubee.com.br/.well-known/oauth-protected-resource/mcpservice/mcp"

E o documento apontado (RFC 9728) é público:

curl -s "$GUBEE_API/.well-known/oauth-protected-resource/mcpservice/mcp"

{
  "resource": "https://api.gubee.com.br/mcpservice/mcp",
  "authorization_servers": ["https://auth.gubee.com.br/realms/gubee"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["..."]
}

O documento é a fonte viva dos escopos

scopes_supported é derivado do catálogo de tools e muda quando o catálogo muda. As configurações desta página trazem a lista vigente para você copiar; quando um domínio novo entrar no catálogo, ela é atualizada aqui. Para conferir a lista na hora: curl -s https://api.gubee.com.br/.well-known/oauth-protected-resource/mcpservice/mcp.

O authorization server anunciado publica o próprio documento de descoberta, com os endpoints de autorização e de token:

curl -s https://auth.gubee.com.br/realms/gubee/.well-known/openid-configuration

Agente próprio¶

Um agente de parceiro ou ERP que fala MCP em nome de um contrato usa o grant client_credentials, com client confidencial. O mecanismo de app OAuth2 da Gubee está em Apps OAuth2 — o modelo de autorização e revogação é o mesmo.

O token precisa carregar a audience do recurso MCP

A rota do MCP valida a audience do token e recusa um token que não a carregue mesmo sendo válido no mesmo realm. Um app registrado para a API de integração não atende a essa condição automaticamente. Ao solicitar acesso ao MCP para um agente, confirme com a Gubee que o client vai emitir a audience do recurso MCP e quais domínios de leitura deve cobrir.

Não há registro dinâmico de cliente

A especificação do MCP prevê que um cliente se registre sozinho no authorization server. Isso não está habilitado na Gubee: o lojista usa o client gubee-mcp-desktop, e um agente próprio usa o client que a Gubee registra para ele.

Chamada crua¶

Quando você mesmo implementa o cliente, o corpo é JSON-RPC 2.0 e a resposta vem no mesmo formato.

curl -s -X POST "$GUBEE_API/mcpservice/mcp" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

O cabeçalho Accept é obrigatório

Sem Accept: application/json, text/event-stream o servidor responde 400 com corpo vazio — sem mensagem que explique a causa. É o erro mais comum de quem implementa o cliente na mão. O Content-Type sozinho não basta.

Chamar uma tool segue o mesmo formato:

curl -s -X POST "$GUBEE_API/mcpservice/mcp" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
        "jsonrpc": "2.0",
        "id": 2,
        "method": "tools/call",
        "params": {
          "name": "search_orders",
          "arguments": { "startDate": "2026-09-01", "endDate": "2026-09-07", "limit": 20 }
        }
      }'

tools/list responde sem initialize prévio. O catálogo é cacheável por 5 minutos — não é preciso listá-lo a cada chamada.

Erros¶

Situação	Resposta
Sem credencial, ou credencial inválida	`401` com `WWW-Authenticate` apontando o resource metadata
Credencial válida sem o escopo da tool	`403`
Falta o `Accept` correto	`400` com corpo vazio
Argumento não declarado pela tool	Erro da tool nomeando os argumentos não reconhecidos

O último caso é deliberado: um argumento com grafia errada é recusado, não ignorado. Um filtro descartado em silêncio devolve uma resposta que parece certa e não é. Os nomes de argumento são camelCase — startDate, não start_date.

Limites¶

A rota do MCP tem limite de requisições por cliente. Os valores aplicados ao seu acesso acompanham a credencial. As tools que paginam usam limit com padrão 10 e teto 50: um limit acima do teto é reduzido, e a resposta informa a redução.

Próximos passos¶

Catálogo de tools — as 22 tools e seus argumentos.
Alterações pelo MCP — o fluxo em dois passos, as permissões e os erros.
Visão geral do MCP — o que o servidor garante em toda resposta.