Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.gyramais.com.br/llms.txt

Use this file to discover all available pages before exploring further.

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 atendimento@gyramais.com.

​
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 atendimento@gyramais.com 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 atendimento@gyramais.com, 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 atendimento@gyramais.com 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

atendimento@gyramais.com, 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.