En este artículo presento una guía práctica para llevar una API existente (por ejemplo, en .NET) al ecosistema MCP (Model Context Protocol) con un enfoque ordenado y seguro. Parto de tres piezas bien definidas: un catálogo estático (/.well-known/mcp.json), un gateway de ejecución y una herramienta de pruebas.

El objetivo es que un agente de IA solo descubra las capacidades que decido exponer y solo ejecute aquello que he validado, apoyándome en contratos explícitos y controles de seguridad verificables.

La diferencia entre un catálogo estático y uno dinámico puede entenderse con un ejemplo sencillo: imagina un libro de recetas. En un modelo estático, las recetas publicadas son fijas y revisadas; si quiero añadir una nueva o modificar una existente, edito el libro y lo vuelvo a publicar. En cambio, en un modelo dinámico, cualquiera podría añadir o alterar recetas en tiempo real: hoy la “tarta de manzana” lleva canela, mañana alguien la modifica y añade un ingrediente que resulta ser venenoso, y otro usuario la sigue cocinando sin saberlo.

En el enfoque estático —el que adopto en Secure MCP— sé exactamente qué “recetas” (endpoints) están disponibles y con qué “ingredientes” (parámetros) pueden usarse. Nada cambia de forma inesperada. Si quiero actualizar la carta, regenero el catálogo y lo despliego de nuevo, igual que sacaría una nueva edición revisada de mi libro de cocina.

Por qué MCP nace dinámico (y por qué eso importa)

MCP (Model Context Protocol) se diseñó originalmente para funcionar de forma dinámica.

El modelo de lenguaje puede preguntar al servidor MCP qué herramientas hay disponibles (listTools) y ejecutarlas (executeTool) en ese mismo momento.

No hay un catálogo fijo: el servidor puede añadir, eliminar o modificar herramientas en tiempo real según el contexto, la sesión o el entorno.

Esto ofrece flexibilidad, pero también introduce incertidumbre.

El “libro de recetas” aquí no es un libro encuadernado, sino un menú que cambia cada vez que el cliente lo consulta:

  • En un MCP dinámico, las recetas pueden variar con cada conexión.

  • Hoy existe una herramienta “GetUserBalance”, mañana desaparece o se modifica.

  • La IA no tiene garantías de que lo que aprendió o validó antes siga siendo válido.

  • Es como abrir un recetario que se reescribe en cada lectura.

  • En Secure MCP, ese menú se convierte en un libro publicado y firmado.

  • Las recetas (endpoints) son estables, auditadas y verificadas.

  • Si quiero añadir una nueva receta o cambiar un ingrediente, creo una nueva versión, la valido y la vuelvo a publicar.

  • Nadie puede colar “un ingrediente venenoso” sin pasar por ese proceso de control.

Este cambio de filosofía convierte MCP en una tecnología predecible, auditable y segura.

La IA sigue pudiendo consultar qué herramientas existen, pero el resultado no depende del momento, sino del catálogo estático que yo decido exponer.

De ese modo, paso de un modelo “descubre lo que hay ahora” a uno “usa lo que está aprobado”.

Generación estática del archivo .well-known/mcp.json desde una API REST

El primer paso para integrar una API con MCP es obtener un catálogo estático JSON que describa las operaciones que la IA puede invocar. A diferencia de exponer toda la API sin filtros, aquí solo muestro los endpoints que me interesa publicar. Este archivo se sirve en:

GET /.well-known/mcp

y contiene la descripción estática de todas las herramientas MCP.

Conversión de OpenAPI a MCP

Para generar el catálogo utilizo una herramienta CLI propia, McpGen, que lee la especificación OpenAPI/Swagger de la API y genera un JSON conforme al formato MCP.

Cada endpoint que quiero exponer se transforma en una herramienta MCP con:

  • name: identificador único (basado en el operationId o en el método HTTP y la ruta).

  • description: texto claro que explica qué hace el endpoint. Si la documentación OpenAPI no es suficiente, puedo generarla automáticamente.

  • inputSchema: esquema JSON que define los parámetros de entrada aceptados (query params, body, tipos, campos requeridos, etc.).

El resultado es un catálogo donde solo aparecen las rutas autorizadas y los parámetros que quiero exponer.

Por ejemplo, si en la API tengo ListCustomers o CreateOrder, aparecerán en el catálogo con sus descripciones y esquemas de entrada.

Cualquier endpoint interno o confidencial lo excluyo marcándolo con una extensión (x-mcp-private) o directamente no incluyéndolo.

Enriquecimiento con IA

Una de las partes más útiles de este proceso es poder apoyarme en GPT-4 u otros modelos de OpenAI para enriquecer automáticamente las descripciones.

El sistema analiza los comentarios y el código de la API y genera explicaciones de uso, ejemplos, notas de seguridad y errores típicos.

Así no tengo que redactar documentación a mano y la IA que consuma mi catálogo obtiene un contexto mucho más rico.

Publicación del catálogo MCP

Una vez generado, coloco el archivo en:

.well-known/mcp.json

y lo sirvo directamente desde la API o desde un hosting estático.

Lo importante es que el archivo sea accesible, ya que el modelo de IA (o MCP Inspector) lo utilizará para descubrir qué herramientas existen.

En el catálogo indico además que la lista de herramientas no cambia dinámicamente (listChanged: false), de modo que el modelo sabe que está trabajando sobre un conjunto estable de operaciones.

Si más adelante añado o elimino endpoints, actualizo la definición OpenAPI, regenero el .well-known/mcp.json y lo despliego de nuevo.

De esta forma, la IA solo puede invocar lo que he validado previamente.

Gateway de ejecución y wrapper de protocolo MCP

Tener un catálogo MCP está bien, pero hace falta una capa que controle las llamadas reales.

Aquí entra en juego el Execution Gateway, una pasarela que actúa como barrera de seguridad entre el agente de IA y la lógica de negocio.

La filosofía es la misma que la de un API Gateway tradicional, pero adaptada al contexto de MCP y como ejemplo que puedas tener en tu equipo local sin depender de una infraestructura más complicada:

  • Valido credenciales y autenticación (Zero Trust).

  • Verifico que los parámetros cumplen el esquema JSON definido (por ejemplo, que un dateStart sea una fecha válida).

  • Impongo límites y filtros (paginación, tamaño máximo de respuesta, saneamiento de salida).

  • Registro toda la actividad para trazabilidad y auditoría.

La IA nunca llama directamente a la API real: todas las invocaciones pasan por el Gateway.

Si algo no cumple las reglas —una herramienta no permitida, parámetros mal formados o llamadas fuera de rango— el Gateway rechaza la petición.

Esta capa adicional aporta seguridad, control y previsibilidad en entornos regulados o de producción.

McpStdioWrapper: la pieza que traduce JSON-RPC a HTTP

El McpStdioWrapper, incluido en el repositorio jmfloreszazo/static-secure-mcp, cumple una función clave: adaptar la comunicación estándar de MCP (basada en JSON-RPC 2.0 por stdio) a un entorno HTTP seguro manejado por el Gateway.

En la práctica, el flujo queda así:

MCP Inspector → (stdio) → McpStdioWrapper → (HTTP) → ExecutionGateway → API

¿Qué hace exactamente el Wrapper?

  1. Recibe mensajes JSON-RPC 2.0 enviados por el cliente MCP (por ejemplo, el Inspector):

{
  "jsonrpc": "2.0",
  "method": "executeTool",
  "params": { "tool": "ListCustomers", "arguments": {...} },
  "id": 1
}

Traduce esa llamada a una petición HTTP REST hacia el Gateway, por ejemplo:

POST /execute/ListCustomers
Content-Type: application/json

  1. Espera la respuesta del Gateway, la encapsula de nuevo en formato JSON-RPC 2.0 y la devuelve al cliente MCP.

De este modo, el Wrapper actúa como puente de protocolo: la IA habla MCP/JSON-RPC, el Gateway opera en HTTP.

Ambas capas están completamente desacopladas y cada una puede evolucionar sin romper compatibilidad.

Arquitectura de MCP: un protocolo, no un framework

Conviene aclararlo: MCP no es una arquitectura de aplicación como MVC o Clean Architecture, sino un protocolo de integración.

Su diseño se basa en el patrón clásico cliente-servidor con mensajería RPC estructurada, apoyándose en JSON-RPC 2.0 (2010) como capa de transporte.

En términos históricos, MCP es el descendiente directo de XML-RPC (1998) —que a su vez derivaba de las ideas de RPC (1976)—, pero modernizado y optimizado para agentes de IA.
Por tanto:

MCP no dicta cómo organizar tu código, sino cómo comunicar capacidades entre sistemas.

En una conferencia escuché a un ponente decir que “la arquitectura de MCP es MVC”.

Me mordí la lengua. MCP no tiene vistas ni controladores; es un protocolo declarativo que define cómo un modelo de lenguaje puede descubrir y ejecutar funciones remotas con contratos JSON bien definidos.

Con esto os quiero decir algo importante: sed escépticos con lo que oigáis, incluso si suena convincente.

Probad las cosas, revisad las especificaciones y experimentad por vosotros mismos.

Podéis hacerlo con el proyecto que he publicado en GitHub, donde el servidor MCP es completamente funcional, seguro y reproducible.

MCP Inspector: pruebas y validación

Para validar y depurar el servidor MCP utilizo MCP Inspector, la herramienta oficial que permite:

  • Visualizar la lista de herramientas publicadas y sus descripciones.

  • Ejecutar cada herramienta con parámetros personalizados y ver la respuesta en tiempo real.

  • Validar que los esquemas de entrada coinciden con lo que la API espera.

  • Depurar fácilmente combinando los logs del Gateway con la salida del Inspector.

En local, arranco todo con un script simple:

./demo-test.sh

que lanza la API, el Gateway y el MCP Inspector, normalmente accesible en http://localhost:6274.

También puedo probar directamente con curl, invocando POST /execute/... sobre el Gateway para comprobar los resultados sin necesidad del Inspector.

Reflexión final

Exponer una API a modelos de lenguaje no requiere reinventar nada, solo aplicar buenas prácticas y sentido común:

  • Reutilizo OpenAPI como fuente de verdad.

  • Genero un catálogo MCP estático claro (/.well-known/mcp.json).

  • Añado un Execution Gateway que refuerza seguridad, validación y auditoría.

  • Usamos el protocolo adecuado de comunicación.

  • Verifico todo el flujo con MCP Inspector antes de llevarlo a producción.

Este enfoque —al que he llamado Static Secure MCP— es pionero en el ecosistema de transformación y modernización.

No es una idea teórica: funciona de extremo a extremo y puede aplicarse directamente en entornos reales.

Hasta donde sé, no existe ninguna PoC funcional en .NET que implemente MCP con este nivel de integración; esta solución es plenamente operativa y pensada para producción.

He incluido tanto el wrapper como el gateway para mostrar cómo encajan las piezas en código, de forma que se puedan entender, probar y extender fácilmente.

Si ya usas un API Gateway corporativo (Azure API Management, Apigee, Kong, etc.), puedes añadir tus propias políticas de seguridad o cumplimiento encima.

En esta demo he mantenido todo sin autenticación por simplicidad, pero endurecerlo en producción es inmediato con JWT, OIDC, rate limits o roles.

Una breve mirada divulgativa: de XML a MCP (y por qué la seguridad importa)

Nada de esto es nuevo.

La idea de describir las capacidades de un sistema mediante contratos viene de muy atrás.

En los años 60, IBM desarrolló el GML (Generalized Markup Language), creado por Charles Goldfarb, Edward Mosher y Raymond Lorie —de ahí las siglas G-M-L.

Era un lenguaje de marcado pensado para estructurar documentos técnicos, y acabó convirtiéndose en la base del SGML (Standard Generalized Markup Language), que la ISO estandarizó en 1986.

En 1998, el W3C publicó XML (eXtensible Markup Language), heredero directo de SGML pero mucho más simple.

XML fue el que realmente explotó a principios de los 2000, cuando tecnologías como SOAP y WSDL lo convirtieron en el lenguaje común de los servicios web.

Aquella época fue el primer gran intento de estandarizar cómo una aplicación podía descubrir y consumir otra sin importar el lenguaje o la plataforma.

SOAP transportaba mensajes XML sobre HTTP, y WSDL definía las operaciones, parámetros y tipos de datos: exactamente el mismo patrón que hoy seguimos con OpenAPI y MCP.

La diferencia es que hoy el interlocutor no es otro sistema corporativo, sino una IA.

El principio, sin embargo, sigue siendo el mismo: contratos declarativos que definen qué se puede hacer, cómo se hace y con qué datos.

ActiveX: el espejo incómodo del pasado

En los años 90, Microsoft ActiveX prometía algo similar a lo que ahora persigue MCP: permitir que aplicaciones externas —e incluso páginas web— invocaran funcionalidades locales de forma directa y dinámica.

La idea era brillante sobre el papel: dotar al navegador de capacidades nativas sin limitaciones.

Pero el resultado fue un desastre en seguridad.

ActiveX carecía de aislamiento, de control de permisos granular y de un modelo de confianza real.

Cualquier control malicioso podía ejecutarse con permisos de sistema, y el ecosistema terminó siendo inseguro por diseño.

La industria aprendió una lección dolorosa: no basta con exponer capacidades, hay que contenerlas.

De ahí mi mirada crítica hacia MCP

Por eso observo MCP con respeto, pero también con cautela.

El protocolo hereda buenas ideas de interoperabilidad —como las que impulsaron SOAP, WSDL o XML—, pero también revive un riesgo que creíamos superado: la ejecución remota sin un perímetro de seguridad sólido.

MCP nace dinámico, abierto y flexible, lo cual es fantástico para experimentar, pero insuficiente para entornos reales, regulados o de misión crítica, donde cada llamada de un modelo de lenguaje puede tener consecuencias operativas o legales.

Ahí es donde entra mi propuesta, Secure MCP.

Lo que planteo —catálogo estático, gateway de ejecución y wrapper controlado— no reinventa MCP: lo corrige en lo que más lo necesitaba.

Le añade un marco de Zero Trust, validación, trazabilidad y control de cambios.

Porque la innovación no consiste en abrir todas las puertas, sino en saber cuáles deben permanecer cerradas.

Desde mi punto de vista, esa es la pieza que faltaba para que MCP pueda desplegarse de verdad en entornos productivos, seguros y auditables.

El protocolo no era el problema; lo que faltaba era una arquitectura responsable para usarlo con cabeza.

Ese es precisamente el propósito de este artículo y el enfoque que desarrollo en detalle en mi publicación: “Secure MCP: un patrón para entornos reales y regulados”