Tag: MCP

Un equipo con el que trabajé tenía una API REST de facturación con cuarenta y tantos endpoints. Documentada con OpenAPI, en producción desde hacía años, sin drama.

Quisieron abrirla a un agente. Para pasar de API REST a servidor MCP hicieron lo obvio: generar el servidor desde el spec de OpenAPI. Cuarenta endpoints, cuarenta tools. Media tarde de trabajo. Funcionaba.

Y el agente era inútil.

Preguntabas "¿cómo está la cuenta de Marta?" y el modelo elegía listInvoices sin filtro, se tragaba doscientas facturas en el contexto y contestaba una vaguedad. Otras veces llamaba a getCustomer, luego a getCustomerById, luego a searchCustomers — tres tools que hacían casi lo mismo porque el backend llevaba cinco años acumulando variantes.

El problema no era el modelo. Era que habían traducido en vez de diseñar.

Cuando pasas de una API REST a un servidor MCP, la conversión mecánica es el error por defecto. Un buen servidor MCP expone menos tools que endpoints tiene la API. Y si no tienes API previa y quieres montar todo desde cero, empieza por construir el agente y su servidor MCP paso a paso — este post asume que ya tienes el backend en producción.

En una frase: un servidor MCP es un proceso que expone las capacidades de tu backend como tools —funciones con nombre, schema de entrada y descripción— para que un modelo pueda elegirlas y ejecutarlas por sí mismo. Si vienes de cero con el protocolo, el mapa completo está en qué son los servidores MCP. Aquí vamos a lo que casi nadie cuenta: cómo se decide qué parte de tu API merece ser una tool.

---

API REST describe recursos, servidor MCP describe capacidades

La diferencia entre una API REST y un servidor MCP no es el transporte: es quién decide qué llamar, cuándo y con qué información delante.

	API REST	Servidor MCP
Quién elige la llamada	Un programador, en tiempo de desarrollo	Un modelo, en tiempo de ejecución
Unidad de diseño	El recurso (/customers/{id})	La intención ("cómo está la cuenta de X")
Para qué sirve la descripción	Documentación que se lee una vez	Prompt que decide la llamada
Coste de añadir una más	Cercano a cero	Contexto en cada petición y más riesgo de elegir mal
Respuesta ideal	El objeto completo, el cliente filtra	Lo mínimo para razonar, el servidor recorta
Errores	Código HTTP y cuerpo estructurado	Frase accionable con isError: true

Tu API REST está escrita para un programador: alguien que ya sabe lo que quiere y que entiende por qué /customers/{id}/invoices devuelve algo distinto de /invoices?customer_id={id}. El contrato REST asume una decisión ya tomada.

MCP es lo contrario. El que lee tu catálogo de tools no sabe nada de tu dominio y tiene que decidir cuál llamar, con qué argumentos y en qué orden — a partir de una frase ambigua de un humano.

Esto cambia una cosa fundamental: la descripción de la tool no es documentación, es prompt. Es el texto que el modelo tiene delante en el momento de elegir. Si escribes "Obtiene un cliente" dejas la decisión al azar. Si escribes "Úsala cuando necesites el estado de facturación de un cliente a partir de su email; no sirve para crear ni modificar facturas", programas el comportamiento.

Y hay un coste que en REST no existe: la lista de tools viaja en cada petición. Cuarenta tools con sus schemas ocupan contexto antes de que el agente haya hecho nada. Cada tool que añades encarece todas las llamadas y hace la elección más difícil.

---

Qué endpoints de tu API REST se convierten en tool MCP (y cuáles no)

No, no va una tool por endpoint. El criterio que uso es uno solo: ¿este endpoint responde a una intención completa que un humano formularía?

Si un usuario puede decir "dime el estado de facturación de Marta" y ese endpoint lo resuelve entero, es candidato. Si es un paso intermedio que solo tiene sentido dentro de una secuencia, no lo es.

Con eso, esto queda fuera:

• CRUD granular. PATCH /customers/{id}/phone no es una intención, es un detalle de implementación. Si el agente necesita actualizar datos de contacto, una sola tool update_customer_contact con varios campos opcionales.
• Endpoints internos. Health checks, webhooks, callbacks de terceros, migraciones. El agente no los necesita y solo compiten por su atención.
• Los que devuelven payloads enormes. Un GET /events que escupe cinco mil registros no se convierte en tool: se convierte en tool con filtros obligatorios, o no se convierte.
• Los destructivos sin confirmación. DELETE /customers/{id} no va al servidor MCP tal cual. O lo marcas con destructiveHint y lo dejas detrás de una confirmación del cliente, o directamente no lo expones. Yo arranco siempre en solo lectura y añado escritura una a una.

Y una regla que ahorra mucho dolor: si dos endpoints se llaman siempre juntos, no son dos tools. Son una.

---

La tool de intención: consolida, no traduzcas

Una tool de intención es una sola tool que resuelve una pregunta completa del usuario agregando por dentro varias llamadas a tu API REST. Ahí está el cambio de mentalidad. La pregunta "cómo está la cuenta de Marta" en tu API REST son tres llamadas:

GET /customers?email=...        → el cliente
GET /customers/{id}/invoices    → sus facturas
GET /customers/{id}/payments    → el estado de pagos

La traducción mecánica te da getCustomer, listInvoices y getPaymentStatus. Tres tools, tres decisiones que el modelo puede equivocar, tres respuestas verbosas en el contexto y una orquestación que el agente tiene que inventarse en cada conversación.

La versión diseñada te da una: get_customer_billing_summary. Recibe un email, encadena esas llamadas por dentro y devuelve un resumen legible.

Tres decisiones menos que tomar, dos viajes menos de contexto y una orquestación que ya no depende de que el modelo acierte. Es el mismo backend; cambia dónde vive la lógica de composición.

---

Las cuatro piezas que no se traducen solas

Autenticación. El token de tu API REST no viaja como viajaba. Regla dura: el token nunca es un parámetro de la tool. Si lo pones en el inputSchema, acaba en el contexto del modelo y en los logs del cliente. En local, por stdio, el servidor lo lee de su entorno y el modelo ni se entera. En cuanto lo expones por red la historia se complica bastante — ahí tu servidor pasa a ser un resource server de OAuth 2.1 y toca leer qué se rompe cuando el MCP server sale del portátil.

Paginación. El agente no debe paginar a mano. Si expones page y per_page, hará cinco llamadas seguidas quemando contexto para reconstruir algo que podías haberle dado resumido.

Dos opciones honestas: un tope de resultados con un cursor explícito que el modelo pueda pasar de vuelta, o —mejor— los N más relevantes más un "hay 340 resultados, afina el filtro por fecha o estado". Empujar al agente a filtrar gana casi siempre a dejarle paginar.

Errores. Un 422 con un cuerpo tipo {"errors":{"date":"invalid format"}} es perfecto para un frontend y horrible para un modelo. El agente necesita texto que le diga qué corregir: "El campo date debe ir en formato YYYY-MM-DD. Reformatea el valor y vuelve a llamar." Y va como resultado con isError: true, no como excepción sin capturar: así el modelo lo lee y se autocorrige en el mismo turno en vez de rendirse.

Tamaño de la respuesta. Tu endpoint devuelve el objeto entero porque a un frontend le sale gratis ignorar campos. Al agente no: cada campo que no usa lo paga en contexto. Recorta en el servidor. De un objeto factura con treinta campos, el agente necesita número, fecha, importe y estado.

---

Servidor MCP en TypeScript con el SDK oficial

Un archivo para hablar con la API que ya tienes, sobre el SDK oficial de TypeScript:

// src/rest.ts
const BASE = process.env.BILLING_API_URL!;
const TOKEN = process.env.BILLING_API_TOKEN!; // del entorno, nunca del modelo

export class RestError extends Error {
  constructor(readonly status: number, readonly body: unknown) {
    super(`REST ${status}`);
  }
}

export async function rest<T>(path: string): Promise<T> {
  const res = await fetch(`${BASE}${path}`, {
    headers: { Authorization: `Bearer ${TOKEN}`, Accept: 'application/json' }
  });

  if (!res.ok) {
    throw new RestError(res.status, await res.json().catch(() => null));
  }

  return res.json() as Promise<T>;
}

export interface Customer {
  id: string;
  name: string;
  email: string;
}

export interface Invoice {
  number: string;
  issuedAt: string; // YYYY-MM-DD
  amount: number;
  status: 'draft' | 'sent' | 'paid' | 'overdue';
}

Y el servidor con la tool de intención que agrega dos llamadas REST:

// src/server.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
import { rest, RestError, type Customer, type Invoice } from './rest.js';

const server = new McpServer({ name: 'billing', version: '1.0.0' });

server.registerTool(
  'get_customer_billing_summary',
  {
    title: 'Resumen de facturación de un cliente',
    description:
      'Devuelve el estado de facturación de un cliente a partir de su email: ' +
      'datos básicos, facturas recientes e importe vencido. Úsala para responder ' +
      '"cómo está la cuenta de X". No sirve para crear ni modificar facturas.',
    inputSchema: {
      email: z.email().describe('Email del cliente, tal como lo dio el usuario'),
      months: z.number().int().min(1).max(12).default(3)
        .describe('Meses de histórico de facturas a incluir. Por defecto 3.')
    },
    annotations: { readOnlyHint: true }
  },
  async ({ email, months }) => {
    const since = new Date();
    since.setMonth(since.getMonth() - months);

    try {
      const [customer] = await rest<Customer[]>(
        `/customers?email=${encodeURIComponent(email)}`
      );

      if (!customer) {
        return {
          content: [{
            type: 'text',
            text: `No existe ningún cliente con el email ${email}. ` +
                  `Pide al usuario el email exacto antes de reintentar.`
          }],
          isError: true
        };
      }

      const invoices = await rest<Invoice[]>(
        `/customers/${customer.id}/invoices` +
          `?limit=20&since=${since.toISOString().slice(0, 10)}`
      );

      const overdue = invoices.filter(i => i.status === 'overdue');
      const owed = overdue.reduce((sum, i) => sum + i.amount, 0);

      // Recorte deliberado: solo lo que el agente necesita para razonar
      const lines = invoices
        .slice(0, 10)
        .map(i => `- ${i.number} · ${i.issuedAt} · ${i.amount} € · ${i.status}`);

      return {
        content: [{
          type: 'text',
          text: [
            `Cliente: ${customer.name} (${customer.email})`,
            `Facturas últimos ${months} meses: ${invoices.length}`,
            `Vencidas: ${overdue.length} · Importe pendiente: ${owed} €`,
            '',
            ...lines,
            invoices.length > 10 ? `… y ${invoices.length - 10} más.` : ''
          ].join('\n')
        }]
      };
    } catch (error) {
      if (error instanceof RestError && error.status === 422) {
        return {
          content: [{
            type: 'text',
            text: `La API rechazó los parámetros: ${JSON.stringify(error.body)}. ` +
                  `Corrige el valor indicado y vuelve a llamar.`
          }],
          isError: true
        };
      }
      throw error;
    }
  }
);

await server.connect(new StdioServerTransport());

Fíjate en el .describe() de cada campo: es la única documentación que el modelo recibe de ese argumento. En una API REST el tipo basta porque hay un humano leyendo el spec; aquí el texto es la interfaz. Esa combinación de tipado y semántica es donde Zod deja de ser un validador y pasa a ser parte del diseño — si quieres exprimirlo, lo trabajo a fondo en el curso de Zod para TypeScript. Si sigues en Zod 3, esa línea es z.string().email(); desde Zod 4 la forma recomendada es z.email().

Un apunte de versiones (septiembre de 2026): el código de arriba corre sobre @modelcontextprotocol/sdk 1.30.0, cuyo inputSchema admite el shape suelto —{ email: z.string() }— y también un z.object({ ... }). La v2 se publica como paquete aparte, @modelcontextprotocol/server 2.0.0, y ahí el shape suelto queda deprecado a favor del z.object() explícito. El monolítico no está deprecado y es el que sigues viendo en la mayoría de servidores, que es por lo que el ejemplo va con él. Los dos implementan la revisión 2026-07-28 de la spec, donde están definidas las annotations y el outputSchema. El criterio de diseño de este post no cambia entre versiones.

Para probarlo, regístralo en tu cliente y lánzale la pregunta en lenguaje natural. Los scopes y el claude mcp add los tienes desglosados en el tutorial de MCP server con Claude Code.

---

Checklist de migración de API REST a servidor MCP

Antes de dar por buena la conversión de tu API:

1. Cuenta. ¿Tienes menos tools que endpoints? Si no, no has diseñado, has traducido.
2. Lee las descripciones en voz alta. Si no explican cuándo usar la tool y cuándo no, reescríbelas.
3. Busca solapes. Dos tools que un humano confundiría, un modelo también.
4. Mide el peor payload. Si una respuesta puede reventar el contexto, mete tope y filtros obligatorios.
5. Convierte los errores. Cada error de tu API tiene que salir como frase accionable con isError: true.
6. Saca el token del schema. Si aparece en inputSchema, tienes una fuga.
7. Arranca en solo lectura. Escritura y borrado después, uno a uno y con confirmación.

---

Lo que haría hoy

Abre el OpenAPI de tu API. Marca los endpoints que responden a una frase completa de un usuario. Normalmente son entre cinco y ocho de cuarenta.

Esos son tus tools. El resto es la fontanería que vive dentro de ellos.

Y luego escribe las descripciones como si fueran prompts — porque lo son. Esa es la parte que casi nadie hace, y la que separa un servidor MCP que el agente usa bien de uno que solo se ve bonito en el tools/list.

Este salto de "envolver lo que ya tengo" a "diseñar la superficie que el agente necesita" es el mismo que trabajo en el curso Construye con IA, y si quieres ver servidores MCP reales con sus decisiones y sus errores, los desmenuzamos en Dominicode Labs.

---

Preguntas frecuentes

¿Cuántas tools debería tener mi servidor MCP?

No hay número mágico, pero sí una señal: si tienes tantas tools como endpoints, has traducido en vez de diseñar. En APIs de tamaño medio suelo acabar entre cinco y diez tools de intención. La pregunta correcta no es cuántas caben, sino cuántas puedes quitar sin perder capacidad real.

¿Puedo generar el servidor MCP automáticamente desde mi OpenAPI?

Puedes, y es justo lo que produce agentes malos. Un generador hace exactamente la conversión mecánica de 1 endpoint = 1 tool: sin criterio sobre qué endpoints son intenciones completas, sin consolidar llamadas y sin descripciones pensadas para un modelo. Úsalo como inventario de partida si quieres, pero la selección y el redactado de las descripciones son trabajo manual.

¿Cómo paso el token de mi API REST al servidor MCP?

Nunca como parámetro de la tool: ahí acaba en el contexto del modelo y en los logs del cliente. En local, con transporte stdio, el servidor lo lee de una variable de entorno y el modelo ni lo ve. Si lo expones por HTTP, el cliente presenta su propio token al servidor MCP y es tu servidor quien traduce esa identidad a la credencial de la API interna.

¿Qué hago con los endpoints de escritura o destructivos?

Sepáralos desde el arranque. Empieza en solo lectura, marcando esas tools con readOnlyHint, y añade escritura una a una cuando ya sabes cómo se comporta el agente con tu dominio. Lo destructivo lleva destructiveHint y confirmación del cliente; si algo cobra dinero o borra registros, además tiene que ser idempotente.

¿La tool debe devolver JSON o texto?

Texto, salvo razón concreta para lo contrario. El JSON crudo arrastra campos que el agente no usa y paga en contexto. Si además necesitas la forma estructurada, el SDK permite declarar un outputSchema y devolver structuredContent junto al texto.

---

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

Tu MCP server funciona. Lo lanzas por stdio, tu agente lo ve, las tools responden.

Y entonces alguien pregunta lo obvio: ¿y si lo usamos desde el resto del equipo?

Ahí es donde la cosa deja de parecerse a lo que montaste. Porque un server local por stdio es un proceso hijo hablando por una tubería: sin red, sin autenticación, sin concurrencia, sin nada que se pueda caer a medias. En cuanto lo expones por HTTP, todo eso aparece de golpe — y encima el protocolo ha cambiado justo en las piezas que te afectan.

Si todavía no tienes el server montado, empieza por construir un agente y su MCP server paso a paso, y para registrarlo en tu entorno tienes claude mcp add explicado con sus scopes. Este post empieza donde acaban esos dos: el día que ese server deja de ser tuyo.

Van seis cosas, todas verificables contra la especificación.

---

1. SSE está deprecado. El transporte es Streamable HTTP

Si has leído tutoriales de MCP del último año y medio, muchos te dicen que para salir a red uses SSE (Server-Sent Events) con dos endpoints.

No lo hagas. El transporte HTTP+SSE está deprecado desde la revisión 2025-03-26 del protocolo, y la revisión 2026-07-28 lo reclasifica formalmente como Deprecated bajo la nueva política de ciclo de vida, con la instrucción explícita de migrar a Streamable HTTP. El SDK de TypeScript ya marca SSEClientTransport como @deprecated.

La diferencia práctica: SSE usaba dos endpoints (uno para abrir el stream, otro para mandar mensajes). Streamable HTTP usa uno solo, que gestiona las dos direcciones. Menos superficie, menos estado que coordinar y mucho menos que explicarle a tu balanceador.

Lo bueno es que esto no depende de si migras a la v2 o no: la deprecación de SSE es anterior y aplica igual. Si tu server remoto habla SSE, ya vas con retraso.

---

2. Ya no hay sesiones — y eso te simplifica el escalado

Este es el cambio que más agradece la infraestructura.

La revisión 2026-07-28 elimina las sesiones a nivel de protocolo y la cabecera Mcp-Session-Id del transporte Streamable HTTP. Y va más allá: elimina también el handshake initialize/notifications/initialized. Cada petición viaja ahora con su versión de protocolo y las capacidades del cliente dentro de _meta.

Traducido a lo que te importa un lunes por la mañana: desaparecen las sticky sessions. Puedes poner un round-robin normal delante de N réplicas y ya está. Si alguna vez has peleado con un balanceador intentando que un cliente vuelva siempre a la misma instancia, esta es la razón para mirar la v2.

El matiz importante: si tu server necesitaba estado entre llamadas, ahora no lo guardas en la sesión. La spec dice que los servidores que necesiten estado entre llamadas usen handles explícitos, acuñados por el servidor y pasados como argumentos normales de una tool. Es decir: el estado deja de ser magia del transporte y pasa a ser parte de tu contrato de datos, visible y tipado.

También aparece un server/discover que los servidores deben implementar para anunciar versiones soportadas, capacidades e identidad.

---

3. Un stream que se rompe pierde la petición

Esta es la que más te va a doler si no la ves venir, y es la menos comentada.

La revisión 2026-07-28 elimina la resumibilidad del stream y la reentrega de mensajes: fuera la cabecera Last-Event-ID y fuera los IDs de evento SSE. Lo que dice la spec es directo: si el stream de respuesta se corta, la petición en vuelo se pierde, y el cliente debe reemitirla como una petición nueva con un ID nuevo.

Piensa en lo que significa eso con una tool que cobra una suscripción, crea un usuario o lanza un despliegue. Un corte de red a mitad y el cliente reintenta. Si tu tool no es idempotente, acabas de cobrar dos veces.

En local esto no existía. Una tubería stdio no se corta a medias. En red, sí.

Lo que hay que hacer es lo de siempre en sistemas distribuidos, solo que ahora te toca a ti aplicarlo en la capa de tools:

• Toda tool con efectos secundarios necesita una clave de idempotencia que venga en los argumentos, no generada dentro.
• Separa lectura de escritura. Las de lectura pueden reintentarse alegremente; las de escritura, solo con la clave.
• Registra el resultado por clave y, si llega repetida, devuelve el resultado guardado en lugar de volver a ejecutar.

En la práctica son unas pocas líneas delante de tu lógica:

const ArgsSchema = z.object({
  idempotencyKey: z.string().uuid().describe("Identificador único de este intento"),
  usuarioId: z.string(),
  plan: z.enum(["pro", "team"]),
});

async function cambiarPlan(args: unknown) {
  const { idempotencyKey, usuarioId, plan } = ArgsSchema.parse(args);

  const previo = await store.get(idempotencyKey);
  if (previo) return previo;               // el reintento no vuelve a cobrar

  const resultado = await facturacion.cambiarPlan(usuarioId, plan);
  await store.set(idempotencyKey, resultado, { ttlSegundos: 86_400 });
  return resultado;
}

La clave llega en los argumentos, no se genera dentro: si la generaras tú, cada reintento traería una distinta y no servirían de nada.

Ese criterio de qué se automatiza y qué no —lo reversible frente a lo irreversible— es el mismo que aplico a los permisos de un agente, y lo desarrollé en inyección indirecta de prompts en agentes.

---

4. Autenticación: tu server pasa a ser un resource server de OAuth 2.1

En local no hay autenticación porque no hace falta: el proceso es tuyo. En red hace falta, y MCP no se la inventa: se apoya en OAuth 2.1.

El modelo mental que conviene fijar: tu MCP server es un resource server, no un servidor de autorización. Valida tokens y sirve recursos. No emite tokens ni loguea a nadie. Eso es de otro.

Las piezas:

• Metadatos de recurso protegido. Tu server publica /.well-known/oauth-protected-resource, un JSON que declara su identificador, los servidores de autorización en los que confía, los scopes que soporta y los métodos de bearer que acepta. Es lo que permite a un cliente descubrir a dónde ir a pedir el token:

  {
    "resource": "https://mcp.tudominio.com",
    "authorization_servers": ["https://auth.tudominio.com"],
    "scopes_supported": ["mcp:read", "mcp:write"],
    "bearer_methods_supported": ["header"]
  }
  

• El parámetro resource. El cliente lo manda en la petición de autorización y en la de token. Es el mecanismo que impide que un token acuñado para tu server sirva en otro distinto.

• Registro de cliente. La revisión 2026-07-28 deprecia el Dynamic Client Registration en favor de los Client ID Metadata Documents, aunque DCR sigue disponible por compatibilidad. También pide validar el parámetro iss de la respuesta de autorización contra el emisor registrado antes de canjear el código, y que las credenciales persistidas se indexen por emisor y no se reutilicen con otro servidor de autorización.

Si vas a exponer un server a terceros, esta sección es la que decide si te lo pueden usar las empresas o no. El caso de negocio de tener el tuyo lo desarrollé en MCP server para empresas.

---

5. Observabilidad: el logging del protocolo se va, entra OpenTelemetry

La revisión 2026-07-28 deprecia las features de Roots, Sampling y Logging. Siguen funcionando durante la ventana de deprecación —que la política fija en un mínimo de doce meses— pero las implementaciones nuevas no deberían adoptarlas.

Para el logging, la migración que sugiere la propia spec es explícita: escribir a stderr (en stdio) o usar OpenTelemetry.

Y la spec te lo pone fácil, porque documenta la propagación de contexto de trazas de OpenTelemetry sobre las claves _meta: traceparent, tracestate y baggage. Eso significa que puedes correlacionar la traza de tu backend con la llamada del agente que la originó, que es justo lo que echas de menos la primera vez que un tool call falla en producción y no sabes de qué conversación venía.

---

6. El caché que te ahorra tokens (y casi nadie configura)

Este es el que da alegrías y no cuesta nada.

La revisión 2026-07-28 exige los campos ttlMs y cacheScope en los resultados de tools/list, prompts/list, resources/list, resources/read y resources/templates/list, mediante una nueva interfaz CacheableResult. ttlMs es una pista de frescura en milisegundos para que el cliente cachee y deje de sondear; cacheScope ("public" o "private") controla si un intermediario compartido puede cachear la respuesta.

Y hay un detalle pequeño con consecuencias grandes: la spec dice que los servidores deberían devolver las tools de tools/list en un orden determinista, explícitamente para permitir el caché del lado del cliente y mejorar los aciertos de caché de prompt del LLM.

Piénsalo un segundo. La lista de tools va al principio del contexto. Si tu server la devuelve en orden distinto en cada petición, estás invalidando el prefijo cacheado del prompt en cada llamada y pagando entrada completa cada vez. Ordenar un array te sale gratis.

---

Y una que no viene de la spec: la deriva de esquemas

Esto no es un cambio del protocolo, es el fallo que más veo en servers reales.

El patrón habitual define el esquema dos veces: una con Zod para validar en ejecución, y otra a mano como JSON Schema en la respuesta de tools/list. Dos fuentes de verdad para el mismo contrato.

El día que añades un campo y solo tocas una, el resultado no es un error: es peor. El modelo lee un contrato y tu servidor valida otro, así que el agente manda llamadas perfectamente razonables que tu server rechaza. Y como el fallo llega como un error de validación, parece culpa del modelo.

La regla: el JSON Schema que publicas tiene que derivarse del esquema que valida, nunca escribirse en paralelo. Un solo sitio donde cambiar las cosas.

Los patrones para modelar y derivar contratos con Zod los vemos en el curso de Zod para TypeScript. Y si vas a definir las tools antes de escribirlas —que es lo que evita justo esta clase de deriva— la metodología está en el libro de Spec-Driven Development.

---

Checklist antes de exponerlo

1. Transporte: Streamable HTTP, un solo endpoint. Si tienes SSE, tienes deuda.
2. Idempotencia: clave en los argumentos para toda tool con efectos secundarios, y resultado guardado por clave.
3. Sin sesiones: nada de sticky sessions; el estado entre llamadas viaja como handle explícito en los argumentos.
4. Auth: /.well-known/oauth-protected-resource publicado y validación del parámetro resource en los tokens.
5. Trazas: propaga traceparent por _meta y manda las trazas a tu colector.
6. Caché: ttlMs y cacheScope en los listados, y tools/list siempre en el mismo orden.
7. Un solo esquema: el JSON Schema publicado, derivado del validador.

El flujo completo de diseñar herramientas para agentes y llevarlas a producción es lo que enseño en el curso Construye con IA: de la idea al producto con Claude Code.

En Dominicode Labs tengo servidores MCP corriendo para infraestructura, analítica y publicación, y comparto ahí las configuraciones que aguantan.

Montar un MCP server es una tarde. Exponerlo es un sistema distribuido. La diferencia entre las dos cosas son estas siete líneas.

---

Preguntas frecuentes

¿Tengo que migrar mi MCP server a la v2 ya?

Para el protocolo, no: hablar la revisión nueva es opt-in y la v1 sigue soportada. Pero la deprecación de SSE es anterior e independiente de la v2 —viene de la revisión 2025-03-26— así que si tu server remoto habla SSE, eso sí conviene cambiarlo aunque no toques nada más. Lo que sí trae la v2 y compensa de verdad es quitarte las sticky sessions.

¿Qué diferencia hay entre SSE y Streamable HTTP en un MCP server?

SSE usaba dos endpoints: uno para mantener abierto el stream de servidor a cliente y otro para que el cliente enviara mensajes. Streamable HTTP usa un único endpoint que gestiona ambas direcciones. Menos piezas que coordinar, menos configuración en el balanceador y menos estado que mantener vivo entre peticiones.

Si desaparecen las sesiones, ¿dónde guardo el estado entre llamadas?

En los argumentos de la tool. La spec indica que los servidores que necesiten estado entre llamadas usen handles explícitos acuñados por el propio servidor y pasados como parámetros normales. Deja de ser un implícito del transporte y pasa a formar parte del contrato de datos, que es más fácil de depurar y de tipar.

¿Por qué mis tools tienen que ser idempotentes en un server remoto?

Porque la revisión 2026-07-28 elimina la reentrega de mensajes y la resumibilidad del stream. Si la conexión se corta, la petición en vuelo se pierde y el cliente debe reemitirla como una petición nueva. Sin clave de idempotencia, una tool que cobra o crea algo lo haría dos veces. En local, con stdio, este escenario no existe.

¿Mi MCP server tiene que emitir tokens de autenticación?

No. Tu server es un resource server: valida tokens y sirve recursos, nunca emite tokens ni autentica usuarios. De eso se encarga un servidor de autorización aparte. Lo que sí publica tu server es /.well-known/oauth-protected-resource, para que los clientes descubran en qué servidor de autorización pedir el token y con qué scopes.

Hace tres semanas un dev me escribió por Telegram con un MCP server funcionando. Lo había construido siguiendo un tutorial. Arrancaba, registraba sus tools, Claude Code lo detectaba. Todo perfecto.

Su pregunta era: "¿y ahora cómo hago que mi agente lo use?".

No supo responderse porque el tutorial terminaba justo ahí. Y ese es el problema con casi todo el material que hay sobre MCP: te enseñan a construir el enchufe, pero nunca el aparato que se enchufa. O al revés — te enseñan a montar un agente con tools locales y jamás mencionan por qué querrías sacarlas a un servidor.

Son dos mitades de la misma pieza. Y separadas no sirven de mucho.

Este post construye las dos. Un MCP server real en TypeScript, un agente que lo consume, y el puente entre ambos. Código verificado contra el SDK, no de memoria. Al final sabrás también cuándo no deberías montar un MCP server, que es una decisión que mucha gente se salta.

---

Las dos mitades: quién expone y quién consume

Un MCP server expone capacidades: tools, resources y prompts. No tiene inteligencia. No decide nada. Es un catálogo de funciones con un contrato estándar delante. Si no tienes claro el concepto de fondo, este post explica qué es Model Context Protocol antes de meterte en código.

Un agente es lo contrario: tiene el modelo, tiene el bucle, y decide qué llamar y cuándo. Lo que no tiene es acceso a tu mundo — a tu base de datos, a tu API interna, a tus postmortems.

MCP es el estándar que une las dos cosas sin que se conozcan entre sí. Escribes el server una vez, y lo consumen Claude Code, Claude Desktop, tu agente propio y el agente que escriba tu compañero el mes que viene.

Esa reutilización es todo el valor de MCP. Recuérdalo, porque en la última sección lo usaremos para decidir si te hace falta.

Vamos a construir un server sobre un caso que a cualquiera con sistemas en producción le suena: un histórico de incidencias. Datos internos, API que nadie más va a integrar, y consultas que un modelo puede hacer mucho mejor que un dashboard.

---

Paso 1: el MCP server en TypeScript

Construir un MCP server en TypeScript requiere tres piezas: el paquete @modelcontextprotocol/sdk con zod como peer dependency, una instancia de McpServer, y un transporte stdio. Este paso monta las tres sobre un caso real.

Primero, versiones. Y aquí hay que ser preciso porque el ecosistema está en transición.

La versión de producción hoy es la v1, en el paquete @modelcontextprotocol/sdk (última: 1.29.0). Es sobre la que vas a construir. Hay una v2 en beta que lo cambia bastante, y le dedico una sección entera más abajo — pero no construyas sobre ella todavía.

mkdir mcp-incidencias && cd mcp-incidencias
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

zod es peer dependency obligatoria del SDK v1, no es opcional.

En tu package.json añade "type": "module", y en el tsconfig.json usa "module": "NodeNext" y "target": "ES2022". Sin eso los imports con extensión .js te van a dar guerra.

Ahora el servidor. Archivo src/server.ts:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

type Severidad = 'baja' | 'media' | 'alta';

interface Incidencia {
  id: string;
  servicio: string;
  fecha: string;
  severidad: Severidad;
  titulo: string;
  causaRaiz: string;
}

// En producción esto sale de tu base de datos.
const INCIDENCIAS: Incidencia[] = [
  {
    id: 'INC-101',
    servicio: 'checkout-api',
    fecha: '2026-05-14',
    severidad: 'alta',
    titulo: 'Timeouts masivos en pasarela de pago',
    causaRaiz: 'Pool de conexiones agotado tras un deploy sin migrar el límite.'
  },
  {
    id: 'INC-118',
    servicio: 'checkout-api',
    fecha: '2026-06-02',
    severidad: 'media',
    titulo: 'Latencia elevada en cálculo de impuestos',
    causaRaiz: 'Consulta N+1 introducida al añadir el desglose por región.'
  },
  {
    id: 'INC-124',
    servicio: 'auth-service',
    fecha: '2026-06-21',
    severidad: 'alta',
    titulo: 'Sesiones invalidadas de forma masiva',
    causaRaiz: 'Rotación de claves JWT desplegada sin periodo de solapamiento.'
  }
];

const server = new McpServer({ name: 'incidencias', version: '1.0.0' });

Fíjate en los imports: llevan la extensión .js y la ruta interna del paquete (/server/mcp.js). No es @modelcontextprotocol/sdk a secas. Es el error más habitual al empezar.

Ahora registramos la primera tool:

const ORDEN: Record<Severidad, number> = { baja: 0, media: 1, alta: 2 };

server.registerTool(
  'buscar_incidencias',
  {
    title: 'Buscar incidencias',
    description:
      'Busca incidencias de producción de un servicio, filtrando por severidad mínima. ' +
      'Úsala cuando necesites el histórico de fallos de un servicio concreto.',
    inputSchema: {
      servicio: z.string().describe('Nombre del servicio, por ejemplo: checkout-api'),
      severidadMinima: z.enum(['baja', 'media', 'alta']).default('baja')
    },
    outputSchema: {
      total: z.number(),
      incidencias: z.array(
        z.object({
          id: z.string(),
          fecha: z.string(),
          severidad: z.string(),
          titulo: z.string()
        })
      )
    }
  },
  async ({ servicio, severidadMinima }) => {
    const encontradas = INCIDENCIAS.filter(
      (i) => i.servicio === servicio && ORDEN[i.severidad] >= ORDEN[severidadMinima]
    ).map(({ id, fecha, severidad, titulo }) => ({ id, fecha, severidad, titulo }));

    const output = { total: encontradas.length, incidencias: encontradas };

    return {
      content: [{ type: 'text', text: JSON.stringify(output, null, 2) }],
      structuredContent: output
    };
  }
);

Un detalle que ahorra tardes: inputSchema acepta tanto la forma en crudo ({ servicio: z.string() }) como un z.object() completo. El SDK normaliza las dos por dentro y el JSON Schema que acaba llegando al modelo es idéntico. Uso la forma cruda porque es menos ruido, pero si vienes de otra librería y te sale envolver, no rompes nada.

Guárdalo, porque dentro de un momento vamos a ver otra librería donde esa flexibilidad no existe.

Lo segundo: la description no es documentación, es prompt. Es literalmente lo único que el modelo lee para decidir si usa esta tool. Una descripción vaga es una tool que nunca se llama, o que se llama cuando no toca. Escríbela pensando en el modelo, incluyendo cuándo usarla.

Segunda tool, con manejo de errores:

server.registerTool(
  'detalle_incidencia',
  {
    title: 'Detalle de incidencia',
    description: 'Devuelve la causa raíz completa de una incidencia por su ID (formato INC-XXX).',
    inputSchema: {
      id: z.string().describe('Identificador, por ejemplo: INC-101')
    }
  },
  async ({ id }) => {
    const incidencia = INCIDENCIAS.find((i) => i.id === id);

    if (!incidencia) {
      return {
        content: [{ type: 'text', text: `No existe ninguna incidencia con ID ${id}.` }],
        isError: true
      };
    }

    return {
      content: [
        {
          type: 'text',
          text: `${incidencia.id} — ${incidencia.titulo}\nServicio: ${incidencia.servicio}\nFecha: ${incidencia.fecha}\nSeveridad: ${incidencia.severidad}\nCausa raíz: ${incidencia.causaRaiz}`
        }
      ]
    };
  }
);

isError: true en lugar de lanzar una excepción. La diferencia importa: con isError el modelo recibe el mensaje y puede corregirse solo — reintentar con otro ID, o decirle al usuario que no existe. Si lanzas, revientas la conexión y el agente se queda ciego.

Y el arranque:

const transport = new StdioServerTransport();
await server.connect(transport);

console.error('MCP server de incidencias escuchando en stdio');

console.error, nunca console.log. En transporte stdio, stdout es el canal JSON-RPC. Un solo console.log mete texto suelto en la tubería y rompe el protocolo con un error de parseo que no dice nada útil. Todo tu logging va a stderr.

Ya tienes la mitad de la pieza. Si quieres comprobar que funciona antes de seguir, no hace falta registrarlo en ningún cliente: npx @modelcontextprotocol/inspector npx tsx src/server.ts levanta MCP Inspector, la herramienta oficial, y te deja ver las tools registradas e invocarlas a mano desde el navegador.

Si además quieres usarlo desde Claude Code, tengo aparte las notas sobre registrar un MCP server en Claude Code — es el complemento natural de esta sección, no un camino alternativo.

---

Paso 2: el agente que consume las tools

El agente se construye con el Tool Runner del SDK de Anthropic (client.beta.messages.toolRunner), que ejecuta por ti el bucle completo: llama al modelo, ejecuta la tool que pida, le devuelve el resultado, y repite hasta obtener una respuesta final.

Aquí hay una confusión que veo constantemente y conviene despejarla antes de escribir una línea, porque son dos productos distintos de Anthropic:

• Tool Runner (client.beta.messages.toolRunner, dentro del SDK normal @anthropic-ai/sdk): automatiza el bucle sobre las tools que tú defines. Sin tools integradas, sin sandbox. Tú pones todo.
• Claude Agent SDK (@anthropic-ai/claude-agent-sdk): es Claude Code empaquetado como librería, con tools integradas de serie — leer y escribir ficheros, bash, grep.

No son versiones distintas de lo mismo. Para este caso queremos el Tool Runner, porque lo que nos interesa es controlar exactamente qué tools existen.

npm install @anthropic-ai/sdk

Un agente mínimo con una tool local:

import Anthropic from '@anthropic-ai/sdk';
import { betaZodTool } from '@anthropic-ai/sdk/helpers/beta/zod';
import { z } from 'zod';

const client = new Anthropic(); // lee ANTHROPIC_API_KEY del entorno

const buscarIncidencias = betaZodTool({
  name: 'buscar_incidencias',
  description: 'Busca incidencias de producción de un servicio por severidad mínima.',
  inputSchema: z.object({
    servicio: z.string().describe('Nombre del servicio, por ejemplo: checkout-api'),
    severidadMinima: z.enum(['baja', 'media', 'alta']).default('baja')
  }),
  run: async (input) => {
    // aquí llamarías a tu API real
    return JSON.stringify({ servicio: input.servicio, total: 0, incidencias: [] });
  }
});

const respuesta = await client.beta.messages.toolRunner({
  model: 'claude-opus-4-8',
  max_tokens: 16000,
  thinking: { type: 'adaptive' },
  messages: [
    {
      role: 'user',
      content: '¿Qué incidencias graves ha tenido checkout-api? Resume el patrón que veas.'
    }
  ],
  tools: [buscarIncidencias]
});

console.log(respuesta.content);

Fíjate en la diferencia con el server: en betaZodTool el inputSchema tiene que ser un z.object() completo. Aquí no hay normalización que te salve — pasarle la forma en crudo no funciona.

Las tres convenciones de schema que se confunden entre sí

El mismo concepto cambia de formato según la librería. Es la causa más frecuente de tools que se registran pero nunca se llaman bien:

Librería y función	Propiedad	Formato esperado
MCP SDK v1 — registerTool	inputSchema	Forma cruda o z.object(); el SDK normaliza las dos
Anthropic SDK — betaZodTool	inputSchema	z.object() completo, obligatorio
Anthropic SDK — betaTool	inputSchema	JSON Schema plano (el que devuelve listTools())

Las tres reciben inputSchema en camelCase. El input_schema en snake_case que quizá tengas visto es lo que viaja por la red hacia la API, no lo que le pasas al helper. Escribir snake_case en cualquiera de los tres revienta con un TypeError.

Tres cosas más sobre los parámetros, que están cambiadas respecto a lo que quizá tengas memorizado:

• El modelo es claude-opus-4-8. Sin sufijo de fecha.
• thinking va con { type: 'adaptive' }. budget_tokens está eliminado en Opus 4.8 y devuelve un 400.
• temperature, top_p y top_k rechazan cualquier valor que no sea el por defecto y devuelven 400. Si arrastras un temperature: 0 de un proyecto viejo, esa llamada falla. Se dirige el comportamiento por prompt, no por sampling.

max_tokens alrededor de 16000 para peticiones normales, hasta ~64000 si haces streaming.

El Tool Runner ejecuta el bucle completo por ti: llama al modelo, si pide una tool la ejecuta, le devuelve el resultado, y repite hasta que el modelo da una respuesta final. Ese bucle es el corazón de cualquier agente — y si quieres entender por qué la calidad del bucle importa más que el modelo que metas dentro, lo desarrollo aquí. Para los fundamentos de la API, este crash course te cubre.

---

Paso 3: conectar las dos mitades

Conectar el agente con el MCP server consiste en levantar un cliente MCP, pedirle sus tools con listTools() y traducirlas al formato del Tool Runner con betaTool. Así el agente ejecuta las tools reales del server en vez de copias locales.

Ahora lo que casi nadie enseña. El agente del paso anterior tiene la tool duplicada en local. Queremos que consuma las tools reales del MCP server, sin reescribirlas.

Para eso montamos un cliente MCP, le preguntamos qué tools tiene, y las traducimos al formato del Tool Runner:

import Anthropic from '@anthropic-ai/sdk';
import { betaTool } from '@anthropic-ai/sdk/helpers/beta/json-schema';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['tsx', 'src/server.ts']
});

const mcp = new Client({ name: 'agente-incidencias', version: '1.0.0' });
await mcp.connect(transport);

// 1. Descubrimos las tools que expone el server
const { tools } = await mcp.listTools();

// 2. Las convertimos en tools ejecutables para el Tool Runner
const puente = tools.map((tool) =>
  betaTool({
    name: tool.name,
    description: tool.description ?? '',
    inputSchema: tool.inputSchema as any,
    run: async (input) => {
      const resultado = await mcp.callTool({
        name: tool.name,
        arguments: input as Record<string, unknown>
      });
      return JSON.stringify(resultado.content);
    }
  })
);

// 3. El agente ya usa las tools reales del server
const respuesta = await new Anthropic().beta.messages.toolRunner({
  model: 'claude-opus-4-8',
  max_tokens: 16000,
  thinking: { type: 'adaptive' },
  messages: [
    {
      role: 'user',
      content:
        'Revisa las incidencias graves de checkout-api, mira el detalle de cada una ' +
        'y dime si hay un patrón común en las causas raíz.'
    }
  ],
  tools: puente
});

console.log(respuesta.content);
await mcp.close();

Eso es el circuito completo. Aquí usamos betaTool en lugar de betaZodTool porque listTools() devuelve JSON Schema, no Zod. Encaja directo: le pasas el inputSchema tal cual llega del server.

Y ojo con el detalle que más despista de todo el post: los helpers reciben inputSchema en camelCase, pero lo que viaja a la API es input_schema en snake_case. Si escribes tools a mano contra la API cruda usas snake_case; con los helpers, siempre camelCase. Escribir input_schema: dentro de betaTool no da un error de validación bonito — revienta con un TypeError antes de tocar la red.

Cuando entiendas el mecanismo, el SDK ya trae ese puente hecho:

import { mcpTools } from '@anthropic-ai/sdk/helpers/beta/mcp';

const puente = mcpTools(tools, mcp);

Merece la pena haber escrito el map a mano una vez: cuando el helper falle, sabrás qué está haciendo por dentro.

Lo potente es que ese map no sabe nada de tus tools. Añade una tercera tool al server y el agente la tiene disponible en el siguiente arranque, sin tocar el código del agente. Ahí es donde MCP paga lo que cuesta.

Al ejecutarlo verás al agente encadenar solo: llama a buscar_incidencias, recibe dos IDs, llama a detalle_incidencia con cada uno, y razona sobre las causas raíz. Nadie le dijo el orden.

La otra vía: el conector MCP remoto

Si en vez de stdio despliegas el server sobre HTTP, la API de Claude puede conectarse a él directamente, sin cliente MCP en tu código:

const message = await client.beta.messages.create({
  model: 'claude-opus-4-8',
  max_tokens: 16000,
  betas: ['mcp-client-2025-11-20'],
  mcp_servers: [
    {
      type: 'url',
      url: 'https://incidencias.tudominio.com/mcp',
      name: 'incidencias'
    }
  ],
  tools: [{ type: 'mcp_toolset', mcp_server_name: 'incidencias' }],
  messages: [{ role: 'user', content: '¿Qué incidencias graves tuvo checkout-api?' }]
});

El conector MCP remoto exige declarar mcp_servers y tools a la vez. Declarar solo mcp_servers hace que la petición se rechace con un error de validación, aunque parezca redundante — ya has dicho dónde está el server, ¿para qué repetirlo? Cada server declarado en mcp_servers necesita su entrada { type: 'mcp_toolset', mcp_server_name: '<nombre>' } dentro de tools, y el mcp_server_name debe coincidir exactamente con el name del server.

Ojo también: esta vía requiere un server con URL pública. Un server stdio no sirve aquí, para eso está el puente de arriba. La documentación del conector MCP de la API de Anthropic detalla el resto de campos disponibles.

---

MCP v2 y la spec 2026-07-28: qué cambia y por qué no tienes que migrar

El 28 de julio de 2026 salen la spec MCP 2026-07-28 y las SDK estables de la v2. Vas a ver posts en tono de urgencia. Ignóralos.

La documentación oficial es explícita en dos puntos. Sobre las versiones, la v1.x sigue siendo "the supported release for production" y mantiene bugfixes y parches de seguridad al menos 6 meses después de que v2 sea estable. Y sobre el protocolo, la guía de la revisión lo cierra: "Nothing in v2 puts a 2026-07-28 byte on the wire by default" — hablar la revisión nueva es siempre un opt-in explícito. Migrar a v2 es opcional y va separado de la fecha del protocolo.

Puedes seguir las dos fuentes de primera mano: la especificación del protocolo y el SDK de TypeScript en GitHub.

El servidor que acabas de construir sigue funcionando. No hay nada que correr a arreglar.

Dicho eso, la v2 no es un cambio cosmético y merece que sepas qué trae, porque cambia decisiones de arquitectura:

Se parte el paquete. El monolítico @modelcontextprotocol/sdk desaparece en favor de @modelcontextprotocol/server, @modelcontextprotocol/client y @modelcontextprotocol/core. La v2 no sale como versión nueva del paquete viejo: son paquetes distintos. Por eso no hay riesgo de que te llegue sola en un npm update.

Protocolo stateless. Cuando activas la revisión nueva, desaparecen el handshake initialize y la gestión de sesión. Traducido a infraestructura: escalas con un round-robin normal, sin sticky sessions. Si has sufrido balanceo con sesiones MCP, esta es la razón para migrar. Ojo: en la v2 el modo de 2025 sigue siendo el por defecto; la revisión 2026-07-28 se activa explícitamente.

Multi Round-Trip Requests. Una tool puede pedir input al usuario a mitad de llamada, sin mantener un stream abierto — con inputRequired() y acceptedContent(). Confirmaciones y flujos de autorización dejan de ser un apaño.

Cabeceras enrutables Mcp-Method y Mcp-Name, para que gateways y rate limiters enruten sin parsear el body. Si expones MCP detrás de un API gateway, esto te ahorra trabajo.

Bring-your-own-schema. inputSchema y outputSchema aceptan cualquier Standard Schema: Zod v4 y ArkType directos, Valibot vía adaptador, o JSON Schema plano con fromJsonSchema. Se acabó estar atado a Zod. El registro pasa a server.registerTool(name, config, handler).

Si vas a experimentar con la beta, el consejo oficial es fijar versiones exactas y poner cotas superiores en las dependencias, para no comerte un major por sorpresa.

Mi recomendación: construye en v1, lee la guía de v2, y migra cuando tengas un motivo concreto — escalado horizontal o flujos que necesiten input a media llamada. No antes.

---

Cuándo NO necesitas un MCP server

Esta sección te puede ahorrar una semana.

Si tu agente va a usar solo tus propias tools, dentro de tu propio proceso, no montes un MCP server. El Tool Runner con tools locales (betaZodTool y punto) es más simple, más rápido de depurar y no añade un proceso extra ni serialización por medio. Todo el paso 1 de este post sobra en ese escenario.

MCP gana cuando aparece la palabra reutilización:

• Quieres las mismas tools en Claude Code, en Claude Desktop y en tu agente.
• Varios equipos van a consumir la misma capacidad y no quieres que cada uno la reimplemente.
• Quieres una frontera de permisos clara: el server decide qué se puede hacer, el agente solo pide.
• Necesitas versionar y desplegar las capacidades por separado del agente.

Si no marcas ninguna, tu MCP server es una capa de indirección que no compra nada.

Y una consecuencia que se ve poco: en cuanto varios clientes consumen tus tools, las descripciones dejan de ser tuyas y pasan a ser una API pública. Cambiar una description puede romper el comportamiento del agente de otro equipo sin que nada falle en rojo. Trátalas con el mismo cuidado que un contrato.

---

Qué hacer con esto hoy

Coge el código del paso 1, cámbiale el array INCIDENCIAS por una consulta real a tu base de datos, y ejecuta el puente del paso 3. En una tarde tienes un agente hablando con tus datos internos.

Y cuando lo tengas funcionando, la parte difícil no será el código. Será decidir qué tools expones y cómo las describes — porque ahí es donde un agente pasa de demo a herramienta que usas todos los días.

Ese salto, el de convertir una prueba de concepto en producto, es justo lo que trabajamos en el curso Construye con IA: De la Idea al Producto con Claude Code, con este mismo flujo de specs, tools y agentes. Si prefieres el método antes que la herramienta, en el libro Spec-Driven Development está el sistema completo para definir qué construyes antes de escribir la primera línea.

Y si quieres los proyectos completos y las versiones de esto que corren en producción, están en Dominicode Labs.

---

FAQ

¿Puedo usar el mismo MCP server con Claude Code y con mi agente propio a la vez?

Sí, y es exactamente para lo que sirve MCP. El server no sabe quién le llama. Claude Code lo lanza como proceso hijo por stdio, y tu agente hace lo mismo con StdioClientTransport. Mismo binario, dos consumidores, cero código duplicado.

¿Tengo que migrar mi server a la v2 el 28 de julio?

No. La v2 llega en paquetes nuevos (@modelcontextprotocol/server, /client y /core), no como actualización del paquete actual, así que no te va a llegar por un npm update. La v1.x sigue siendo la versión soportada para producción y mantiene bugfixes y parches de seguridad al menos 6 meses tras la salida de v2. Además, hablar la revisión 2026-07-28 es siempre un opt-in explícito: nada la pone en el cable por defecto.

¿Cuál es la diferencia real entre el Tool Runner y el Claude Agent SDK?

El Tool Runner automatiza el bucle sobre tools que defines tú, y nada más: sin tools integradas, sin sandbox. El Claude Agent SDK es Claude Code como librería, y viene con tools de ficheros, bash y grep de serie. Si quieres control total sobre qué puede hacer el agente, Tool Runner. Si quieres un agente que opere sobre un repositorio desde el minuto uno, Agent SDK.

Mi server arranca pero el cliente da error de parseo JSON. ¿Qué pasa?

Casi seguro tienes un console.log en algún sitio. En stdio, stdout es el canal JSON-RPC exclusivo del protocolo. Cualquier texto que escribas ahí corrompe el flujo. Cambia todos los console.log por console.error y vuelve a probar.

¿Por qué mi tool aparece registrada pero el modelo nunca la llama?

Dos causas, por frecuencia. La primera es la description: si es vaga, el modelo no sabe cuándo aplica. Escríbela diciendo explícitamente en qué situación usarla. La segunda es que el schema no describa bien los campos — añade .describe() a cada uno, porque el modelo los lee para saber con qué rellenarlos.

¿Cómo pruebo mi MCP server sin registrarlo en un cliente?

Con MCP Inspector, la herramienta oficial: npx @modelcontextprotocol/inspector npx tsx src/server.ts. Abre una interfaz web donde ves las tools registradas, su schema, y puedes invocarlas con argumentos a mano. Es la forma más rápida de saber si el fallo está en el server o en cómo lo consume el cliente.

¿Puedo usar temperature para que el agente sea más determinista?

No con Opus 4.8. temperature, top_p y top_k rechazan cualquier valor que no sea el por defecto y devuelven un 400. Tampoco existe ya budget_tokens para thinking — se usa thinking: { type: 'adaptive' }. Si migras código de modelos anteriores, revisa esos parámetros primero. El comportamiento se dirige por prompt.

¿El conector MCP de la API sirve para un server local por stdio?

No. mcp_servers con type: 'url' necesita un endpoint HTTP accesible desde la API de Anthropic. Para un server local usas el puente del paso 3: cliente MCP por stdio y las tools traducidas al Tool Runner.

---

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.

Más contenido sobre agentes e IA aplicada al desarrollo en el canal de YouTube de Dominicode. Y si estás empezando con agentes, esta guía es el punto de partida.