Contrato de transporte MCP

POM AI usa automáticamente la API de Abilities de WordPress y su adaptador MCP oficial incluido en WordPress 6.9+. WordPress 6.8 conserva el transporte estándar. No hay ningún conmutador de transporte ni se necesita un plugin adaptador por separado.

El endpoint MCP con alcance de sitio es:

/wp-json/pom-ai-mcp/v1/mcp

Usa el endpoint canónico que muestra el sitio en lugar de construir una URL entre sitios en una multisitio.

Ejecución en segundo plano

Las herramientas del catálogo, las lecturas de recursos y la generación de prompts se ejecutan mediante eventos programados de WordPress. Enviar una tarea y leer su estado con pom_get_task son síncronos: la solicitud HTTP responde después de guardar o leer el recibo, sin esperar al cron. La autenticación, la negociación del protocolo, el descubrimiento del catálogo y la identidad del sitio también siguen siendo solicitudes HTTP breves.

Cada sitio de destino puede tener una tarea siguiente lista para su ejecutor de cron, mientras que las tareas posteriores de ese sitio esperan. El ejecutor configurado determina cuándo comienza una tarea lista. Solo se ejecuta una operación pesada a la vez en toda la instalación. La recuperación restaura los eventos que faltan, y los nuevos envíos no posponen una recuperación que ya está pendiente.

El descubrimiento de sitio y de red anuncia contract_version: 3 para este contrato de resultados asíncrono. Reconecta y actualiza el descubrimiento al actualizar una integración que antes esperaba resultados de operación inmediatos.

El envío de una herramienta devuelve un recibo con task_id, status, phase, terminal, blog_id, created_at, started_at y expires_at. Los recibos pendientes incluyen poll_after_seconds, y el envío identifica poll_tool: pom_get_task. Llama a pom_get_task con el mismo task_id en la misma conexión autenticada después de la demora indicada. Para tareas de red, sigue sondeando a través de la conexión del sitio principal de origen.

Usa la demora de cada recibo pendiente, que aumenta de cinco a treinta segundos a medida que la tarea envejece. Repite las lecturas de estado mientras terminal sea falso; detén el sondeo automático cuando sea verdadero. created_at identifica la hora de envío, y started_at se completa cuando comienza la ejecución. La fase explica el progreso sin cambiar los valores de estado establecidos.

Una operación lenta permanece en running mientras su trabajador está activo. El tiempo transcurrido por sí solo no hace que una tarea sea terminal; sigue su demora de sondeo hasta que se informe de su finalización o de un fallo confirmado.

Una tarea completada devuelve la respuesta de operación original en result. Los resultados de operaciones de red conservan su blog_id, isError y result internos; inspecciona el error interno incluso cuando la tarea externa haya finalizado. Una tarea de preparación completada puede contener una revisión de escritura pendiente, que aún requiere la aprobación del usuario.

Nunca vuelvas a enviar una operación en cola o en ejecución para comprobar su progreso, y nunca repitas automáticamente una escritura incierta. Una tarea en cola tiene una hora para comenzar. Una vez que termina, su resultado se conserva hasta una hora desde su finalización. Cuando se necesita capacidad de recibos o de almacenamiento para trabajo nuevo, los recibos terminales más antiguos pueden eliminarse antes; las tareas en cola y en ejecución nunca se eliminan para hacer sitio. Guarda los resultados cuando los recibas.

expires_at es el plazo de retención más reciente para un recibo terminal, el plazo de inicio para una tarea en cola, y null mientras está en ejecución. Los recibos terminales incluyen un recordatorio de retention. Si falta el recibo o ha expirado, inspecciona el destino antes de otra escritura: perder el recibo no demuestra que la operación nunca se haya ejecutado.

Las herramientas de publicaciones integradas leen y escriben mediante funciones de WordPress; no envían solicitudes HTTP a /wp-json/wp/v2/posts ni abren páginas en un navegador. Leer el estado de su tarea con pom_get_task no repite la operación de la publicación. Abrir una página por separado en un navegador puede activar la analítica normal de esa página, incluidas las visitas de las vistas previas basadas en navegador.

Las lecturas de recursos devuelven el recibo como texto JSON en la envoltura del recurso. Las solicitudes de prompt lo devuelven como un mensaje de texto. Sondea pom_get_task para recuperar la respuesta completa original del recurso o del prompt. Los clientes MCP deben seguir este flujo de trabajo asíncrono.

Transporte estándar: métodos HTTP

• GET devuelve la disponibilidad y los metadatos de conexión para las comprobaciones de estado.
• POST acepta mensajes JSON-RPC 2.0 como un único objeto. Los lotes JSON-RPC se rechazan.
• OPTIONS admite el comportamiento de preflight de origen cruzado configurado.
• DELETE borra la sesión opcional de elicitación de formularios cuando se negoció una.

El transporte normalmente utiliza HTTP de solicitud/respuesta. Los clientes compatibles que anuncian elicitación de formularios y aceptan text/event-stream pueden recibir un flujo POST breve que contiene una solicitud de diálogo de revisión y el resultado pendiente de la herramienta. El flujo se cierra inmediatamente; el POST de respuesta autenticado registra la decisión del usuario. Usa el enlace de revisión web devuelto si el cliente no puede completar este intercambio.

Transporte estándar: negociación del protocolo

El servidor actual admite las versiones de protocolo MCP 2025-06-18 y 2025-03-26; la primera es la predeterminada. Los clientes deben enviar la versión que implementan y usar el protocolVersion negociado devuelto por initialize. El filtro público pom_ai_mcp_supported_protocol_versions puede cambiar deliberadamente el conjunto admitido.

initialize anuncia herramientas, recursos y prompts con listChanged: true. Actualiza sus listas cuando el cliente se reconecte o reciba una razón para esperar que las capacidades del sitio hayan cambiado.

Trata el protocolo negociado y las capacidades anunciadas como autoritativos. Una implementación MCP diferente puede usar la misma URL de endpoint mientras cambia los requisitos de sesión, los métodos HTTP admitidos o las herramientas disponibles; reconecta y vuelve a descubrir después de que un administrador cambie la implementación de la conexión.

Las notificaciones cuyo método comienza con notifications/ y no tienen ID no producen ninguna respuesta. Los métodos de solicitud desconocidos devuelven el error JSON-RPC de método no encontrado.

Transporte del adaptador MCP de WordPress

El modo nativo requiere WordPress 6.9+. POM AI incluye el adaptador MCP oficial 0.6.1 y usa el autocargador compartido de Jetpack para coexistir con otras integraciones. El adaptador cargado debe permanecer dentro de >=0.6.1 <0.7.0. Usa la misma URL del sitio, la autorización OAuth y la configuración de la clave de API. Las dependencias faltantes o incompatibles detienen las conexiones nativas sin volver al transporte estándar. Actualiza o reinstala el paquete completo de POM AI si su tiempo de ejecución está incompleto.

Al inicializar el MCP nativo, POM AI desactiva el servidor predeterminado genérico del adaptador y expone su catálogo revisado explícito. No registra un ejecutor de abilities genérico ni expone automáticamente abilities de terceros. Otras integraciones pueden registrar sus propios servidores personalizados, con sus propias políticas de autorización.

• POST acepta un mensaje JSON-RPC por solicitud. Los lotes JSON-RPC se rechazan; las herramientas de dominio que aceptan lotes siguen funcionando.
• initialize negocia un protocolo admitido (2025-11-25, 2025-06-18 o 2024-11-05) y devuelve Mcp-Session-Id. Envía esa cabecera de sesión en las solicitudes posteriores.
• GET devuelve 405 porque este transporte no proporciona un flujo SSE.
• DELETE finaliza la sesión. Reinicializa después de la expiración o finalización de la sesión.
• Las respuestas no deben almacenarse en caché. Los clientes de navegador deben usar un Origin permitido configurado.

El adaptador gestiona la negociación del protocolo, las sesiones y la serialización de herramientas/recursos/prompts. Sus capacidades anunciadas son autoritativas; el filtro de protocolo del transporte estándar no cambia la negociación nativa. Las conexiones con clave de API requieren un Service user ID con la capability de WordPress read. OAuth usa el usuario de WordPress que autoriza.

Los nombres de operación existentes, los URI de recursos, los prompts, las barreras de escritura y las cargas útiles exitosas específicas de cada herramienta siguen estando disponibles según los productos activos. El modo nativo ofrece además pom_get_site_context. Los clientes deben usar structuredContent cuando esté presente e inspeccionar isError antes de usar cualquier resultado. El modo nativo aplica los esquemas de entrada declarados a través de WordPress; envía booleanos JSON reales para dry_run.

Las actualizaciones desde el transporte estándar requieren que los clientes se reconecten, inicialicen una sesión y vuelvan a descubrir el catálogo. Las credenciales OAuth existentes conservan la misma identidad de recurso del sitio. Las integraciones con clave de API en WordPress 6.9+ deben configurar un Service user ID válido antes de reconectar. Los valores guardados del conmutador de transporte retirado no anulan la selección automática.

Límites de admisión

Ambos transportes aceptan un mensaje JSON-RPC por solicitud, de hasta 1 MiB. Los envíos de tareas y las lecturas de estado tienen cuotas por minuto separadas y pueden continuar mientras se ejecuta una tarea pesada. Las solicitudes públicas no ocupan el trabajador pesado compartido; la admisión en cola permanece limitada y la ejecución pesada permanece serializada. Un envío rechazado devuelve un error de cuota o de admisión en cola sin iniciar su operación. Comprueba los errores de la herramienta además del estado HTTP. Consulta MCP rate limiting para conocer los límites exactos y el comportamiento de reintento.

Contexto del sitio y catálogos de cuenta

El pom_get_site_context nativo incluye la identidad canónica site y un objeto connection con actor_user_id, client_id, scopes y auth_type. Estos describen la conexión autenticada actual; no se devuelve ninguna credencial. Un UUID identifica un sitio, pero no concede acceso.

Un servidor de cuenta expone herramientas de enrutamiento de cuenta en lugar de administración local del sitio. Selecciona un connection_id explícito de pom_account_list_sites, descubre el catálogo de ese destino con pom_account_discover_site y enruta las lecturas o la ejecución con pom_account_read_site o pom_account_execute_site. Comprueba el error externo de la herramienta y el remote_result.isError anidado, y luego los estados de cada paso. Los esquemas y permisos del destino siguen siendo autoritativos. Las llamadas también pueden devolver errores de puerta de enlace antes del envío. Una respuesta incierta no es motivo para repetir una escritura; inspecciona primero el estado de su destino.

Guías relacionadas: MCP connection, error contract y authentication.