Despliega un servidor MCP remoto en Cloudflare Workers con McpAgent y OAuth, reduce el contexto de herramientas con el patrón de búsqueda y ejecución de Code Mode y, después, agrupa tus servidores detrás de un MCP Server Portal con políticas de Zero Trust Access, filtrado de herramientas y registros de acceso.
Tu servidor de Model Context Protocol (MCP) funciona bien en tu equipo portátil. Luego un compañero te pide la URL, un segundo editor la necesita en otra máquina y alguien de seguridad pregunta quién puede llamar a cada herramienta. Un proceso local no puede responder nada de eso. Cloudflare te ofrece tres piezas para este momento: Workers para alojar el servidor, Code Mode para reducir lo que el modelo tiene que leer y MCP Server Portals para poner todos los servidores tras una única puerta controlada. A continuación encontrarás cada pieza en orden, con los comandos, la configuración y las trampas que importan, para que pases de una carpeta vacía a una configuración gobernada sin adivinar.
Un servidor stdio es un proceso hijo de un cliente en una sola máquina. Eso funciona para un proyecto de fin de semana. Deja de funcionar en cuanto aparece una segunda persona: cada uno instala su copia, los secretos quedan en archivos de configuración locales y nadie puede ver qué herramientas se llaman. Un servidor remoto resuelve todos esos problemas. Tienes una URL, un despliegue y un único lugar donde leer los registros.
Lo local sigue ganando en un caso: una herramienta que toca archivos de la máquina de una sola persona, como una carpeta privada de notas. El alojamiento remoto es para herramientas que comparten varias personas o varios agentes.
Los Workers ejecutan tu código en la red edge de Cloudflare, cerca de quien hace la llamada. En concreto para MCP, Cloudflare ofrece tres bloques de construcción:
McpAgent, una clase del Agents SDK que gestiona el transporte remoto. El SDK sirve Streamable HTTP por ti.workers-oauth-provider, una biblioteca proveedora de OAuth 2.1 que envuelve tu Worker y añade autorización a sus endpoints, incluidos los de MCP.mcp-remote, un adaptador que permite conectar a un servidor remoto a los clientes que solo hablan stdio.| Necesidad | Servidor stdio local | Servidor remoto en Workers |
|---|---|---|
| Quién puede usarlo | Una máquina | Cualquiera con la URL y un inicio de sesión |
| Actualización | Reinstalar en cada máquina | Un wrangler deploy |
| Secretos | Archivos de configuración locales | Secretos de Worker |
| Estado por sesión | Memoria del proceso | Durable Objects |
| Visibilidad | Ninguna integrada | Registros de acceso del portal |
💡 Recuerda: remoto no significa público. Trata la URL como una API expuesta a internet desde el primer despliegue.
Cloudflare mantiene una plantilla para un servidor sin inicio de sesión, que es la forma más rápida de ver las piezas en movimiento:
npm create cloudflare@latest -- my-mcp-server --template=cloudflare/ai/demos/remote-mcp-authless
cd my-mcp-server
npm start
Tu servidor ya escucha en local en http://localhost:8788/mcp. No hay nada más que instalar.
El núcleo del proyecto es una clase que extiende McpAgent. Registras las herramientas dentro de init(), igual que harías con el SDK oficial de TypeScript:
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
export class MyMCP extends McpAgent {
server = new McpServer({ name: "math", version: "1.0.0" });
async init() {
this.server.tool("add", { a: z.number(), b: z.number() }, async ({ a, b }) => ({
content: [{ type: "text", text: String(a + b) }],
}));
}
}
export default MyMCP.serve("/mcp");
Esa clase también es un Durable Object, por eso la configuración del proyecto declara un binding y una migración para ella. Los Durable Objects dan a cada sesión MCP su propio estado sin que tú necesites una base de datos. Si tus herramientas solo devuelven resultados puros, nunca tocarás ese estado. En cuanto hagas seguimiento de un carrito, un borrador o una conversación larga, te alegrará que exista.
Ejecuta el MCP Inspector en una segunda terminal y apúntalo a la URL local:
npx @modelcontextprotocol/inspector@latest
Llama a tu herramienta desde su interfaz web. Cuando se comporte bien, despliega:
npx wrangler@latest deploy
Tu servidor queda entonces activo en https://my-mcp-server.<your-account>.workers.dev/mcp. Los clientes que solo hablan stdio, como Claude Desktop, se conectan a través del adaptador:
{
"mcpServers": {
"math": {
"command": "npx",
"args": ["mcp-remote", "https://my-mcp-server.<your-account>.workers.dev/mcp"]
}
}
}
También puedes pegar la URL en el Cloudflare AI Playground o en el Inspector para probar la versión desplegada.
Un servidor sin autenticación sirve para una demo y es mala idea para cualquier cosa que toque datos reales. La segunda plantilla de Cloudflare conecta GitHub como proveedor de identidad:
npm create cloudflare@latest -- my-mcp-server-github-auth --template=cloudflare/ai/demos/remote-mcp-github-oauth
La configuración es una lista corta de pasos:
npx wrangler secret put GITHUB_CLIENT_ID y npx wrangler secret put GITHUB_CLIENT_SECRET, además del secreto de cifrado de cookies que indica el README de la plantilla.npx wrangler kv namespace create "OAUTH_KV".wrangler.jsonc y despliega.Internamente, workers-oauth-provider envuelve tu Worker, así que tus herramientas reciben los datos del usuario ya autenticados como parámetro. No escribes a mano las comprobaciones de token, y ese es precisamente el objetivo.
💡 Consejo: GitHub es solo una opción. La misma biblioteca de proveedor puede colocarse delante de cualquier proveedor de identidad OAuth, lo que importa cuando quieras poner el servidor tras un portal.
Cada definición de herramienta que expones es texto que el modelo debe leer antes de hacer algo útil. Con diez herramientas eso se gestiona. Con una plataforma entera, se desborda. Cloudflare indica que exponer su API de más de 2.500 endpoints como herramientas MCP normales costaría más de 1,17 millones de tokens. Con Code Mode, ese mismo alcance cabe en unos 1.000 tokens.
Hay un segundo costo que recibe menos atención. En un bucle normal de llamadas a herramientas, cada resultado intermedio vuelve a pasar por el modelo. Si el paso dos necesita la salida del paso uno, el modelo la lee, la reformula y la envía de nuevo. Code Mode permite que el modelo escriba un programa corto en su lugar. Las llamadas dependientes se ejecutan dentro del sandbox, los datos intermedios permanecen allí y solo la respuesta final regresa a la conversación. Menos viajes de ida y vuelta significan menos texto que leer y menos oportunidades de copiar mal un valor.
El patrón para APIs grandes, openApiMcpServer(), expone solo dos herramientas:
search ejecuta código escrito por el modelo contra un documento OpenAPI dentro de un sandbox y devuelve solo las operaciones, parámetros o esquemas que necesita la tarea.execute ejecuta código escrito por el modelo con una función de solicitud autenticada que proporciona tu Worker.Como dice la documentación, solo el subconjunto devuelto entra en el contexto del modelo. El modelo hace una pregunta concreta, recibe una respuesta concreta y después actúa.
Imagina una petición como lista los registros DNS de mi zona. El modelo primero escribe un fragmento pequeño para search que filtra las rutas de OpenAPI hasta las operaciones DNS y devuelve unas pocas coincidencias en lugar de miles. Después escribe un fragmento para execute que llama a la operación correcta mediante tu función de solicitud y devuelve solo los campos que necesita. Dos viajes cortos sustituyen a una lista de herramientas del tamaño de una guía telefónica.
Para construir uno, necesitas un proyecto de Workers, un documento OpenAPI 3.x y un método del lado del host para autenticar las solicitudes.
El código escrito por el modelo se ejecuta en un Worker aislado, y el acceso directo de salida a la red está bloqueado por defecto. El código generado solo puede llegar al exterior a través de herramientas MCP upstream o de la función de solicitud (callback) que proporcionas. Es un valor predeterminado sólido, pero no hace la autorización por ti:
codeMcpServer() | openApiMcpServer() | |
|---|---|---|
| Ideal para | Envolver un servidor MCP existente con un conjunto manejable de herramientas | Catálogos de APIs grandes |
| Lo que ve el modelo | Una herramienta code con definiciones TypeScript de cada operación upstream | Dos herramientas: search y execute |
| Cómo se hacen las llamadas | A través de un namespace codemode, así las llamadas dependientes se componen dentro del sandbox | Operaciones seleccionadas llamadas mediante una función de solicitud que proporciona el host |
| Costo de contexto | Crece con el número de herramientas upstream | Acotado, porque solo vuelven los resultados de search |
💡 Regla general: envuelve lo que ya tienes con
codeMcpServer(). UsaopenApiMcpServer()cuando tu lista de herramientas sería un catálogo y no una caja de herramientas.
Los MCP Server Portals se lanzaron en beta abierta en agosto de 2025 como parte de Cloudflare One. La idea es simple: enrutar cada solicitud MCP a través de un único endpoint de portal, aplicar allí políticas de Zero Trust y registrarlo todo.
Antes de abrir el panel, confirma tres cosas:
https://<subdomain>.<domain>/mcp.Un servidor solo aparece en el portal para las personas que cumplen una política Allow. Las etiquetas del menú pueden cambiar mientras una función está en beta, así que fíate del panel actual más que de cualquier captura de pantalla.
En la configuración del portal puedes desactivar el interruptor junto a cualquier herramienta o prompt que quieras ocultar. Cada servidor muestra un recuento de Tools authorized para que veas cuánto has expuesto. Algunos controles que conviene conocer:
{server_id}_{tool_name}, así dos servidores pueden tener cada uno una herramienta search sin colisionar.Los registros del portal guardan la hora, el estado, el nombre del servidor, la capacidad y la duración, por portal o por servidor. Pueden exportarse con Logpush a almacenamiento de terceros o a un SIEM. Para un despliegue en equipo, aquí es donde respondes la pregunta que planteó seguridad en el primer párrafo: quién llamó a qué y cuándo.
Un orden de despliegue que mantiene las sorpresas al mínimo:
/mcp en vivo antes de añadirlo a un portal.💡 Prueba rápida: abre el portal como un usuario que no está en tu política Allow. Si ves algún servidor, tu política está mal.
Cualquier cliente que llame a tu servidor necesita un modelo capaz que lo respalde. Estos modelos de lenguaje de PicassoIA merecen una prueba con tus herramientas:
| Modelo | Fortaleza indicada |
|---|---|
| Claude Sonnet 5 | Automatizar tareas de programación |
| GPT 5.6 Sol | Resolver tareas de programación complejas |
| Kimi K2.6 | Crear agentes de IA y escribir código |
| Gemini 3.5 Flash | Chat rápido, código e imágenes |
También son útiles antes de desplegar nada: pídele a uno que redacte descripciones de herramientas, que escriba el TypeScript que darías a Code Mode o que revise tu documento OpenAPI en busca de operaciones que prefieras no exponer.
Un Worker puede llamar a cualquier API HTTP, así que una herramienta MCP puede llamar a la de PicassoIA. La API de PicassoIA está en https://api.picassoia.com/v1, acepta un token bearer que empieza por pia_sk_ y sigue un patrón al estilo de Replicate: POST /v1/models/{owner}/{name}/predictions crea una tarea y GET /v1/predictions/{id} lee su estado. Las tareas son asíncronas, y una cuenta ejecuta hasta 5 predicciones a la vez.
Esa forma encaja de manera natural en dos herramientas: una que inicia una generación y devuelve un id, y otra que consulta el resultado. Guarda el token con npx wrangler secret put PICASSOIA_API_TOKEN y nunca lo imprimas en un resultado de herramienta. Si prefieres no construir nada, PicassoIA también ofrece su propia conexión MCP, que da a tu cliente directamente los mismos modelos de imagen y video.
Ya tienes el camino completo: un Worker que sirve MCP, OAuth delante, Code Mode para mantener el contexto pequeño y un portal para gobernarlo todo. La recompensa más rápida es hacer que el servidor genere algo visual.
Abre Seedream 5 Pro, GPT Image 2 o FLUX 2 Pro y escribe un prompt para la foto que hubieras querido tener en tu último proyecto. Después llévalo más lejos con Seedance 2.0 o Veo 3.1 Fast y convierte la imagen fija en movimiento. Experimenta con la iluminación, el objetivo y el ángulo hasta que el resultado parezca una sesión real.
Todos los modelos están en picassoia.com/en/all-models. Elige uno, ejecuta un prompt y mira lo que sale.
Elige tu idioma
