Troubleshooting MCP

Erros comuns ao usar o MCP da GYRA+: autenticação, conexão, tools não aparecendo, comportamento inesperado do agente.

Resumo: esta página cataloga os problemas mais comuns ao configurar e usar o MCP da GYRA+, com diagnóstico e solução. Consulte por sintoma; se o seu caso não está listado, fale com o suporte em [e-mail].

As tools não aparecem no cliente

Sintoma

Você configurou o mcpServers em Claude Desktop (ou equivalente), reiniciou, e no chat o ícone de ferramentas não mostra as tools da GYRA+.

Diagnóstico

1. Verificar se o processo sobe

   Cheque logs do cliente. Em Claude Desktop: Settings > Developer > Open Logs. Procure linhas com gyra ou erros de spawn do npx.

2. Rodar o comando manual

   Num terminal:

   GYRA_CLIENT_ID=seu_client_id \
   GYRA_CLIENT_SECRET=seu_client_secret \
   npx -y @gyramais/mcp-server
   

   Se der erro de módulo não encontrado, é Node.js ausente ou versão antiga. Instale Node 18+.

3. Validar o JSON do config

   Erro comum: vírgula faltando, chaves sem aspas, escape errado no Windows. Passe o JSON num validador (jsonlint.com).

4. Reiniciar totalmente o cliente

   Claude Desktop às vezes mantém o MCP antigo em cache. Cmd+Q no macOS, e não só fechar a janela.

Erro 401, Unauthorized

Sintoma

O agente tenta chamar uma tool e recebe 401 Unauthorized.

Causas possíveis

• clientId ou clientSecret com typo. Copie novamente do e-mail do suporte.
• Credenciais revogadas ou reemitidas. Confirme com [e-mail] se as credenciais que você tem ainda estão ativas.
• Credenciais de organização errada. As credenciais são vinculadas a uma organização; se você tem várias, confira qual está usando.

Solução

Solicitar reemissão via [e-mail], atualizar GYRA_CLIENT_ID e GYRA_CLIENT_SECRET no config do cliente (ou reautenticar no custom connector do Claude) e reiniciar.

Erro 403, Forbidden

Sintoma

Tool específica retorna 403. Outras tools funcionam.

Causa

As credenciais da sua organização não têm permissão para o endpoint em questão (ex: organização sem a feature contratada, ou papel restrito).

Solução

Acionar [e-mail] informando a tool que falhou — o suporte confirma o escopo contratado e ajusta se for o caso.

Rate limit, 429 Too Many Requests

Sintoma

Em conversas com muitas chamadas encadeadas, o agente recebe 429.

Causa

Limite padrão é 100 req/min por organização. Encadeamentos longos (ex: varrer 500 relatórios) excedem.

Solução

• Esperar: o cliente MCP respeita Retry-After e retoma automaticamente depois do intervalo.
• Pedir ao agente em batches: “processa 50 por vez e me avisa quando terminar cada bloco”.
• Contrato enterprise: limites mais altos disponíveis. Fale com o comercial.

Relatório fica em PROCESSING para sempre

Sintoma

Depois de chamar create_report, o agente faz polling em get_report e o status nunca muda de PROCESSING.

Causas possíveis

• Fonte lenta (SCR via Open Finance, por exemplo). Esperar até 2 minutos é normal.
• Fonte totalmente indisponível: o status acaba em ERROR. Acione create_report novamente ou aguarde o restabelecimento da fonte.
• Polling muito rápido: se você instruir o agente a chamar get_report cada 1s, o 429 aparece sem progresso real.

Solução

• Esperar 60 a 120 segundos antes de assumir erro.
• Se o status for ERROR, confirmar na resposta qual fonte falhou e reanalisar.
• Em agentes autônomos, adotar backoff: 10s, 20s, 40s entre chamadas de get_report.

O modelo escolhe a tool errada

Sintoma

Você pede “quantas análises negadas esta semana” e o modelo chama list_reports gigante em vez de count_reports.

Solução

• Modelo melhor: Claude 3.5 Sonnet (ou equivalente) escolhe tool muito melhor que modelos pequenos.
• Prompt mais direto: “usa count_reports para me dar só o número” força a escolha.
• Dividir a pergunta: se a conversa tem muita ambiguidade, separar em passos explícitos.

O agente inventa dados

Sintoma

O agente responde “a análise aprovou com score 750” mas na verdade não rodou tool alguma.

Causa

Isso é alucinação do modelo, não falha do MCP. Algum cliente MCP por padrão deixa o modelo responder sem usar tools se ele “achar que sabe”.

Solução

• No prompt: “sempre chame as tools da gyra para dados reais, nunca invente”.
• Verificação visual: todo cliente MCP mostra as tool calls na UI. Se você não viu chamada acontecer, o dado não é real.
• Modelos reasoning (o1, Claude Thinking) costumam ser mais honestos sobre o que sabem.

Timeouts ou conexão instável

Sintoma

Chamadas falham intermitentemente com timeout ou ECONNRESET.

Causas possíveis

• Rede corporativa com firewall bloqueando SSE/WebSocket.
• Proxy do seu ambiente não repassa headers.
• ISP instável.

Solução

• Testar em rede doméstica para isolar o firewall corporativo como causa.
• Se for proxy, consultar a TI para liberar o host mcp.gyramais.com.br.
• Para ambientes muito restritos, considerar usar a API REST direta em vez de MCP.

Múltiplas organizações confundindo o agente

Sintoma

Você pertence a Org A e Org B, e o agente mistura dados.

Solução

• As credenciais são por organização. Use uma config de MCP por organização, com nomes distintos (gyra-orgA, gyra-orgB).
• No prompt: “use o servidor gyra-orgA” garante a escolha.

Logs e diagnóstico avançado

Claude Desktop

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\mcp*.log

Cursor

• Settings > MCP > View Logs.

Cliente próprio

Suba o level do logger do SDK MCP para debug e cheque a troca de JSON-RPC com o servidor.

Ainda está com problema?

Abrir chamado

[e-mail], com log do cliente anexado.

FAQ

Base de conhecimento geral da GYRA+.

Instalação

Revisar o setup do zero.

API REST

Alternativa sem MCP em caso de bloqueio crônico.