Troubleshooting
Guia de diagnóstico para problemas comuns ao usar o servidor MCP da Alcance.
Erros frequentes
| Sintoma | Causa provável | Solução |
|---|---|---|
401 Unauthorized | Bearer ausente ou errado. | Confirme o header Authorization: Bearer <token>. Sem espaços extras, sem aspas. Veja tokens. |
| Tool não aparece no Claude/Cursor/Lovable | Connector não conectado ou cache de tools/list. | Reconecte o conector. No Cursor: MCP: Reload Servers. No Claude: desligue e ligue o connector. |
cliente_nao_encontrado mesmo passando dados certos | Termo de busca normalizado não bate (acentos, máscara CNPJ). | Use buscar_cliente com CNPJ apenas dígitos ou com parte exata da razão social sem pontuação. |
| Timeout em automação (scraper, conversor) | Tarefa assíncrona demorando - normal para CNDs e conversões. | Pegue o task_id retornado e use consultar_status_task(task_id) em intervalos de 10-30s. |
| Resposta truncada / "muitos itens" | Mais de 20 itens retornados. | Use filtros: status=…, cliente_id=…, periodo=…, tipo=…. Quebre em buscas menores. |
403 Forbidden mesmo com bearer correto | A API Key usada pelo gateway não tem o escopo necessário. | Veja escopos por tool e solicite a ampliação ao TI. |
502 Bad Gateway esporádico | Indisponibilidade temporária da API. | Aguarde e tente novamente. Se persistir mais de 5 min, contate ti@alcancecontabilidade.com.br. |
| Latência alta (>3s) por chamada | Primeira chamada após inatividade ou API com carga. | Esperado em primeiras chamadas após inatividade. Chamadas seguintes ficam abaixo de 500ms. |
criar_lembrete retorna 422 | Payload inválido (data no passado, cliente_id inexistente). | Cheque a mensagem em PT-BR retornada pela tool - ela aponta o campo problemático. |
| Cliente IA "inventa" CNPJs ou IDs | Alucinação típica de LLM. | Sempre instrua o modelo a buscar primeiro e nunca confiar em memória prévia. Veja boas práticas de prompt. |
Tokens
Gerar um token seguro
# Linux/macOS
openssl rand -base64 32# Windows PowerShell
$b = [byte[]]::new(32); [Security.Cryptography.RandomNumberGenerator]::Fill($b); [Convert]::ToBase64String($b)O token do MCP é emitido pelo TI Alcance, distinto por integração. Guarde-o em um cofre de segredos, rotacione a cada 90 dias ou imediatamente em caso de suspeita de vazamento.
API Key do gateway
A API Key usada pelo gateway é emitida pelo TI Alcance com escopos mínimos. Para solicitar ou rotacionar, veja escopos de API Key. Para gerir chaves no Hub, faça login com um usuário com permissão adicional.
Escopos mínimos por tool
Configure a API Key da WebApi com apenas os escopos abaixo. Princípio do menor privilégio.
| Tool | Escopos obrigatórios |
|---|---|
buscar_cliente | customers:read |
listar_certidoes | certidao_negativa:read |
listar_lembretes | lembretes:read |
criar_lembrete | lembretes:read, lembretes:write |
consultar_status_task | worker_automation:read |
Escopos para os resources
| Resource | Escopo |
|---|---|
glossario://contabil | Nenhum (estático, embutido no MCP). |
status://certidoes | Nenhum (estático). |
bancos://suportados | Nenhum (estático). |
Conjunto mínimo recomendado
Para usar todas as tools do MVP, o conjunto mínimo de escopos é:
customers:read
certidao_negativa:read
lembretes:read
lembretes:write
worker_automation:readCinco escopos. Nada mais que isso.
Logs e observabilidade
- Logs estruturados: cada chamada loga
tool,latency_ms,status_code,request_id. PII é mascarada (CNPJs viram***).
Como abrir um chamado
Se o problema persistir após as soluções acima:
- Capture o
request_idretornado pela tool (presente em todo erro). - Anote: data/hora, cliente IA usado (Claude/Cursor/Lovable), prompt completo, resposta de erro completa.
- Envie para ti@alcancecontabilidade.com.br com assunto
[MCP] <descrição curta>.
Para problemas com a WebApi (não com o MCP em si), contate ti@alcancecontabilidade.com.br.