Solução de problemas

Problemas comuns ao conectar ou chamar ferramentas, e o que causa cada um.

"Authentication required" ao conectar

O servidor exige um token de acesso Bearer em cada solicitação — um simples GET na URL do servidor (por exemplo, abri-la no navegador) sempre retorna isso; não é um erro na sua configuração.

{
  "error": "Authentication required. POST with Authorization: Bearer <token>."
}

Solicitações que funcionavam antes falham de repente

Tokens de acesso expiram após 1 hora. Um cliente funcional renova automaticamente usando seu refresh token — se o seu não fizer isso, reconecte-o.

Um cliente que funcionava antes parou de funcionar completamente

Alguém na sua agência pode ter revogado a conexão desse cliente em Configurações → Desenvolvedor → Conexões MCP. Reconecte-o para obter uma nova autorização.

"Tool not found" ou uma ferramenta com nome parecido está faltando

Os nomes das ferramentas são exatos e diferenciam maiúsculas de minúsculas — confira esta referência para o nome preciso. Se você usa um cliente em modo "compacto" ou "código", apenas as ferramentas de descoberta (search_os_tools, call_os_tool, …) são listadas diretamente; use-as para encontrar e chamar as demais pelo nome.

Uma chamada de ferramenta é rejeitada por falta de acesso

A conexão só tem mcp:read (somente leitura) — reconecte e aprove o acesso de escrita se a ferramenta chamada precisar dele.

Limites de requisições

Atualmente não há limite de requisições específico para chamadas de ferramentas MCP — diferente do limite da API REST, baseado no plano e por agência.