Errores y resolución de problemas del MCP MemberPress

El servidor MCP de MemberPress AI Foundation devuelve errores estructurados cuando una solicitud no supera la autenticación, supera un límite de frecuencia, carece de ámbito o capacidad, o se recibe mientras las escrituras destructivas están en pausa. Cada error incluye un código que un cliente de IA o un desarrollador puede identificar.

Esta guía recoge los códigos de error que genera el servidor MCP, indica qué provoca cada uno de ellos y explica cómo solucionarlos. La sección dedicada a la resolución de problemas aborda los fallos que suelen producirse con mayor frecuencia durante la configuración inicial.

Forma de la respuesta de error

El servidor devuelve errores en dos niveles, y estos tienen formas diferentes. Es fundamental identificar el campo correcto para gestionar los errores de forma fiable.

Errores en la capa de transporte se rechazan antes del procesamiento de JSON-RPC: errores de autenticación y rutas desmontadas. Utilizan el formato de error REST de WordPress, con una cadena código y un estado HTTP en data.status:

{
  "code": "auth_required",
  "message": "Se requiere el encabezado de autorización.",
  "data": { "status": 401 }
}

Errores en la capa de herramientas se producen tras la autenticación, durante el envío de herramientas: la capa de seguridad y los controles de capacidad. Utilizan el formato de error JSON-RPC 2.0, en el que código es el valor genérico de JSON-RPC -32603 y el identificador estable y combinable es data.mp_error_code:

{
  "code": -32603,
  "message": "Las escrituras destructivas han sido suspendidas por un administrador. Inténtalo de nuevo más tarde o ponte en contacto con el propietario del sitio.",
  "data": { "mp_error_code": "WRITES_PAUSED" },
  "request_id": "req_011Cc7Bhv5NZnRMgQ9Bg2JBo"
}

Partido en data.mp_error_code, no código. Cada error de la capa de herramientas devuelve lo mismo -32603; solo mp_error_code es lo que los distingue. El request_id Es único por llamada; resulta útil para la asistencia técnica, pero nunca para la comparación.

Resumen de las categorías de errores

Categoría	Identificador	Capa
Autenticación	auth_required y errores de tokens	Transporte (data.status: 401)
Ruta desactivada o enlaces permanentes	rest_sin_ruta	Transporte (data.status: 404)
Ámbito de aplicación y capacidades	SCOPE_INSUFFICIENT, CAPACIDAD_INSUFICIENTE	Herramienta (-32603 + mp_error_code)
Capa de seguridad	ESCRITURA_EN_PAUSA, CONFIRMACIÓN_NO VÁLIDA	Herramienta (-32603 + mp_error_code)
Limitación de velocidad	RATE_LIMITED, público, inscripción	Varios — véase «Errores de límite de solicitudes»
Validación	error de validación	Herramienta (-32603 + mp_error_code)
Recursos y situación	usuario_no_encontrado, nombre_de_usuario_duplicado, ya_reembolsadoEl *_no_encontrado_* familia	Herramienta (-32603 + mp_error_code)
Agradecimientos	créditos insuficientes, créditos_no_disponibles	No se puede acceder a través de las herramientas de MCP — véase más abajo

Errores de autenticación

El servidor comprueba las credenciales en cada solicitud. Todas las rutas principales de MCP requieren un token «Bearer» o autenticación «Basic».

Una solicitud con No hay encabezado «Authorization» se rechaza en la capa de transporte:

{
  "code": "auth_required",
  "message": "Se requiere el encabezado de autorización.",
  "data": { "status": 401 }
}

Disparador	Código	Mensaje
Sin credenciales	auth_required	“Se requiere un encabezado de autorización”.”
Encabezado con formato incorrecto (no es «Bearer» ni «Basic»)	auth_required	“Se requiere autenticación de portador o básica”.”
Token caducado	token_caducado	“El token ha caducado”.”
Token revocado o inexistente	auth_required	“Token no válido o revocado”.”

Un token caducado devuelve un código distinto. Un token revocado y un token que nunca ha existido son deliberadamente indistinguibles — Los filtros de búsqueda de tokens excluyen las filas revocadas, por lo que la respuesta no revela si un token concreto ha existido alguna vez.

401 Las respuestas en la ruta MCP conllevan un WWW-Authenticate encabezado con el valor exacto Portador realm="mcp", resource_metadata="", y el encabezado se expone a través de CORS. Los puntos finales de OAuth lo omiten deliberadamente.

Resolución: Genera un nuevo token mediante el asistente o vuelve a conectar el cliente para ejecutar de nuevo el flujo de OAuth. Comprueba que el token no haya sido revocado en el Clientes conectados a MCP ficha.

Errores de alcance y capacidad

Hay dos puertas de control distintas que rechazan una llamada a una herramienta tras una autenticación correcta. Ambas se manifiestan como errores de la capa de herramientas.

Puerta de alcance. Cada herramienta declara un ámbito de acceso necesario. El servidor lo compara con los ámbitos de acceso concedidos al token antes de la ejecución. Una conexión de solo lectura que invoca memberpress_create_member no supera esta prueba.

Puerta de capacidad. Cada herramienta de escritura también declara la capacidad de WordPress que necesita; por ejemplo, create_users, editar_usuarios, eliminar_usuarioso gestionar_opciones. El servidor comprueba la capacidad del propietario del token antes de la distribución. Un completo-token de ámbito propiedad de un usuario sin create_users Sigo sin poder crear miembros.

Las puertas se ejecutan en orden —primero «scope»— y devuelven códigos distintos:

Puerta	mp_error_code	Mensaje
Alcance	SCOPE_INSUFFICIENT	El ámbito "%s" no está concedido en este token.
Capacidad	CAPACIDAD_INSUFICIENTE	Capacidad insuficiente para esta herramienta. El usuario debe disponer de "%s".

Ambos utilizan la envolvente de la capa de herramientas — -32603 con el identificador de la cuadra en data.mp_error_code:

{
  "code": -32603,
  "message": "Capacidad insuficiente para esta herramienta. El usuario debe tener el permiso \"create_users\".",
  "data": { "mp_error_code": "CAPABILITY_INSUFFICIENT" },
  "request_id": "req_..."
}

Resolución:

• Fallos del visor: La conexión requiere una autorización más amplia. Revócala y crea una nueva conexión con los ámbitos de escritura necesarios. El nivel máximo de acceso debe ser «Acceso completo» para que las nuevas conexiones puedan recibir ámbitos de escritura;
• Fallos de capacidad: El usuario de WordPress asociado al token no dispone de la capacidad de rol necesaria. Inicia sesión como un usuario que tenga esa capacidad o concédesela a ese usuario.

Importante: Las conexiones con contraseña de aplicación son siempre de solo lectura. Por diseño, todas las herramientas de escritura fallan en la comprobación de ámbito en una conexión con contraseña de aplicación. Utiliza una conexión OAuth para las operaciones de escritura.

Errores de la capa de seguridad

Las medidas de seguridad de los agentes generan sus propios errores en la capa de herramientas. El Referencia sobre medidas de seguridad para agentes explica las medidas; en esta sección se recogen sus rechazos.

ESCRITURA_EN_PAUSA

El «kill switch» detiene temporalmente cualquier escritura destructiva. Mientras está activo, el servidor rechaza las herramientas destructivas con ESCRITURA_EN_PAUSA — independientemente de los ámbitos de la conexión e incluso cuando la llamada incluya un token de confirmación válido.

Los disparos de rechazo contra el primera llamada sin compromiso: la *vista previa* de una herramienta destructiva queda bloqueada, no solo su ejecución. El «kill switch» bloquea toda la ruta de escritura destructiva, por lo que un estado en pausa ni siquiera puede generar un token de confirmación. Las herramientas de lectura siguen funcionando.

{
  "code": -32603,
  "message": "Las escrituras destructivas han sido suspendidas por un administrador. Inténtalo de nuevo más tarde o ponte en contacto con el propietario del sitio.",
  "data": { "mp_error_code": "WRITES_PAUSED" },
  "request_id": "req_011Cc7Bhv5NZnRMgQ9Bg2JBo"
}

Resolución: un administrador desactiva el «kill switch» desde el Clientes conectados a MCP pestaña. La pausa es una medida administrativa deliberada; comprueba por qué se ha activado antes de reanudar las operaciones de escritura.

CONFIRMACIÓN_NO VÁLIDA

Las herramientas destructivas requieren un flujo de dos llamadas: la primera llamada devuelve una vista previa y un token de confirmación de un solo uso; la segunda llamada pasa el token en el confirmar parámetro. Tres causas distintas dan el mismo resultado CONFIRMACIÓN_NO VÁLIDA error — El mensaje no aclara qué de las dos cosas ocurrió:

Causa	Detalle
El token ha caducado	El token tiene una antigüedad superior a los 60 segundos de su ventana de validez
El token ya se ha utilizado	Los vales son de un solo uso
Los argumentos han cambiado	El token se vincula a la herramienta, los argumentos y el usuario concretos

{
  "code": -32603,
  "message": "El token de confirmación no es válido, ha caducado o los argumentos han cambiado. Llama a la herramienta sin `confirm` para obtener una vista previa y un token nuevos.",
  "data": { "mp_error_code": "CONFIRMATION_INVALID" },
  "request_id": "req_011Cc7AK3jF4SA4VLs3qsmBD"
}

Resolución: vuelve a ejecutar la herramienta sin confirmar para obtener una vista previa y un token nuevos, y a continuación confirmar en un plazo de 60 segundos utilizando los mismos argumentos. Dado que un código abarca tres causas, un cliente que esté resolviendo un problema debería volver a ejecutar la vista previa en lugar de intentar diagnosticar qué protección se ha activado.

El fallo es intencionado. Una simple respuesta de «aprobado/suspendido» no revela si un token concreto llegó a existir, y la solución es la misma en todos los casos: volver a ejecutar la vista previa.

La respuesta es error.data tiene un razón campo junto al código de nivel superior, que no ha sufrido cambios, con dos valores: caducado_o_utilizado (el token no se ha encontrado —caducado, ya utilizado o que nunca se ha emitido— y permanece ocultado de forma deliberada) y arguments_changed (El token era válido, pero la solicitud no se correspondía con lo que se había previsualizado; vuelve a ejecutar la previsualización y confirma el nuevo token).

Errores de límite de solicitudes

Los límites de velocidad independientes protegen el servidor, y la forma de la respuesta varía según el punto final — el punto final MCP autenticado no devuelve 429 en absoluto.

Superficie	Límite	Respuesta
Punto final MCP autenticado	120 solicitudes por minuto por token (valor predeterminado; configurable entre 1 y 1000): se configura en la pestaña «Configuración de MCP», donde también se puede desactivar por completo la limitación de velocidad.	Error de JSON-RPC en HTTP 200 — código -32029, mp_error_code: RATE_LIMITED
Punto final público de MCP	60 solicitudes por minuto por dirección IP (fijo)	HTTP 429 con Retry-After: 60
OAuth /registrarse	60 registros por hora por dirección IP	HTTP 429 con Retry-After: 3600

El límite del punto final autenticado aparece dentro de la envoltura JSON-RPC, no como un error HTTP:

{"jsonrpc":"2.0","id":1,"error":{"code":-32029,"message":"Se ha superado el límite de solicitudes.","data":{"mp_error_code":"RATE_LIMITED"}}}

El punto final público devuelve un cuerpo de error JSON-RPC sin formato con su 429:

{"jsonrpc":"2.0","error":{"code":-32000,"message":"Se ha superado el límite de solicitudes. Inténtalo de nuevo dentro de un minuto."}}

El punto final de registro devuelve un cuerpo de tipo OAuth con su 429:

{"error":"too_many_requests","error_description":"Demasiados registros de clientes desde esta IP. Inténtalo de nuevo dentro de una hora."}

Nota: No se envían mensajes desde ningún punto final X-RateLimit-Limit o X-Límite de velocidad restante encabezados. Los únicos encabezados de limitación de velocidad son los Retry-After los valores que se indican más arriba.

Resolución: Espera a que se reinicie la ventana. Para el punto final autenticado, busca coincidencias en mp_error_code: RATE_LIMITED — a 200 El estatus no es sinónimo de éxito — y mantén la distancia al menos un minuto. Respeto Retry-After dónde se envía. Para mantener un volumen legítimo constante, realiza solicitudes por lotes o reduce la frecuencia de consulta.

Errores de validación

Los errores de validación son errores de la capa de herramientas: -32603 con mp_error_code: error_de_validación. En mensaje Esto explica por sí mismo el problema: indica el valor rechazado y, cuando hay un vocabulario aplicable, enumera los valores aceptados. Por ejemplo, al crear un webhook con un evento desconocido, se obtiene el siguiente resultado:

Eventos desconocidos: «member-added». Eventos conocidos: «transaction-completed», ...

Las herramientas de escritura validan los vocabularios de argumentos según sus esquemas, y los valores heredados se rechazan si no se ajustan a la enumeración aceptada. Las herramientas de cupones son el ejemplo documentado: modo_descuento acepta estándar o primer pagoy tipo_descuento acepta por ciento o dólar. Los valores heredados primero, todosy plano se rechazan.

Resolución: corrige la entrada tal y como se indica en el mensaje, o consulta la documentación de la herramienta esquema de entrada en herramientas/lista — y, a continuación, vuelve a enviarla con los valores canónicos. No vuelvas a intentar enviar los mismos argumentos.

Errores de recursos y de estado

Más allá de la validación, las herramientas devuelven códigos destinados al usuario cuando una solicitud está bien formada, pero no se puede aplicar al estado actual del sitio. Estos siguen el mismo formato de la capa de la herramienta (-32603 + mp_error_code), y en sus mensajes se explica directamente el motivo:

Código	Disparador
usuario_no_encontrado	El miembro o usuario al que se hace referencia no existe.
*_no_encontrado_* familia	El recurso al que se hace referencia (transacción, suscripción, webhook, etc.) no existe.
nombre_de_usuario_duplicado	Creación de un usuario con un nombre de usuario ya en uso
ya_reembolsado	Se ha intentado realizar un reembolso de una transacción que ya había sido reembolsada
memberpress_not_active	El complemento MemberPress no está activo
autoeliminación rechazada	eliminar_miembro dirigido al usuario que realiza la llamada: eliminar la cuenta asociada al token actual pondría fin a la sesión. La comprobación automática se ejecuta primero, por lo que tiene prioridad sobre el control de acceso de administrador.
admin_delete_rechazado	eliminar_miembro dirigirse a cualquier usuario con el gestionar_opciones capacidad. Si la eliminación es intencionada, retira primero los privilegios al usuario en el panel de administración de WordPress.

Resolución: Se trata de condiciones del estado del sistema, no de fallos pasajeros: comprueba el recurso al que se hace referencia (o el estado del sitio) y corrige la solicitud. Volver a intentarlo sin realizar cambios no dará resultado.

Fallos verdaderamente internos — error_al_guardar, eliminación fallida, db_error — están concebidos para ser genéricos, de modo que los detalles de la capa de almacenamiento no se revelen a los clientes. Un cliente que reciba uno de estos mensajes solo puede volver a intentarlo más tarde o informar del fallo al administrador del sitio.

Errores de crédito: no se puede acceder a ellos a través de MCP

Las llamadas de vista previa pasan por la misma lista de permitidos que la ejecución en producción y tienen las mismas mp_error_code — Una herramienta no puede revelar en su vista previa un error interno que la ejecución en tiempo real ocultaría.

La lista de excepciones de errores del servidor incluye dos códigos relacionados con el crédito: créditos insuficientes y créditos_no_disponibles. Ninguna herramienta del MCP consume créditos de IA, y el servidor del MCP no invoca ningún método relacionado con los créditos. Los códigos existen para que los servicios posteriores puedan transmitir los errores relacionados con los créditos a través de la respuesta JSON-RPC; ninguna ruta de llamada de las herramientas del MCP los genera.

Un cliente que utilice las herramientas de MCP nunca se encuentra con estos códigos. Los saldos acreedores afectan a las funciones de generación basadas en Mastermind (por ejemplo, Course Copilot), pero no a las llamadas a las herramientas de MCP.

Solución de problemas relacionados con fallos en la configuración

Modos de fallo que se producen durante la conexión inicial, en el orden en que los usuarios suelen encontrarlos:

• El punto final MCP autenticado devuelve 404: Los enlaces permanentes están configurados como «Plain». La API REST requiere enlaces permanentes con el nombre de la entrada o más detallados;
• El punto final público de MCP devuelve 404 (rest_sin_ruta): El catálogo público está desactivado. Cuando está desactivado, la ruta no se monta, por lo que cualquier solicitud devuelve rest_sin_ruta — No se revela la existencia del punto final. Habilita el catálogo en el Configuración de MCP ficha;
• El punto final devuelve 401 (auth_required) en un navegador: comportamiento esperado. El 401 confirma que el punto final está activo; el navegador no incluye ningún encabezado de autorización;
• Claude Desktop muestra el conector, pero no las herramientas: La autorización de OAuth no se ha completado o se ha revocado la conexión. Abre el conector y vuelve a conectarte;
• paso=error_inicial Durante la conexión a Claude Desktop: El registro mediante OAuth tiene un límite de 60 intentos por hora por dirección IP. Espera a que se reinicie el contador y vuelve a intentarlo;
• Un cliente externo no puede registrarse mediante OAuth (uri_de_redirección_no_válida): El punto final de registro dinámico solo acepta URI de redirección incluidas en la lista de permitidos (los clientes de IA conocidos). Un cliente cuya URI de redirección no figure en la lista de permitidos es rechazado en /registrarse;
• Falta una herramienta que se esperaba encontrar en herramientas/lista: La herramienta pertenece a un complemento inactivo. Las herramientas de los complementos solo se registran mientras el complemento correspondiente está activo. Al llamar a una herramienta no registrada, se devuelve el error estándar de JSON-RPC «método desconocido»;
• Casillas de selección que faltan en el asistente: El límite de acceso está establecido en «Solo lectura». El asistente oculta los ámbitos de escritura y muestra un aviso. Aumenta el límite en el Configuración de MCP ficha;
• Una herramienta destructiva muestra una vista previa en lugar de ejecutarse: Comportamiento esperado. Las herramientas destructivas requieren el flujo de confirmación de dos llamadas. Pasa el token devuelto en el confirmar parámetro en un plazo de 60 segundos.

Orientaciones sobre la gestión de errores

• Partido en data.mp_error_code en cuanto a errores en la capa de herramientas, y en código y data.status por errores en la capa de transporte. Nunca realices la coincidencia sobre el -32603;
• auth_required / 401: Vuelve a iniciar sesión. No vuelvas a intentarlo con las mismas credenciales; los fallos repetidos activan el bloqueo por ataque de fuerza bruta;
• SCOPE_INSUFFICIENT / CAPACIDAD_INSUFICIENTE: No volver a intentarlo. La conexión requiere una autorización de mayor alcance, o bien el usuario asociado al token carece de la capacidad de WordPress necesaria; un nuevo intento no dará resultado;
• ESCRITURA_EN_PAUSA: No volver a intentarlo automáticamente. Un administrador ha suspendido deliberadamente las operaciones de escritura destructivas; mostrar el estado al usuario;
• error de validación: corrige la entrada tal y como se indica en el mensaje y, a continuación, vuelve a enviarla. No vuelvas a intentar con los mismos argumentos: la misma entrada da lugar al mismo rechazo;
• CONFIRMACIÓN_NO VÁLIDA: Reinicia el flujo de dos llamadas desde la llamada de vista previa. Un código abarca tres causas, así que vuelve a ejecutar la vista previa en lugar de intentar determinar cuál se ha activado. Nunca almacenes en caché los tokens de confirmación;
• Límites de frecuencia: Retírate. El punto final autenticado indica RATE_LIMITED dentro de un HTTP 200; los puntos finales públicos y de registro devuelven 429 con Retry-After. Respeto Retry-After si se ha enviado; de lo contrario, espera al menos un minuto.

Documentación relacionada

• Guía general y de configuración de MemberPress AI Foundation — instalación, requisitos previos y comprobaciones tras la instalación;
• Conexión de clientes de IA a MemberPress – Referencia para desarrolladores — métodos de autenticación y configuración por cliente;
• Referencia de herramientas MCP de MemberPress AI Foundation — ámbitos, capacidades y esquemas de cada herramienta;
• Medidas de seguridad para los agentes de MemberPress AI Foundation — las cuatro medidas que están detrás de los errores de la capa de seguridad.