Migrar una API de WordPress existente a MCP: un plan de 4 semanas
Construir un servidor MCP desde cero es sencillo. Migrar desde una REST API de WordPress existente y en funcionamiento, mientras sigue atendiendo tráfico de producción, es una forma más difícil. Este plan es el que uso para pasar de “tenemos /wp-json/ y un consumidor socio” a “tenemos /wp-json/, ese socio y un servidor MCP pensado para LLM delante”, sin romper nada.
El artículo forma parte del pilar desarrollo de servidores MCP.
TL;DR
- Cuatro semanas: auditoría, estructura, ejecución en paralelo, cambio.
- REST sigue activa para los consumidores existentes; MCP es un añadido, no un sustituto.
- Los esquemas Zod salen de la auditoría de REST, no de una lista de deseos.
- Ejecución en paralelo con un agente interno antes de que el tráfico externo llegue a MCP.
- Logpush captura cada llamada a herramienta; las discrepancias entre las respuestas de MCP y de REST aparecen como errores de esquema.
Cómo auditar los endpoints de la REST API de WordPress
La auditoría es una hoja de cálculo. Una fila por endpoint, con estas columnas:
| Columna | Qué anotamos |
|---|---|
| Endpoint | /wp-json/wp/v2/posts, /wp-json/wc/v3/products, etc. |
| Verbos HTTP | GET, POST, PUT, DELETE admitidos |
| Consumidores actuales | Tienda, ERP del socio, receptores de webhooks |
| Volumen de tráfico | Peticiones al día según los registros de acceso |
| Sensibilidad de los datos | Públicos, de clientes, solo administración |
| ¿Modifica el estado? | Sí/no |
| ¿Corresponde a una herramienta MCP? | Nombre propuesto de la herramienta e intención |
| Notas | Plugins implicados, formas de campos personalizados, trampas |
En una tienda WooCommerce típica la hoja tiene de 20 a 60 filas. La mayoría se corresponde limpiamente con herramientas MCP; unas pocas (internas de administración, endpoints específicos de plugins, receptores de webhooks) se quedan solo en REST.
El resultado de la semana 1 son dos artefactos:
- Un inventario de herramientas propuesto:
catalogue.list,product.detail,order.intent,order.status,inventory.check, más lo que sea específico de tu desarrollo. - Un primer borrador de los esquemas Zod para las entradas y salidas de cada herramienta, derivado de las respuestas REST reales capturadas durante la auditoría.
Capturo las respuestas REST con curl y jq para inspeccionar la forma, o con una colección de Postman que comparte el equipo. Se trata de la verdad empírica, no de lo que dice el README. Los plugins de WordPress tienen fama de añadir campos que la documentación nunca recoge; la auditoría los detecta.
Cómo montar un servidor MCP en Cloudflare Workers
El resultado de la semana 2 es un servidor MCP que funciona, desplegado en un entorno de Cloudflare Workers que no es de producción, con el inventario de herramientas de la semana 1 implementado como adaptadores delgados sobre los endpoints REST existentes.
El esqueleto del servidor:
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { catalogueListInput, catalogueListOutput, handleCatalogueList } from "./tools/catalogue-list.js";
import { productDetailInput, productDetailOutput, handleProductDetail } from "./tools/product-detail.js";
// ... jeden import na narzędzie
export function createMcpServer(env: Env): Server {
const server = new Server({
name: "wppoland-mcp",
version: "0.1.0",
});
server.tool(
"catalogue.list",
catalogueListInput,
catalogueListOutput,
(input) => handleCatalogueList(input, env),
);
server.tool(
"product.detail",
productDetailInput,
productDetailOutput,
(input) => handleProductDetail(input, env),
);
// ... jedno wywołanie .tool() na narzędzie
return server;
}Cada handler es un adaptador delgado. Recibe la entrada validada, construye la query string, hace fetch a /wp-json/, mapea la respuesta a una forma de salida alineada con schema.org, llama a parse sobre la salida y la devuelve. La lógica de negocio se queda en WordPress; el handler es una traducción mecánica.
La semana 2 incluye también la estructura de autenticación de la guía de patrones de autenticación MCP. Para la ejecución en paralelo de la semana 3 uso un único token de prueba con todos los scopes; los scopes de producción los ajusto en la semana 4.
El wrangler.toml del entorno de preview apunta a una instalación de staging de WordPress o a una copia de producción. El servidor MCP es accesible en una URL *.mcp-staging.wppoland.workers.dev disponible solo para el equipo.
Cómo probar el servidor MCP en paralelo con la REST API
En la semana 3 salen los bugs. El patrón:
Construye un arnés de comparación. Un pequeño script de TypeScript que recibe el nombre de una herramienta y una entrada, llama al servidor MCP, después llama directamente al endpoint REST equivalente y compara las dos respuestas. La diferencia se registra junto con el nombre de la herramienta, la entrada y una ruta al estilo JSON pointer hacia cada discrepancia.
async function compareToolToRest(toolName: string, input: unknown) {
const mcpResponse = await callMcp(toolName, input);
const restResponse = await callEquivalentRest(toolName, input);
const diff = jsonDiff(restResponse, mcpResponse);
if (diff.length > 0) {
await logMismatch({ toolName, input, diff });
}
}Cada herramienta contra un conjunto representativo de entradas. Para catalogue.list: query vacía, query que devuelve cientos de productos, query con filtro de categoría, query con rango de precios, query sin resultados. Para product.detail: SKU conocido, SKU desconocido, SKU con variaciones, SKU con campos personalizados. Cubre los casos límite de la auditoría.
Apunta un agente interno al servidor MCP. Claude Desktop con el servidor MCP configurado como fuente remota de herramientas es la configuración que uso. Alguien del equipo dedica 30 minutos al día durante una semana a interactuar con su propia tienda a través del agente y anota las sorpresas en un documento compartido.
Ajusta los esquemas según lo que vuelve. Cada fallo de validación de Zod en el registro es un bug de esquema o un bug de mapeo. Corrígelo, vuelve a desplegar el Worker de preview y repite el arnés.
El resultado de la semana 3 es un arnés que pasa con cero diferencias y un inventario de herramientas que ha sobrevivido a cinco días de 30 minutos diarios de interacción real con el agente. Si falta cualquiera de los dos, la semana 4 no empieza.
Cómo desplegar el servidor MCP en producción y monitorizarlo
El cambio no tiene drama si las semanas 1 a 3 han ido bien.
Despliega los Workers de producción. wrangler deploy --env production. El servidor MCP de producción apunta al origen WordPress de producción, con scopes de producción en los tokens que emite la administración de WordPress.
Emite tokens para el primer runtime real de agente. Normalmente uno de estos: un agente interno para empleados, una integración de un socio que pide una superficie MCP, un asistente público en la tienda. Empieza por el consumidor más pequeño y de menor riesgo.
Conecta Cloudflare Logpush a un almacenamiento a largo plazo. Los campos de registro descritos en el artículo sobre cómo construir un servidor MCP para WooCommerce son los valores por defecto adecuados: nombre de la herramienta, hash de la entrada, latencia, resultado de la validación, scope del token. El almacenamiento es el que tu equipo ya usa (BigQuery, ClickHouse, S3 + Athena).
Construye un panel de observación. Tres consultas desde el primer día:
- Llamadas a herramientas por minuto, desglosadas por nombre de herramienta. Detecta picos de carga.
- Tasa de fallos de validación por herramienta, desglosada por código (
input_invalid,output_invalid). Detecta regresiones. - Latencia p50/p95/p99 por herramienta. Detecta un WordPress lento más arriba en la cadena.
Mantén REST viva e intacta. La tienda existente, las integraciones de socios existentes y los receptores de webhooks existentes siguen usando /wp-json/ exactamente igual que antes. MCP es un añadido, no un sustituto. Es la regla más importante de la migración.
Los errores más comunes al migrar la REST API a MCP
Seis cosas que he visto fallar en migraciones reales:
Un campo de la respuesta REST que la auditoría no detectó. Un plugin añade meta_data: [...] a las respuestas de productos. El esquema de salida de MCP no lo conoce. El parse de Zod falla con datos reales. Solución: repite la auditoría sobre tráfico de producción, amplía el esquema o descarta el campo de forma explícita con .transform().
Permalinks distintos entre staging y producción. La herramienta MCP product.detail devuelve el campo permalink de WooCommerce. Los permalinks de staging son https://staging.example.com/...; los de producción, https://example.com/.... Los datos de prueba pasan; producción falla en el validador de URL. Solución: configura el Worker de staging con un paso de reescritura de permalinks que replique el comportamiento de producción.
Gestión de variaciones de WooCommerce. La auditoría capturó la forma de la respuesta de un producto simple. Las respuestas de las variaciones son distintas (los SKU de las variaciones están en /wp-json/wc/v3/products/<id>/variations). Solución: trata las variaciones como un fetch independiente en product.detail y mapéalas a hasVariant de schema.org.
El token de autenticación se filtra a los registros. Un handler registra la cabecera Authorization completa para depurar. El token acaba en el almacenamiento de registros. Solución: oculta la cabecera en la capa de registro; rota todos los tokens emitidos antes de que la ocultación estuviera activa. Relevante para el cumplimiento del artículo 32 del RGPD.
La actualización de un plugin rompe la respuesta REST. WooCommerce 9.x cambia el nombre de un campo, el handler de MCP sigue esperando el nombre antiguo y el parse de Zod falla. Solución: fija la versión de WooCommerce en staging, ejecuta el arnés de comparación en cada actualización de WordPress y trata el arnés como parte de la barrera de actualización.
El agente entra en bucle con una llamada a herramienta mal formada. Un agente defectuoso reintenta order.intent 100 veces por minuto cuando la entrada no supera la validación. Sin rate limit, el origen WordPress recibe 100 llamadas en cascada. Solución: rate limit por principal, como en la guía de patrones de autenticación MCP, y devuelve retry_after_seconds en el sobre de error.
Cuánto tarda migrar la API de WordPress a MCP
Cuatro semanas es la opción por defecto. Dos ajustes:
Superficie más pequeña, dos semanas. Tres herramientas, un consumidor, sin complejidad de autenticación. Comprime la auditoría y la estructura en la semana 1, y la ejecución en paralelo y el cambio en la semana 2. El mismo patrón, un calendario más corto.
Superficie más grande, seis semanas. Una docena de herramientas, varios modos de autenticación, acciones sensibles que modifican datos. Añade una semana entre la estructura y la ejecución en paralelo para una revisión de seguridad. Añade otra entre la ejecución en paralelo y el cambio para un lanzamiento suave con un único usuario autorizado por OAuth antes de un despliegue más amplio.
Las cuatro fases mantienen el mismo orden sea cual sea el presupuesto de tiempo.
¿Cambia WordPress después de adoptar MCP?
Dicho sin rodeos, después de la migración:
- La interfaz de administración de WordPress no cambia.
- El Block Editor no cambia.
- El sistema de autenticación de usuarios no cambia.
- Los endpoints REST existentes no cambian y siguen atendiendo a sus consumidores.
- La lógica que dispara los webhooks no cambia.
- La capa de datos (
wp_posts,wp_postmeta, tablas de WooCommerce) no cambia.
Lo que se añade: el servidor MCP en Cloudflare Workers, una interfaz para emitir tokens en la administración de WordPress (un pequeño plugin o una función del tema) y la configuración de Cloudflare Logpush. Todo lo demás sigue igual.
Eso es justo lo que hace que la migración tenga poco riesgo. Si el servidor MCP tiene un mal día, apagas el Worker. La superficie para agentes desaparece. La tienda sigue funcionando, las integraciones de socios siguen funcionando y los pedidos siguen entrando.
Temas relacionados
Este artículo trata la forma de la migración. La implementación se describe en el artículo sobre cómo construir un servidor MCP para WooCommerce. La estrategia de autenticación se trata en la guía de patrones de autenticación MCP. El diseño de herramientas tipadas se trata en el artículo sobre herramientas de catálogo tipadas con Zod para MCP. La decisión a nivel de protocolo se trata en la comparación entre MCP y REST. La página del servicio es desarrollo de servidores MCP.
El presupuesto es individual, porque el alcance de la migración depende del número de endpoints de la auditoría, de la complejidad de la autenticación y del número de consumidores.
En la parte de implementación, este tema encaja en la migración a Next.js o Astro.
