Diagnóstico do servidor MCP
Erros comuns na conexão de assistentes de IA — 401, 403, 404, cabeçalho Authorization, OAuth em subpasta e domínio de redirecionamento.
Avançado2 min de leitura
Comece sempre pelo botão Testar conexão em Converto → IA → Conexão: ele cobre as causas mais comuns e explica cada falha.
Respostas do servidor
| Resposta | Mensagem | Causa e solução |
|---|---|---|
404 (rest_no_route) | "No route was found matching the URL and request method." | O servidor MCP está desativado. Ative em Converto → IA e salve. Confira também se a REST API do WordPress está acessível. |
401 (mcp_unauthorized) | "Autenticação necessária (OAuth, token ou Senha de aplicativo)." | Nenhuma credencial enviada. |
401 (mcp_unauthorized) | "Token inválido ou expirado." | O token estático foi substituído (gerar outro revoga o anterior) ou o token OAuth expirou. Gere um novo ou reconecte. |
403 (mcp_forbidden) | "Seu usuário não pode editar páginas." | O usuário que autenticou não tem permissão de edição de páginas. |
| 405 | — | GET e DELETE não existem; use POST. |
| 413 | "Mensagem grande demais." | O corpo ultrapassou 1 MB. |
| 400 | "JSON inválido." | Corpo não é JSON válido. |
Cabeçalho Authorization removido (Apache)
Se o teste mostrar "Cabeçalho Authorization" com falha, o servidor web removeu o cabeçalho antes de chegar ao PHP. Em Apache, adicione ao .htaccess do WordPress:
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1OAuth
| Sintoma | Solução |
|---|---|
| O cliente não encontra a autorização | Em instalações em subpasta, o WordPress não recebe /.well-known da raiz do domínio. O Converto oferece rotas REST equivalentes, mas o cliente pode exigir a URL na raiz: configure uma regra no servidor apontando /.well-known/oauth-* para o WordPress. O teste mostra "Descoberta OAuth (/.well-known)" como alerta. |
| "redirect_uri" recusado | O domínio do cliente não está na lista. Adicione em Converto → IA → Domínios de redirecionamento OAuth e salve. Padrão aceito: claude.ai, claude.com, chatgpt.com, chat.openai.com, platform.openai.com e localhost. |
| "PKCE com code_challenge_method=S256 é obrigatório." | O cliente não envia PKCE S256. Use um cliente compatível com OAuth 2.1. |
code_verifier inválido | O fluxo foi interrompido ou repetido; inicie a conexão de novo. |
| Muitas tentativas | Limites: 10 registros por hora e 60 trocas de token por minuto. Aguarde. |
| Cliente "perdeu" a conexão | Verifique a tabela Aplicativos conectados; se foi revogado, reconecte. |
HTTPS
OAuth e senhas de aplicativo exigem HTTPS em produção. O teste avisa quando o site não usa HTTPS.
Ferramentas
| Mensagem | Significado |
|---|---|
| "Ferramenta desconhecida: …" | O cliente chamou uma ferramenta que não existe; atualize a lista de ferramentas. |
| "Informe ids e/ou intents." | get_widget_spec exige ao menos um dos dois. |
| "Erro interno ao executar a ferramenta." | Falha inesperada; consulte o log de erros do PHP (prefixo [converto-mcp]). |
Este artigo foi útil?
Artigos relacionados
IA e Markdown
Conectando um assistente
Passo a passo para conectar clientes de IA ao servidor MCP — token estático, OAuth, domínios permitidos, aplicativos conectados e teste de conexão.
IA e Markdown
Servidor MCP
Conecte assistentes de IA ao seu site pelo Model Context Protocol — como ligar, o endpoint, as ferramentas expostas e as permissões.
IA e Markdown
Segurança do MCP
Boas práticas e salvaguardas do servidor MCP — acesso desligado por padrão, permissões do WordPress, tokens com hash, OAuth com PKCE e revogação.