🔌 Tu primer puente MCP

En el módulo 2.1, Claude llamaba a un script. Funciona, pero el agente necesita saber el nombre del archivo y armar el comando. Con MCP es diferente: el agente recibe una lista de herramientas listas para usar, cada una con nombre, descripción y campos.

R3 combina dos peldaños de la escalera. La lectura del archivo es una puente local (nivel 6). La forma de entregárselo al agente es MCP (nivel 2). El resultado: un sistema sin API empieza a parecer, para el agente, un sistema con herramientas oficiales.

Cómo leer el diagrama: a la izquierda, quien hace la solicitud; en el medio, el puente, que conoce las reglas; a la derecha, los archivos. Las flechas discontinuas hacia los archivos son solo de lectura: el puente nunca escribe en ellos.

El modelo está en runtime/pontes/mcp-modelo/server.mjs. Es un servidor MCP sin dependencias: no necesitas instalar ningún paquete, solo tener Node.

Incluye dos herramientas de ejemplo, una para cada personaje del curso. La descripción de cada una es lo que el agente lee para decidir cuándo usarla.

Qué revisar en la tabla: los campos son opcionales. Sin data, la primera lista todos los horarios disponibles; sin agrupar_por, la segunda agrupa por cliente.

data,hora,profissional,status,paciente
2026-10-06,08:00,Dra. Ana,ocupado,Paciente 01
2026-10-06,09:00,Dra. Ana,livre,
2026-10-06,10:00,Dra. Ana,livre,
2026-10-06,14:00,Dr. Bruno,ocupado,Paciente 02
2026-10-06,15:00,Dr. Bruno,livre,
2026-10-07,08:00,Dra. Ana,livre,
2026-10-07,09:00,Dra. Ana,ocupado,Paciente 03
2026-10-07,16:00,Dr. Bruno,livre,

La misma regla del módulo 2.1: primero sin agente. El servidor tiene un modo de autoprueba, --selftest. Enumera las herramientas, llama a cada una con datos de ejemplo e imprime el resultado.

No consume ninguna cuota: ningún modelo de IA participa en esta prueba. Solo es Node leyendo los CSV.

node runtime/pontes/mcp-modelo/server.mjs --selftest

tools: 2 (listar_horarios_livres, resumo_vendas)
2026-10-06 09:00 · Dra. Ana
2026-10-06 10:00 · Dra. Ana
2026-10-06 15:00 · Dr. Bruno
TOTAL: R$ 856.00

Los tres horarios coinciden con las líneas livre del 06/10 que viste en el tema anterior. Falta comprobar el total de Sônia. La autoprueba muestra solo la última línea del resumen; la tabla de abajo vuelve a hacer la cuenta a mano, línea por línea del erp-vendas.csv.

Qué revisar en la tabla: la cuenta hecha a mano llega al mismo TOTAL: R$ 856.00 del puente (el punto en lugar de la coma es solo el formato del programa).

En el kit, esta parte ya está lista. Dos archivos se encargan de ella: el .mcp.json, en la raíz, registra el puente; el .claude/settings.json libera su uso.

Cuando abres claude en la carpeta, lee el .mcp.json y enciende el servidor automáticamente. No necesitas dejar nada en ejecución.

{
  "mcpServers": {
    "ponte-modelo": {
      "command": "node",
      "args": ["runtime/pontes/mcp-modelo/server.mjs"]
    }
  }
}

"enabledMcpjsonServers": [
  "ponte-modelo"
]

claude mcp list

ponte-modelo: node runtime/pontes/mcp-modelo/server.mjs - ✔ Connected

Ahora entra el agente. El comando de abajo usa claude -p: envía una sola solicitud, sin abrir la pantalla, e imprime la respuesta. Pide los horarios del 07/10, un día distinto al de la prueba automática.

Cambiar el día es intencional. Si el agente responde correctamente sobre un día que no probaste, es señal de que llamó a la herramienta y no repitió algo que ya había visto.

claude -p "Use a tool listar_horarios_livres da ponte-modelo e diga os horários livres de 2026-10-07."

Cómo leer el diagrama: la caja con brillo es el único punto en el que la IA decide algo: qué herramienta llamar y con qué fecha. El filtro del paso 3 es código, no una suposición.

Sonia hace lo mismo con la otra herramienta. Con claude abierto en la carpeta del kit, pide: "Usa la herramienta resumo_vendas del ponte-modelo agrupando por cliente y dime quién compró más." La respuesta tiene que coincidir con la tabla del tema 3: Mercado Sol va a la cabeza, con R$ 393,00.

Codex no lee el .mcp.json. Tiene su propio registro, creado con un comando. El puente es el mismo: ninguna línea del server.mjs cambia.

Fíjate en "$PWD/…": la receta registra en Codex la ruta completa del servidor, empezando desde la raíz del disco, y no la ruta corta que el .mcp.json usa. Así, el registro no depende de dónde se abrió Codex.

codex mcp add ponte-modelo -- node "$PWD/runtime/pontes/mcp-modelo/server.mjs"

Qué revisar en la tabla: solo cambia la forma de registrarlo. Por eso MCP vale la pena: escribes el puente una vez y cualquier agente que hable MCP lo usa.