Tools MCP como API Contracts: documenta lo que tus agentes pueden hacer
Hace unos meses lanzamos los API Contracts: especificaciones OpenAPI, gRPC, GraphQL y AsyncAPI, enlazadas directamente a los elementos C4 que las implementan y las consumen. La idea era simple — la descripción precisa y legible por máquina de una interfaz pertenece dentro de tu arquitectura, no en una página de Notion que nadie actualiza.
Quedaba una interfaz que no habíamos cubierto. La más nueva. La que tus servicios exponen cada vez más, no a otros servicios, sino a los agentes de IA: MCP.
Un servidor MCP publica un conjunto de tools — cada uno con un nombre, una descripción y un JSON Schema para sus entradas. Eso es un contrato. Es el contrato que decide lo que un agente tiene permitido hacer con tu sistema. Y hasta hoy, era completamente invisible en tu documentación de arquitectura.
Ya no. MCP es ahora un tipo de API Contract de primera clase en Archyl — el quinto, junto a HTTP, gRPC, GraphQL y AsyncAPI.
Lo difícil: los tools MCP no viven en un archivo
Los otros cuatro tipos de contrato comparten una suposición — hay un archivo de spec en un repo. openapi.yaml. schema.graphql. Apuntas Archyl a él y lo renderizamos.
MCP rompe eso. Los tools de un servidor MCP se definen en el código, y la lista completa y autoritativa solo existe en tiempo de ejecución, cuando un cliente llama a tools/list y recibe el schema de cada tool. No hay un mcp.yaml universal al que apuntar.
Así que construimos dos vías de entrada.
Dos formas de añadir un contrato MCP
Pégalo. Si ya tienes tu salida de tools/list, pégala. Archyl la valida y renderiza cada tool — su descripción y sus parámetros de entrada en una tabla legible.
O simplemente danos la URL. Dile a Archyl dónde está tu servidor MCP, añade opcionalmente un token de acceso (como header o como parámetro de URL), y haz clic en Descubrir tools. Archyl se conecta, ejecuta el handshake y trae automáticamente cada tool y parámetro. Sin copiar y pegar, sin un archivo mantenido a mano.
Cómo funciona el descubrimiento en vivo — y por qué es seguro
El descubrimiento ocurre en tu navegador, no en nuestros servidores. Cuando haces clic en Descubrir tools, tu navegador habla directamente con tu servidor MCP.
Esa elección importa:
- Tu token nunca sale de tu navegador. Archyl guarda los tools descubiertos y los detalles de conexión — la URL, el transporte, dónde va el token — pero nunca el token en sí.
- Ningún acceso desde el servidor a tu red. Como la llamada se origina en tu máquina, no hay forma de apuntarla a los servicios internos de otra persona. Toda la categoría de riesgos de tipo SSRF simplemente no existe aquí.
- Llega a localhost y a servidores privados. ¿Pruebas un servidor que corre en tu portátil o dentro de tu red? Funciona, porque tu navegador puede verlo.
La única contrapartida es CORS: un servidor de terceros tiene que permitir el origen de Archyl para que tu navegador pueda leer la respuesta. Para servidores que controlas es una línea de configuración; para el resto, la opción de pegar siempre está ahí.
Enlazado a tu arquitectura, como cualquier otro contrato
Una vez dentro, un contrato MCP se comporta como cualquier otro. Enlázalo al container o componente que aloja el servidor. Explora cada tool y su schema de entrada. Vuelve a descubrirlo cuando el servidor cambie. Aparece junto a tus contratos REST y GraphQL, porque para los agentes que lo llaman es una API igual de real.
Esto convierte tu contrato MCP en algo genuinamente nuevo: un mapa de lo que tus agentes de IA tienen permitido hacer a una parte concreta de tu sistema — documentado, enlazado y revisable.
Lo usamos en nosotros mismos
Archyl es en sí mismo un servidor MCP — 178 tools que te permiten gobernar tu arquitectura desde Claude Code, Cursor o cualquier cliente MCP. El primer contrato MCP que creamos fue el nuestro: apuntar Archyl a su propio endpoint, descubrir los 178 tools, enlazarlo a la plataforma. Nuestra superficie de agente ahora se documenta a sí misma.
Pruébalo
Abre un proyecto, ve a API Contracts, crea uno nuevo y elige MCP. Pega tu tools/list, o introduce una URL y pulsa Descubrir tools.
Tus servicios ya hablan con los agentes. Ahora tu arquitectura sabe qué se dicen.