MCP vs API: un servicio de pedidos, dos interfaces

Repositorio complementario para el vídeo "MCP vs API: ¿por qué necesitamos MCP si REST ya funciona?"

Clónalo, ejecuta dos comandos y haz el mismo trabajo dos veces. Una vez con una API REST simple. Otra con un servidor MCP encima. Tarda unos 20 minutos.

Qué estamos construyendo

Tienes una pequeña tienda online. Llegan pedidos. Algunos se quedan atascados y nunca se envían. Quieres que un agente de IA encuentre los atascados y abra un issue de GitHub para cada uno.

Ese es todo el ejemplo. Un trabajo pequeño y real.

La primera forma, le das al agente la documentación de tu API y lo dejas usar curl. Tiene que averiguar qué endpoint llamar, construir un filtro de fecha para "más de 7 días", darse cuenta de que la respuesta viene paginada, y convertir céntimos a dólares.

La segunda forma, le das una herramienta llamada find_stale_orders que recibe { older_than_days: 7 }.

Ambas llaman al mismo endpoint, GET /orders. La tienda no cambia en absoluto. Lo que cambia es quién hace el razonamiento: el agente, o tu servidor.

                        ┌──────────────────────────────────┐
  Web frontend  ───────▶│                                  │
  Mobile app    ───────▶│   Orders service (Express)       │
  Microservice  ───────▶│   GET  /orders                   │
                        │   GET  /orders/:id               │
                        │   PATCH /orders/:id              │
                        └──────────────▲───────────────────┘
                                       │  plain HTTP, nothing AI specific
                        ┌──────────────┴───────────────────┐
  Claude Code   ───────▶│   Orders MCP server              │
  Cursor        ───────▶│   tool: find_stale_orders        │
  Codex         ───────▶│   input: { older_than_days: 7 }  │
                        └──────────────────────────────────┘

Tu API es la puerta. MCP da a los clientes de IA un tirador estándar para abrirla.

El servicio de pedidos nunca sabe que Claude Code existe. El servidor MCP es solo otro cliente HTTP de tu API. La única diferencia es que se describe a sí mismo de una forma que los agentes entienden.

Related MCP server: OHMS

Pruébalo en un minuto

Necesitas Node 20 o superior. Nada más. Sin base de datos, sin claves de API.

git clone https://github.com/bytemonk-academy/mcp-vs-api.git
cd mcp-vs-api
npm install
npm test

npm test ejecuta 31 tests contra la API REST y el servidor MCP. Si pasan, todo funciona y el resto es solo verlo ocurrir.

Ahora arranca el servicio y déjalo corriendo:

npm run api

En una segunda terminal, mira los datos:

npm run orders

  ID         CUSTOMER             STATUS      PLACED       DAYS  TOTAL
  ----------------------------------------------------------------------
  ORD-1001   Ada Lovelace         UNSHIPPED   2026-07-27   31    $129.00
  ORD-1002   Grace Hopper         UNSHIPPED   2026-08-03   24    $45.99
  ...

  Showing 20 of 24 matching orders.

  !! There are more. page.nextOffset = 20
     You have NOT seen all 24 orders.

Luego hazle la pregunta sobre la que trata toda esta demo:

npm run orders -- --stale=7

Ocho pedidos. Los mismos ocho en cualquier máquina, a cualquier hora del día.

Qué es npm run orders

Es un atajo para curl.

Envía GET /orders a tu API e imprime la respuesta como tabla en lugar de JSON crudo. Eso es todo lo que hace. Puedes ejecutar la misma petición tú mismo:

curl "http://localhost:3000/orders"

Obtienes los mismos datos, solo que más difíciles de leer. El script está ahí solo para que puedas comprobar los datos rápidamente. No forma parte de la lección. En la Fase 1 el agente recibe curl y la documentación, nada más.

Acepta algunas opciones:

npm run orders -- --stale=7             # unshipped for more than 7 days
npm run orders -- --status=UNSHIPPED    # filter by status
npm run orders -- --limit=5 --offset=5  # move through the pages by hand

Por qué los datos de prueba tienen este aspecto

Hay 24 pedidos, guardados en memoria, con fechas relativas a hoy. Así que siempre hay exactamente 8 pedidos obsoletos, cuando clonas esto.

Hay tres problemas puestos a propósito, para que puedas ver la diferencia por ti mismo en lugar de creerte la palabra del vídeo:

• La respuesta viene paginada. Pides pedidos y obtienes 20 de 24. Nada en esas 20 filas parece incompleto. Un agente que se detiene en la primera página da una respuesta incorrecta y suena seguro de sí mismo.

• Algunos pedidos antiguos están cancelados. Parecen obsoletos pero no lo están. Si filtras por shippedAt en lugar de status, los cuentas por error.

• Algunos pedidos están justo por debajo de la línea de 7 días. Cuenta los días ligeramente mal y obtienes un total incorrecto, no un mensaje de error.

El servidor MCP se ocupa de los tres en código, una vez, en src/mcp/server.ts. En la versión con curl, el agente tiene que acertar los tres cada vez.

El ejercicio

Hazlos en orden. La Fase 1 antes de la Fase 2 es el punto, porque la diferencia es la lección.

También aquí: la referencia de la API que le das al agente en la Fase 1, prompts que puedes copiar, y solución de problemas.

La Fase 2 abre issues reales de GitHub, así que usa un repositorio de prueba que no te importe llenar.

Qué hay aquí dentro

src/
  data/orders.ts     The 24 test orders
  api/app.ts         The REST API. Knows nothing about MCP.
  api/server.ts      Starts it on a port.
  mcp/server.ts      The MCP server. Calls the REST API over HTTP.
scripts/orders.ts    The table viewer used above
clients/             Plain MCP clients, in Python and TypeScript
tests/               Tests for both halves
docs/                The walkthrough
.mcp.json            Claude Code reads this automatically
.cursor/mcp.json     Cursor reads this automatically

Tres herramientas. Cada una es un envoltorio fino sobre un endpoint que ya tienes:

src/mcp/server.ts tiene unas 170 líneas y la mayor parte son comentarios. Eso es todo lo que es realmente un servidor MCP.

Ver el protocolo por ti mismo

Claude Code no hace nada especial aquí. Arranca el servidor como subproceso y envía mensajes JSON-RPC por stdin y stdout. clients/raw_mcp_client.py hace lo mismo a mano:

async with stdio_client(server) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("find_stale_orders", {"older_than_days": 7})

El mismo script luego habla con el servidor MCP de GitHub por HTTP para abrir los issues:

await session.call_tool("create_issue", {"owner": owner, "repo": name, "title": ...})

La misma forma en ambos casos. Un servidor es un proceso de Node en tu portátil. El otro lo ejecuta GitHub. El cliente no puede distinguirlos. Esa es la parte que merece la pena recordar. Hay una versión en TypeScript en clients/ si prefieres quedarte en un solo lenguaje.

Tests

npm test

31 tests. Los de MCP manejan un cliente MCP real por stdio, igual que hace Claude Code.

Merece la pena leerlos si planeas escribir tu propio servidor. Muestran lo que realmente vale la pena comprobar: que cada herramienta tiene una descripción y un esquema utilizables, que la paginación funciona de verdad, que un 404 vuelve como error de herramienta en lugar de un fallo, y que los pedidos cancelados se mantienen fuera de los resultados.

Comandos

npm run api        # REST API on :3000
npm run api:dev    # same, restarts when you edit a file
npm run orders     # print the orders as a table
npm run mcp        # run the MCP server directly (agents usually do this for you)
npm test           # the tests
npm run typecheck  # tsc --noEmit
npm run inspect    # MCP Inspector, to try the tools by hand

npm run inspect es la forma más rápida de ver exactamente lo que ve un agente: nombres de herramientas, descripciones y el esquema de entrada de cada una.

Los datos se guardan en memoria, así que reiniciar npm run api lo devuelve todo al principio.

¿Cuándo merece la pena MCP?

La Fase 1 funciona. Eso no es un truco. Un buen agente encontrará los pedidos obsoletos y abrirá los issues usando nada más que curl y tu documentación. MCP no es lo que hace posible el trabajo.

Lo que cambia es la forma de la integración. Cómo consultar tu servicio de pedidos ahora vive en un servidor, en lugar de en la ventana de contexto de cada agente. La misma capacidad funciona en Claude Code, Cursor y Codex sin escribir una integración nueva para cada uno. Y tú eliges qué capacidades exponer, lo cual es muy diferente de entregar una clave de API.

Lo que no cambia: autenticación, autorización, validación, límite de tasa, reintentos y un buen diseño de servicio siguen siendo tu trabajo. Un servidor MCP sobre una API mal diseñada sigue siendo una API mal diseñada.

A grandes rasgos, el valor crece con el número de clientes multiplicado por el número de herramientas. ¿Un agente llamando a dos funciones que controlas? Sáltatelo, simplemente llama a las funciones. ¿Treinta herramientas en cinco equipos y cuatro clientes? Ahí es cuando un protocolo compartido empieza a amortizarse. docs/architecture.md cubre dónde está la línea.

Licencia MIT. Úsalo en tu propia enseñanza, sin necesidad de crédito.