# Solução de Problemas MCP

import Code from '~/components/Code/Code.astro'

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**:
   <Code lang="bash" code={`
   # 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](https://console.azion.com/personal-tokens)
   - 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**:
   <Code lang="bash" code={`
   npx @modelcontextprotocol/inspector
   `} />
   Configure como `streamable-http` com seu token para validar a conexão.

:::warning
Nunca compartilhe seu Personal Token ou faça commit dele no controle de versã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**:
   <Code lang="bash" code={`
   # 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**:
   <details>
   <summary>Claude Code</summary>
   <Code lang="bash" code={`
   claude mcp list  # Deve mostrar azion-mcp
   `} />
   </details>
   
   <details>
   <summary>Cursor</summary>
   Verifique se a sintaxe JSON nas configurações é válida
   </details>
   
   <details>
   <summary>Windsurf</summary>
   Verifique se `.codeium/windsurf/mcp_config.json` existe e é JSON válido
   </details>

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**:
   <Code lang="plaintext" code={`
   ❌ "Ajuda com cache"
   ✅ "Como configuro TTL de cache para imagens na Azion?"
   `} />

2. **Usar dicas de ferramenta específicas**:
   <Code lang="plaintext" code={`
   "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**:
   <Code lang="bash" code={`
   # 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**:
   <Code lang="json" code={`
   {
     "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**:
   <Code lang="bash" code={`
   # 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**:
   <Code lang="bash" code={`
   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**:
   <Code lang="bash" code={`
   npm cache clean --force
   `} />

2. **Instalar globalmente**:
   <Code lang="bash" code={`
   npm install -g mcp-remote
   `} />

3. **Usar versão específica**:
   <Code lang="bash" code={`
   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**:
   <Code lang="bash" code={`
   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**:

<Code lang="bash" code={`# Verificar se azion dev está rodando
curl http://localhost:3333`} />

2. **Verificar variáveis de ambiente**:

<Code lang="bash" code={`# Necessário para desenvolvimento local
echo $OPENAI_API_KEY`} />

3. **Reiniciar servidor local**:

<Code lang="bash" code={`# 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](https://discord.gg/azion)

:::note
  Ao reportar problemas, nunca inclua seu Personal Token em logs ou capturas de tela.
:::

---

## Próximos passos

   - [Desenvolvimento Local MCP](/pt-br/documentacao/devtools/mcp/desenvolvimento-local/)
   - [Teste de Cache MCP](/pt-br/documentacao/devtools/mcp/teste-cache/)