MCP-readiness by default: every new service ships with a tool surface

Cuando un servicio se considera "terminado" en mi stack tiene cuatro cosas: tests, observabilidad, deploy automatizado y un MCP server. Las primeras tres no se discuten. La cuarta sigue sorprendiendo. Lo separo.

La premisa: un servicio no-agent-readable no está terminado

Si tu servicio solo se consume por humanos con Postman, asumiste que el cliente más demandante de tu API es una persona. Esa asunción dejó de ser cierta hace al menos un año. Hoy, en la mayoría de stacks donde trabajo, el integrador más exigente no abre Postman — es un agente leyendo el catálogo de tools al inicio de una sesión.

El agente no improvisa contra una doc Confluence ni interpreta tu README. Si la superficie no está descrita en un formato que pueda consumir, simplemente no la usa. O peor: la usa mal, porque infiere semántica desde el nombre del endpoint y se inventa el resto.

Lo planteo en la lente Meta-Software que vengo masticando: si el agente no puede leer tu superficie, vos vas a ser la traducción. Cada vez que alguien quiera integrar ese servicio en un flujo agentic, va a tener que sentarse con vos a explicar. Eso no escala — y más importante, te convierte en cuello de botella de capacidades que el resto del equipo necesita ejecutar sin pedirte permiso.

Qué exige "MCP-readiness" como default

No es una bandera de marketing. Es un set chico de obligaciones concretas. Primero: un sub-proyecto mcp-server dentro del repo del servicio. No en otro repo, no en el backlog, no "cuando tengamos tiempo". Mismo CI, misma versión, mismo dueño. Si vive afuera, drift garantizado.

Segundo: tools nombrados con verbo y objeto. list_invoices, issue_dte, reconcile_batch. No invoiceController.findAll. El agente planea desde el nombre — si el nombre miente, el plan miente. CRUD genérico es un anti-patrón en este contexto, porque oculta intención.

Tercero: cada tool con su flag destructive declarado explícitamente (lo desarrollé en otro post — es el ADR 0006). El agente decide diferente cuando ve que una llamada borra estado que cuando ve que solo lee. Si no se lo decís en el schema, lo va a aprender por accidente.

Cuarto: schemas tipados de input y output. El agente no adivina. Si tu tool acepta un dict opaco, el modelo va a llenarlo con lo que le suene razonable — y va a equivocarse en los campos que importan justamente porque "sonaban opcionales".

El costo real

Doy números honestos, los míos. Para un servicio simple (5-10 endpoints, lógica clara), agregar el MCP server en el día uno cuesta entre 2 y 4 horas. Es menos que escribir el README. Si lo hacés cuando el servicio ya tiene cuarenta endpoints REST acumulados, la estimación realista sube a dos semanas de calendario.

La diferencia no es técnica. El código en sí no es lo que duele. Lo que duele es que retrofittear te obliga a debatir qué exponer y qué no, qué tools tiene sentido fusionar, cuáles son redundantes, cuáles nunca debieron existir. Y ese debate ya no tenés tiempo de tenerlo, porque hay seis cosas más arriba en la lista.

Es el clásico patrón de deuda: barata cuando se paga al momento, cara cuando se acumula. La diferencia con otras deudas es que ésta bloquea capacidades enteras del equipo, no solo velocidad incremental.

Patrón concreto: Akopia como caso límite

Un ejemplo de mi propio stack. Akopia no tiene UI. Su única superficie de consumo es el servidor MCP — no hay dashboard, no hay frontend admin, no hay Postman collection "oficial". Cero.

Eso forzó una disciplina interesante: lo que no está en MCP no existe operacionalmente. No hay endpoint "secreto" que solo usan los devs. No hay "sí, eso lo arreglás a mano con un SQL". La superficie agentic es la superficie real.

Resultado concreto: un agente puede aprender a usar Akopia leyendo su tool surface, sin que yo le pase documentación adicional. Eso es el test honesto. Si necesito mandar un PDF de cómo usarlo, fallé el principio. Akopia es el extremo — la mayoría de servicios no van a ser MCP-only — pero ayuda a calibrar qué se siente cuando la doctrina se aplica completa.

Cuando este default no aplica

No todo servicio necesita MCP. Dos excepciones que uso. Una: servicios puramente de infraestructura — sidecars, proxies, ingress controllers, schedulers internos. Su cliente legítimo es otro servicio, no un agente que razona sobre intención. Agregar MCP ahí es overhead innecesario.

Dos: superficies microscópicas, de uno o dos endpoints, donde el MCP no agrega capacidad expresiva sobre lo que ya describe el OpenAPI. Si tu servicio es básicamente una función pura expuesta por HTTP, no hace falta envolverla.

El patrón mental que uso: si el servicio pertenece al dominio del negocio y tiene más de cinco operaciones distinguibles, MCP es default. Si es plumbing o trivial, no.

La pieza que me costó internalizar: agent-readable no es "además de" terminado. Es parte de la definición. Mientras esa definición no cambie en el equipo, vas a tener mitad del stack listo para 2026 y mitad atado a un humano traduciendo.

¿En tu stack, qué porcentaje de servicios tiene MCP server hoy? Pregunto sin trampa — yo no llegué a 100%.

#MCP #AI #Platform #Architecture