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)	Task Celery 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 `WEBAPI_API_KEY` usada upstream não tem o escopo necessário.	Veja escopos por tool e regenere a API Key.
`502 Bad Gateway` esporádico	Servidor on-premise reiniciando (NSSM) ou Cloudflare segurando.	Aguarde 30s e tente de novo. Se persistir mais de 5 min, contate `ti@alcancecontabilidade.com.br`.
Latência alta (>3s) por chamada	Cold start da função Vercel ou WebApi 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 `MCP_BEARER_TOKEN`

# Linux/macOS
openssl rand -base64 32

# Windows PowerShell
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Max 256 }))

O valor gerado deve:

Ser configurado em Vercel → Environment Variables → MCP_BEARER_TOKEN (production, preview e development).
Ser distribuído de forma segura aos clientes (1Password, e-mail interno cifrado).
Ser rotacionado a cada 90 dias ou imediatamente em caso de suspeita de vazamento.

Obter `WEBAPI_API_KEY`

A API Key consumida pelo gateway é gerada na própria WebApiAlcance:

Faça login como admin em https://contabilidadealcance.com.br.
Navegue até Configurações → API Keys.
Clique em Nova API Key.
Preencha:
- Nome: mcp-gateway-prod (ou mcp-gateway-preview).
- Escopo: marque Restrito e selecione os pares recurso:acao listados abaixo.
- Expiração: 180 dias.
Copie o valor exibido uma única vez e cole em WEBAPI_API_KEY na Vercel.

O sistema de escopos da WebApi foi introduzido na release v5.15.1 (PR #168). Para detalhes internos, consulte a issue de governança #187 no repositório privado da WebApi.

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`	`clientes:read`
`listar_certidoes`	`certidoes:read`
`listar_lembretes`	`lembretes:read`
`criar_lembrete`	`lembretes:read`, `lembretes:write`
`consultar_status_task`	`tasks: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

Se você vai criar uma única API Key para todas as tools do MVP:

clientes:read
certidoes:read
lembretes:read
lembretes:write
tasks:read

Cinco escopos. Nada mais que isso.

Logs e observabilidade

Logs em produção: Vercel → Project → Logs (filtrar por /api/mcp).
Logs estruturados: cada chamada loga tool, latency_ms, status_code, request_id. PII é mascarada (CNPJs viram ***).
Métricas: Vercel Analytics + (futuro) Vercel Observability na Fase 2.

Como abrir um chamado

Se o problema persistir após as soluções acima:

Capture o request_id retornado 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 upstream (não com o MCP em si), siga o fluxo padrão de suporte do repositório privado WebApiAlcance — contate ti@alcancecontabilidade.com.br.