> ## Documentation Index
> Fetch the complete documentation index at: https://docs.migraflow.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Problemas comuns do MCP

> Diagnóstico de registro, processo local, autenticação e ferramentas.

## O servidor não aparece

Confirme que a configuração está no cliente correto, que o JSON é válido e que `command` aponta para um executável absoluto. Reinicie o cliente após a alteração.

## O processo encerra imediatamente

Execute o comando configurado em um terminal para observar erros de Python ou dependências. O servidor usa transporte `stdio`; quando iniciado pelo cliente, não deve imprimir conteúdo arbitrário no canal de protocolo.

## `MIGRAFLOW_API_KEY not set`

Inclua a variável no bloco `env` do servidor ou no ambiente herdado pelo cliente. Não a envie como argumento de ferramenta.

## Ferramentas aparecem, mas retornam 401/403

O registro MCP está correto, mas a API rejeitou a credencial. Confirme perfil, validade e ambiente da chave.

## Timeout durante análise

Valide primeiro, reduza o DDL ao escopo acordado e evite chamadas simultâneas. Não fragmente objetos dependentes sem registrar essa limitação no assessment.

## `explain_mapping` não encontra o ID

Use um `mapping_id` retornado por uma execução persistida no mesmo ambiente. IDs de staging e produção não são intercambiáveis.

## O cliente corporativo bloqueia MCP local

Solicite liberação ao administrador. Não contorne políticas de allowlist, execução local ou armazenamento de credenciais.

## Como abrir um incidente

Informe versão do pacote, sistema operacional, cliente MCP, horário, ferramenta chamada e status HTTP. Remova API keys e dados de cliente antes de anexar logs.