Erros e solução de problemas do MCP MemberPress

O servidor MCP da MemberPress AI Foundation retorna erros estruturados quando uma solicitação falha na autenticação, excede um limite de taxa, não possui escopo ou capacidade, ou chega enquanto as gravações destrutivas estão em pausa. Cada erro contém um código que um cliente de IA ou desenvolvedor pode identificar.

Este guia lista os códigos de erro gerados pelo servidor MCP, mostra o que causa cada um deles e explica como resolvê-los. Uma seção dedicada à solução de problemas aborda os tipos de falhas que ocorrem com mais frequência durante a configuração inicial.

Formato da resposta de erro

O servidor retorna erros em duas camadas, e eles apresentam formatos diferentes. Identificar o campo correto é essencial para um tratamento confiável dos erros.

Erros na camada de transporte são rejeitadas antes do processamento do JSON-RPC — falhas de autenticação e rotas desativadas. Elas utilizam o formato de erro REST do WordPress, com uma string código e um código de status HTTP em data.status:

{
  "code": "auth_required",
  "message": "É necessário o cabeçalho de autorização.",
  "data": { "status": 401 }
}

Erros na camada de ferramentas ocorrem após a autenticação, durante o envio da ferramenta — a camada de segurança e os controles de capacidade. Eles utilizam o formato de erro JSON-RPC 2.0, no qual código é o valor genérico do JSON-RPC -32603 e o identificador estável e compatível é data.mp_error_code:

{
  "code": -32603,
  "message": "As gravações destrutivas foram suspensas por um administrador. Tente novamente mais tarde ou entre em contato com o proprietário do site.",
  "data": { "mp_error_code": "WRITES_PAUSED" },
  "request_id": "req_011Cc7Bhv5NZnRMgQ9Bg2JBo"
}

Jogo em andamento data.mp_error_code, não código. Todo erro na camada de ferramentas retorna o mesmo resultado -32603; apenas mp_error_code é o que os distingue. O request_id é único para cada chamada — útil para suporte, mas nunca para comparação.

Visão geral das categorias de erros

Categoria	Identificador	Camada
Autenticação	auth_required e erros de token	Transporte (data.status: 401)
Rota desativada ou links permanentes	rest_no_route	Transporte (data.status: 404)
Âmbito e capacidade	SCOPE_INSUFICIENTE, CAPACIDADE_INSUFICIENTE	Ferramenta (-32603 + mp_error_code)
Camada de segurança	WRITES_PAUSED, CONFIRMAÇÃO_INVÁLIDA	Ferramenta (-32603 + mp_error_code)
Limitação de taxa	RATE_LIMITED, público, inscrição	Misto — consulte Erros de limite de taxa
Validação	erro_de_validação	Ferramenta (-32603 + mp_error_code)
Recurso e estado	usuário_não_encontrado, nome_de_usuário_duplicado, já_reembolsado, o *_não_encontrado_* família	Ferramenta (-32603 + mp_error_code)
Créditos	créditos_insuficientes, créditos_indisponíveis	Não está acessível por meio das ferramentas do MCP — veja abaixo

Erros de autenticação

O servidor valida as credenciais em cada solicitação. Todas as rotas principais do MCP exigem um token Bearer ou autenticação Basic.

Uma solicitação com sem cabeçalho de autorização é rejeitado na camada de transporte:

{
  "code": "auth_required",
  "message": "É necessário o cabeçalho de autorização.",
  "data": { "status": 401 }
}

Gatilho	Código	Mensagem
Sem credenciais	auth_required	“É necessário um cabeçalho de autorização.”
Cabeçalho com formato incorreto (que não seja Bearer ou Basic)	auth_required	“É necessária autenticação por portador ou básica.”
Token expirado	token_expired	“O token expirou.”
Token revogado ou inexistente	auth_required	“Token inválido ou revogado.”

Um token expirado retorna um código distinto. Um token revogado e um token que nunca existiu são deliberadamente indistinguíveis — os filtros de consulta de tokens excluem as linhas revogadas; portanto, a resposta não revela se um determinado token já existiu.

401 as respostas na rota MCP carregam um WWW-Authenticate cabeçalho com o valor exato Portador realm="mcp", resource_metadata="", e o cabeçalho é exposto por meio do CORS. Os endpoints do OAuth o omitem deliberadamente.

Resolução: Gere um novo token pelo assistente ou reconecte o cliente para executar o fluxo OAuth novamente. Confirme se o token não foi revogado no Clientes conectados ao MCP guia.

Erros de escopo e capacidade

Dois gateways distintos rejeitam uma chamada de ferramenta após a autenticação ter sido bem-sucedida. Ambos são exibidos como erros da camada de ferramentas.

Porta de escopo. Cada ferramenta declara um escopo obrigatório. O servidor compara esse escopo com os escopos concedidos ao token antes do despacho. Uma conexão somente leitura que chama memberpress_create_member não passa por este portão.

Porta de capacidade. Cada ferramenta de edição também declara a capacidade do WordPress de que necessita — por exemplo create_users, editar_usuários, excluir_usuáriosou gerenciar_opções. O servidor verifica a autorização do proprietário do token antes do envio. Um completo-token de escopo pertencente a um usuário sem create_users Ainda não consigo criar membros.

Os portões são executados em ordem — primeiro o scope — e retornam códigos distintos:

Portão	mp_error_code	Mensagem
Escopo	SCOPE_INSUFICIENTE	O escopo obrigatório "%s" não está concedido a este token.
Capacidade	CAPACIDADE_INSUFICIENTE	Capacidade insuficiente para esta ferramenta. O usuário deve ter o "%s".

Ambos utilizam o envelope da camada de ferramentas — -32603 com o identificador do estábulo em data.mp_error_code:

{
  "code": -32603,
  "message": "Permissão insuficiente para esta ferramenta. O usuário deve ter a permissão \"create_users\".",
  "data": { "mp_error_code": "CAPABILITY_INSUFFICIENT" },
  "request_id": "req_..."
}

Resolução:

• Falhas no escopo: A conexão precisa de uma autorização mais ampla. Revogue-a e emita uma nova conexão com os escopos de gravação necessários. O limite de acesso deve ser “Acesso Total” para que novas conexões recebam escopos de gravação;
• Falhas de capacidade: O usuário do WordPress associado ao token não possui a permissão de função necessária. Faça login como um usuário que possua essa permissão ou conceda-a a esse usuário.

Importante: As conexões com senha de aplicativo são sempre somente para leitura. Por padrão, todas as ferramentas de gravação falham na verificação de escopo em uma conexão com senha de aplicativo. Use uma conexão OAuth para gravações.

Erros na camada de segurança

As medidas de segurança do agente geram seus próprios erros na camada de ferramentas. O Referência sobre medidas de segurança para agentes explica as medidas; esta seção lista as recusas.

WRITES_PAUSED

O kill switch suspende todas as gravações destrutivas. Enquanto estiver ativo, o servidor rejeita as ferramentas destrutivas com WRITES_PAUSED — independentemente dos escopos da conexão e mesmo quando a chamada contém um token de confirmação válido.

A recusa ataca o primeiro, chamada sem compromisso: a *pré-visualização* de uma ferramenta destrutiva é bloqueada, e não apenas sua execução. O kill switch bloqueia todo o caminho de gravação destrutiva, de modo que um estado pausado nem mesmo consegue gerar um token de confirmação. As ferramentas de leitura continuam funcionando.

{
  "code": -32603,
  "message": "As gravações destrutivas foram suspensas por um administrador. Tente novamente mais tarde ou entre em contato com o proprietário do site.",
  "data": { "mp_error_code": "WRITES_PAUSED" },
  "request_id": "req_011Cc7Bhv5NZnRMgQ9Bg2JBo"
}

Resolução: um administrador desativa o botão de emergência a partir do Clientes conectados ao MCP guia. A pausa é uma ação administrativa deliberada; verifique o motivo pelo qual ela foi ativada antes de retomar as gravações.

CONFIRMAÇÃO_INVÁLIDA

As ferramentas destrutivas exigem um fluxo de duas chamadas: a primeira chamada retorna uma pré-visualização e um token de confirmação de uso único; a segunda chamada passa o token na confirmar parâmetro. Três causas distintas levam ao mesmo resultado CONFIRMAÇÃO_INVÁLIDA erro — a mensagem não deixa claro o que ocorreu:

Causa	Detalhes
O token expirou	O token já ultrapassou o prazo de validade de 60 segundos
Token já foi usado	Os tokens são de uso único
Os argumentos foram alterados	O token está vinculado à ferramenta, aos argumentos e ao usuário específicos

{
  "code": -32603,
  "message": "O token de confirmação é inválido, está vencido ou os argumentos foram alterados. Chame a ferramenta sem `confirm` para receber uma nova visualização e um novo token.",
  "data": { "mp_error_code": "CONFIRMATION_INVALID" },
  "request_id": "req_011Cc7AK3jF4SA4VLs3qsmBD"
}

Resolução: chame a ferramenta novamente sem confirmar para obter uma pré-visualização e um token novos e, em seguida, confirmar em até 60 segundos usando os mesmos argumentos. Como um único código abrange três causas, um cliente que esteja solucionando problemas deve executar a pré-visualização novamente, em vez de tentar diagnosticar qual proteção foi acionada.

A falha é intencional. Uma resposta simples do tipo “aprovado/reprovado” não revela se um determinado token chegou a existir, e a solução é a mesma em todos os casos: execute novamente a visualização.

As respostas error.data tem um razão campo ao lado do código de nível superior, que permanece inalterado, com dois valores: vencido_ou_utilizado (o token não foi encontrado — expirou, já foi utilizado ou nunca foi emitido; nesses casos, permanece deliberadamente oculto) e arguments_changed (o token estava válido, mas a solicitação diferiu do que foi exibido na pré-visualização — execute a pré-visualização novamente e confirme o novo token).

Erros de limite de taxa

Os limites de taxa independentes protegem o servidor, e a forma da resposta varia de acordo com o ponto-final — o endpoint MCP autenticado não retorna 429 de jeito nenhum.

Superfície	Limite	Resposta
Ponto de extremidade MCP autenticado	120 solicitações por minuto por token (padrão; configurável entre 1 e 1.000) — definido na guia “Configurações do MCP”, onde a limitação de taxa também pode ser totalmente desativada	Erro de JSON-RPC no HTTP 200 — código -32029, mp_error_code: RATE_LIMITED
Endpoint público do MCP	60 solicitações por minuto por IP (fixo)	HTTP 429 com Retry-After: 60
OAuth /registrar	60 registros por hora por endereço IP	HTTP 429 com Retry-After: 3600

O limite do endpoint autenticado é exibido dentro do envelope JSON-RPC, e não como um erro HTTP:

{"jsonrpc":"2.0","id":1,"error":{"code":-32029,"message":"Limite de solicitações excedido.","data":{"mp_error_code":"RATE_LIMITED"}}}

O endpoint público retorna um corpo de erro em JSON-RPC simples com seu 429:

{"jsonrpc":"2.0","error":{"code":-32000,"message":"Limite de solicitações excedido. Tente novamente daqui a um minuto."}}

O endpoint de registro retorna um corpo no estilo OAuth com seu 429:

{"error":"too_many_requests","error_description":"Há um número excessivo de registros de clientes a partir deste IP. Por favor, tente novamente daqui a uma hora."}

Observação: Nenhum ponto final é enviado X-RateLimit-Limit ou X-RateLimit-Remaining cabeçalhos. Os únicos cabeçalhos de limitação de taxa são os Retry-After valores apresentados acima.

Resolução: aguarde até que a janela seja reinicializada. Para o endpoint autenticado, faça a correspondência com mp_error_code: RATE_LIMITED — a 200 O status não significa sucesso — e dê um tempo de pelo menos um minuto. Respeito Retry-After para onde foram enviadas. Para manter um volume legítimo constante, utilize solicitações em lote ou reduza a frequência de consulta.

Erros de validação

Falhas de validação são erros na camada de ferramentas: -32603 com mp_error_code: erro_de_validação. O mensagem isso mesmo explica o problema — indica o valor rejeitado e, quando há um vocabulário aplicável, lista os valores aceitos. Por exemplo, ao criar um webhook com um evento desconhecido, é exibido:

Eventos desconhecidos: member-added. Eventos conhecidos: transaction-completed, ...

As ferramentas de gravação validam os vocabulários de argumentos em relação aos seus esquemas, e os valores legados são rejeitados em favor da enumeração aceita. As ferramentas de cupons são o exemplo documentado: discount_mode aceita padrão ou primeiro pagamentoe tipo de desconto aceita por cento ou dólar. Os valores tradicionais primeiro, todose plano são rejeitados.

Resolução: corrija a entrada conforme descrito na mensagem — ou leia as instruções da ferramenta esquema de entrada em ferramentas/lista — em seguida, reenvie com os valores canônicos. Não tente novamente com os mesmos argumentos.

Erros de recurso e de estado

Além da validação, as ferramentas retornam códigos voltados para o usuário quando uma solicitação está bem formada, mas não pode ser aplicada ao estado atual do site. Esses códigos seguem o mesmo formato da camada da ferramenta (-32603 + mp_error_code), e suas mensagens explicam o motivo diretamente:

Código	Gatilho
usuário_não_encontrado	O membro ou usuário mencionado não existe
*_não_encontrado_* família	O recurso mencionado (transação, assinatura, webhook etc.) não existe
nome_de_usuário_duplicado	Criação de usuário com um nome de usuário já em uso
já_reembolsado	Tentativa de reembolso em uma transação que já havia sido reembolsada
memberpress_not_active	O plug-in MemberPress não está ativo
auto_exclusão_recusada	excluir_membro visando o usuário que está fazendo a chamada — a exclusão da conta associada ao token atual encerraria a sessão. A verificação automática é executada primeiro, portanto, tem prioridade sobre a proteção de administrador
admin_delete_refused	excluir_membro direcionado a qualquer usuário com o gerenciar_opções capacidade. Primeiro, retire os privilégios do usuário no painel de administração do WordPress, caso a exclusão seja intencional

Resolução: Essas são condições de estado, não falhas transitórias — verifique o recurso referenciado (ou o estado do site) e corrija a solicitação. Repetir a tentativa sem alterações não dará certo.

Falhas genuinamente internas — falha ao salvar, falha na exclusão, db_error — são genéricos por definição, de modo que os detalhes da camada de armazenamento não sejam revelados aos clientes. Um cliente que receba uma dessas mensagens só pode tentar novamente mais tarde ou relatar a falha ao administrador do site.

Erros de crédito — não acessíveis por meio do MCP

As chamadas de pré-visualização passam pelas mesmas restrições de lista de permissão que a execução em produção e apresentam as mesmas mp_error_code — uma ferramenta não pode revelar, em sua pré-visualização, um erro interno que a execução em tempo real mascararia.

A lista de permissões de erros do servidor inclui dois códigos relacionados a crédito: créditos_insuficientes e créditos_indisponíveis. Nenhuma ferramenta do MCP consome créditos de IA, e o servidor do MCP não chama nenhum método relacionado a créditos. Os códigos existem para que os serviços posteriores possam transmitir erros relacionados a créditos por meio da resposta JSON-RPC; nenhum caminho de chamada das ferramentas do MCP os gera.

Um cliente que utiliza as ferramentas do MCP nunca se depara com esses códigos. Os saldos credores afetam os recursos de geração baseados no Mastermind (por exemplo, o Course Copilot), e não as chamadas às ferramentas do MCP.

Solução de problemas relacionados a falhas na configuração

Modos de falha que surgem durante a conexão inicial, na ordem em que os usuários normalmente os encontram:

• O endpoint MCP autenticado retorna 404: Os permalinks estão configurados como “Simples”. A API REST exige permalinks do tipo “Nome da postagem” ou mais detalhados;
• O endpoint público do MCP retorna 404 (rest_no_route): O catálogo público está desativado. Quando desativado, a rota não é montada; portanto, qualquer solicitação retorna rest_no_route — a existência do ponto final não é revelada. Habilite o catálogo no Configurações do MCP guia;
• O endpoint retorna 401 (auth_required) em um navegador: comportamento esperado. O 401 confirma que o endpoint está ativo; o navegador não possui nenhum cabeçalho de autorização;
• O Claude Desktop mostra o conector, mas não exibe as ferramentas: a aprovação do OAuth não foi concluída ou a conexão foi revogada. Abra o conector e reconecte-se;
• etapa=erro_inicial durante a conexão com o Claude Desktop: O registro via OAuth está limitado a 60 tentativas por hora por endereço IP. Aguarde até que o limite seja reiniciado e tente novamente;
• Um cliente de terceiros não pode se cadastrar via OAuth (uri_de_redirecionamento_inválido): O ponto de extremidade de registro dinâmico aceita apenas URIs de redirecionamento incluídas na lista de permissões (os clientes de IA conhecidos). Um cliente cuja URI de redirecionamento não conste na lista de permissões é rejeitado em /registrar;
• Falta uma ferramenta esperada em ferramentas/lista: a ferramenta pertence a um complemento inativo. As ferramentas de complementos só ficam registradas enquanto o respectivo complemento estiver ativo. Ao chamar uma ferramenta não registrada, é retornado o erro padrão de método desconhecido do JSON-RPC;
• Caixas de seleção que faltam no assistente: O limite de acesso está definido como “Somente leitura”. O assistente oculta os escopos de gravação e exibe um aviso. Aumente o limite do Configurações do MCP guia;
• Uma ferramenta destrutiva exibe uma pré-visualização em vez de executar: comportamento esperado. Ferramentas destrutivas exigem o fluxo de confirmação em duas etapas. Passe o token retornado no confirmar parâmetro em até 60 segundos.

Orientações para o tratamento de erros

• Jogo em andamento data.mp_error_code para erros na camada de ferramentas e em código mais data.status para erros na camada de transporte. Nunca faça a correspondência diretamente no -32603;
• auth_required / 401: Faça uma nova autenticação. Não tente novamente com as mesmas credenciais; falhas repetidas acionam o bloqueio por ataque de força bruta;
• SCOPE_INSUFICIENTE / CAPACIDADE_INSUFICIENTE: Não tente novamente. A conexão requer uma autorização de escopo mais amplo, ou o usuário por trás do token precisa da permissão do WordPress que está faltando — uma nova tentativa não terá sucesso;
• WRITES_PAUSED: não tentar novamente automaticamente. Um administrador suspendeu deliberadamente as gravações destrutivas; exibir o estado ao usuário;
• erro_de_validação: corrija a entrada conforme descrito na mensagem e, em seguida, reenvie. Não tente novamente com os mesmos argumentos — a mesma entrada gera a mesma rejeição;
• CONFIRMAÇÃO_INVÁLIDA: reinicie o fluxo de duas chamadas a partir da chamada de pré-visualização. Um código abrange três causas; portanto, execute novamente a pré-visualização em vez de tentar diagnosticar qual delas foi acionada. Nunca armazene tokens de confirmação em cache;
• Limites de taxa: Deixe isso pra lá. O ponto de extremidade autenticado sinaliza RATE_LIMITED dentro de um HTTP 200; os endpoints públicos e de registro retornam 429 com Retry-After. Respeito Retry-After se tiver sido enviado; caso contrário, aguarde pelo menos um minuto.

Documentação relacionada

• Visão geral e guia de configuração do MemberPress AI Foundation — instalação, pré-requisitos e verificações pós-instalação;
• Conectando clientes de IA ao MemberPress – Referência para desenvolvedores — métodos de autenticação e configuração por cliente;
• Referência às ferramentas MCP do MemberPress AI Foundation — escopos, recursos e esquemas por ferramenta;
• Medidas de segurança para agentes da MemberPress AI Foundation — as quatro medidas responsáveis pelos erros na camada de segurança.