Troubleshooting

Guia de diagnóstico para problemas comuns ao usar o servidor MCP da Alcance.

Erros frequentes

SintomaCausa provávelSolução
401 UnauthorizedBearer ausente ou errado.Confirme o header Authorization: Bearer <token>. Sem espaços extras, sem aspas. Veja tokens.
Tool não aparece no Claude/Cursor/LovableConnector 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 certosTermo 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 corretoA 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ádicoIndisponibilidade temporária da API.Aguarde e tente novamente. Se persistir mais de 5 min, contate ti@alcancecontabilidade.com.br.
Latência alta (>3s) por chamadaPrimeira chamada após inatividade ou API com carga.Esperado em primeiras chamadas após inatividade. Chamadas seguintes ficam abaixo de 500ms.
criar_lembrete retorna 422Payload 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 IDsAlucinaçã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.

ToolEscopos obrigatórios
buscar_clientecustomers:read
listar_certidoescertidao_negativa:read
listar_lembreteslembretes:read
criar_lembretelembretes:read, lembretes:write
consultar_status_taskworker_automation:read

Escopos para os resources

ResourceEscopo
glossario://contabilNenhum (estático, embutido no MCP).
status://certidoesNenhum (estático).
bancos://suportadosNenhum (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:read

Cinco 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:

  1. Capture o request_id retornado pela tool (presente em todo erro).
  2. Anote: data/hora, cliente IA usado (Claude/Cursor/Lovable), prompt completo, resposta de erro completa.
  3. 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.