Este guia ajuda a resolver problemas comuns com configuração e uso do MCP.

Problemas de conexão

Falha na autenticação

Sintomas:

• Erro: “401 Unauthorized”
• Mensagem “Invalid token”
• Conexão recusada pelo servidor MCP

Soluções:

1. Verificar formato do token:

   # Formato correto com prefixo Bearer
   Authorization: Bearer SEU_PERSONAL_TOKEN
   
   # Nota: Cursor usa prefixo Token
   Authorization: Token SEU_PERSONAL_TOKEN

2. Verificar validade do token:

   • Navegue até o Console Azion
   • Verifique se o token está ativo e não expirado
   • Certifique-se de que o token tem as permissões necessárias

3. Testar com MCP Inspector:

   npx @modelcontextprotocol/inspector

   Configure como streamable-http com seu token para validar a conexão.

Timeout de conexão

Sintomas:

• Requisição expira após 30+ segundos
• Sem resposta do servidor MCP
• Mensagens de “Network error”

Soluções:

1. Verificar URL do ambiente:

   • Produção: https://mcp.azion.com
   • Certifique-se de não haver erros de digitação na URL

2. Testar conectividade de rede:

   # Testar disponibilidade do servidor
   curl -I https://mcp.azion.com

3. Verificar configurações de firewall/proxy:

   • Certifique-se de que tráfego HTTPS para mcp.azion.com é permitido
   • Verifique configuração de proxy se aplicável

Ferramentas não aparecem

Nenhuma ferramenta listada no assistente

Sintomas:

• Assistente de código não mostra ferramentas Azion
• Mensagem “No tools available”
• Comandos não reconhecidos

Soluções:

1. Verificar suporte MCP:

   • Certifique-se de que sua versão do assistente de código suporta MCP
   • Atualize para a versão mais recente se necessário

2. Verificar sintaxe da configuração:

   Claude Code

   claude mcp list  # Deve mostrar azion-mcp

   Cursor

   Verifique se a sintaxe JSON nas configurações é válida

   Windsurf

   Verifique se .codeium/windsurf/mcp_config.json existe e é JSON válido

3. Reiniciar o assistente:

   • Feche e reabra a aplicação
   • Para Claude Code: claude serve --restart

Erros de execução de ferramentas

Erro “Tool not found”

Sintomas:

• Nomes de ferramentas específicos não reconhecidos
• Erros “Unknown tool”

Soluções:

1. Verificar nome da ferramenta: Nomes corretos das ferramentas:

   • search_azion_docs_and_site
   • search_azion_code_samples
   • search_azion_cli_commands
   • search_azion_api_v3_commands
   • search_azion_api_v4_commands
   • search_azion_terraform
   • create_rules_engine
   • create_graphql_query
   • deploy_azion_static_site

2. Verificar perfil de API:

   • Perfis v3 podem ter acesso limitado a ferramentas
   • Considere atualizar para perfil v4

Respostas vazias ou incompletas

Sintomas:

• Ferramentas retornam sem resultados
• Respostas parciais
• Respostas genéricas em vez de informações específicas da Azion

Soluções:

1. Refinar sua query:

   ❌ "Ajuda com cache"
   ✅ "Como configuro TTL de cache para imagens na Azion?"

2. Usar dicas de ferramenta específicas:

   "Busque nos docs Azion sobre configuração de cache do Rules Engine"

3. Dividir requisições complexas:

   • Separe perguntas com múltiplas partes
   • Peça esclarecimentos se necessário

Problemas de arquivo de configuração

Erros de parsing JSON

Sintomas:

• Erros “Invalid JSON”
• Configuração não carregada

Soluções:

1. Validar sintaxe JSON:

   # Usar um validador JSON
   cat mcp_config.json | python -m json.tool

2. Problemas comuns de JSON:

   • Vírgulas faltando entre propriedades
   • Vírgulas finais (não permitidas em JSON)
   • Tipos de aspas incorretos (deve usar aspas duplas)
   • Colchetes ou chaves não fechados

3. Exemplo de configuração válida:

   {
   "mcpServers": {
     "azion": {
       "command": "npx",
       "args": [
         "mcp-remote",
         "https://mcp.azion.com",
         "--header",
         "Authorization: Bearer SEU_TOKEN"
       ]
     }
   }
   }

Problemas relacionados ao Node.js

Comando npx não encontrado

Sintomas:

• “npx: command not found"
• "Node.js is required”

Soluções:

1. Instalar Node.js:

   # Verificar se está instalado
   node --version
   npm --version
   
   # Instalar via gerenciador de pacotes
   # macOS
   brew install node
   
   # Ubuntu/Debian
   sudo apt install nodejs npm

2. Atualizar npm:

   npm install -g npm@latest

Problemas com pacote mcp-remote

Sintomas:

• “Cannot find module ‘mcp-remote‘“
• Falha na instalação do pacote

Soluções:

1. Limpar cache do npm:

   npm cache clean --force

2. Instalar globalmente:

   npm install -g mcp-remote

3. Usar versão específica:

   npx mcp-remote@latest

Problemas de performance

Tempos de resposta lentos

Soluções:

1. Usar ambiente apropriado:

   • Produção para estabilidade
   • Local para desenvolvimento (mais rápido)

2. Otimizar queries:

   • Seja específico nas requisições
   • Evite buscas muito amplas

3. Verificar latência de rede:

   ping mcp.azion.com

Problemas de OAuth e SSO

Falha na validação do token

Sintomas:

• “Invalid token” após fluxo OAuth
• UserInfo retorna 401

Soluções:

1. Verificar formato do token:

   • Certifique-se de que o token é enviado com prefixo Bearer
   • Verifique se está usando o domínio SSO correto (produção vs stage)

2. Verificar expiração do token:

   • Tokens OAuth expiram após um período definido
   • Solicite um novo token se expirado

3. Verificar endpoints SSO:

   • Produção: https://sso.azion.com/oauth/*
   • Stage: https://stage-sso.azion.com/oauth/*

Cliente não autorizado

Soluções:

1. Verifique se client ID e secret estão corretos
2. Verifique se a URI de redirect corresponde exatamente ao configurado no SSO
3. Certifique-se de que os scopes necessários estão habilitados para o cliente

Problemas específicos de ambiente

Ambiente stage não responde

Soluções:

1. Verificar URL:

   • URL Stage: https://stage-mcp.azion.com
   • URL Produção: https://mcp.azion.com

2. Verificar status do ambiente:

   • Stage pode ter disponibilidade diferente de produção
   • Use produção para fluxos críticos

Problemas de desenvolvimento local

Soluções:

1. Verificar se o servidor está rodando:

# Verificar se azion dev está rodando
curl http://localhost:3333

2. Verificar variáveis de ambiente:

# Necessário para desenvolvimento local
echo $OPENAI_API_KEY

3. Reiniciar servidor local:

# Parar e reiniciar
azion dev

Obtendo ajuda

Se os problemas persistirem após tentar essas soluções:

1. Entre em contato com o suporte:

   • Inclua mensagens de erro
   • Especifique o assistente de código e versão
   • Forneça a configuração (sem tokens)
   • Descreva os passos para reproduzir

2. Recursos da comunidade:

   • Discord da Azion

Próximos passos

• Desenvolvimento Local MCP
• Teste de Cache MCP