Crea tu primer servidor MCP

Cualquier cliente de IA capaz de invocar herramientas —un asistente de escritorio, un IDE, un framework de agentes— necesita una forma de alcanzar tus datos y tus acciones. El camino ingenuo es una integración a medida por cada cliente: un formato de plugin aquí, un esquema de function calling allá, cada uno reescrito cuando aparece el siguiente cliente. El Model Context Protocol reemplaza todo eso con un único contrato, y montar un servidor lleva una tarde. Esta guía recorre el servidor más pequeño que vale la pena ejecutar y luego lo verifica contra un cliente real.

El cambio importante es que escribes la capacidad una sola vez. El mismo servidor que hoy conectas a un cliente de escritorio funciona sin cambios dentro de un entorno de agentes mañana, porque el cliente solo ve el protocolo, nunca tu código.

Requisitos previos

Esta guía asume que ya trabajas con soltura en TypeScript y Node. En concreto necesitarás:

• Node.js 18 o superior y un gestor de paquetes (npm, pnpm o yarn).
• Familiaridad con async/await y con los módulos ES.
• Un cliente MCP para probar. El MCP Inspector oficial se ejecuta con npx sin instalar nada, y un asistente de escritorio sirve como objetivo del mundo real.

No hace falta experiencia previa con MCP. Si alguna vez escribiste un esquema de function calling para un LLM, el modelo mental te resultará familiar: MCP es esa idea, formalizada y hecha portable.

Paso 1 — Prepara el proyecto

Crea un directorio, inicialízalo y declara dos dependencias: el SDK de MCP y Zod, que el SDK usa para describir y validar las entradas de las herramientas.

1
{
2
  "name": "weather-mcp",
3
  "type": "module",
4
  "bin": { "weather-mcp": "build/server.js" },
5
  "dependencies": {
6
    "@modelcontextprotocol/sdk": "^1.0.0",
7
    "zod": "^3.23.8"
8
  },
9
  "devDependencies": {
10
    "typescript": "^5.5.0",
11
    "@types/node": "^22.0.0"
12
  }
13
}

La línea "type": "module" importa: el SDK se distribuye como módulos ES, así que tu proyecto también debe serlo. Ejecuta tu comando de instalación y añade un tsconfig.json mínimo que apunte a ES2022, con "module": "NodeNext" y un outDir igual a build.

Paso 2 — Escribe el servidor

Un servidor hace tres cosas: anuncia quién es, registra sus capacidades y se conecta a un transporte. Aquí están las tres, completas y ejecutables.

1
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3
import { z } from "zod";
4

5
const server = new McpServer({
6
  name: "weather",
7
  version: "1.0.0",
8
});
9

10
// El esquema de Zod es el contrato. El cliente ve los nombres y
11
// tipos de los parámetros, y el SDK valida cada llamada antes de
12
// que tu handler se ejecute: así el handler solo recibe entradas válidas.
13
server.tool(
14
  "get_forecast",
15
  { city: z.string().describe('Nombre de ciudad, p. ej. "Lisboa"') },
16
  async ({ city }) => {
17
    const tempC = 18 + (city.length % 10); // sustituto de una llamada real a una API
18
    return {
19
      content: [{ type: "text", text: `${city}: ${tempC}°C, cielo despejado.` }],
20
    };
21
  },
22
);
23

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

El bloque resaltado es el núcleo del servidor. server.tool recibe un nombre, un esquema y un handler. El nombre y el esquema son los metadatos que el cliente puede descubrir; el handler es tu lógica. La forma del retorno —un arreglo content de partes tipadas— es cómo responde toda herramienta, ya devuelva texto, una imagen o datos estructurados.

Las dos últimas líneas conectan el servidor a stdio: lee peticiones JSON-RPC de la entrada estándar y escribe respuestas en la salida estándar. Esa decisión tiene una consecuencia que conviene decir en voz alta.

Paso 3 — Verifícalo de principio a fin

Compila el TypeScript y luego apunta el MCP Inspector al punto de entrada compilado. El Inspector es un cliente pequeño que te deja enumerar e invocar herramientas a mano: la forma más rápida de confirmar que el servidor realmente habla el protocolo.

1
npx tsc
2
npx @modelcontextprotocol/inspector node build/server.js

El Inspector abre una interfaz local. En Tools deberías ver get_forecast con su parámetro city. Invócala con el nombre de una ciudad y confirma que vuelve la respuesta de texto. Si la herramienta aparece y responde, tu servidor es correcto: un cliente descubrió su capacidad y la invocó, que es el contrato completo.

Cuando el Inspector esté conforme, conectar un asistente real es solo configuración. Un cliente de escritorio lee un archivo JSON que lista los servidores a lanzar:

1
{
2
  "mcpServers": {
3
    "weather": {
4
      "command": "node",
5
      "args": ["/ruta/absoluta/a/build/server.js"]
6
    }
7
  }
8
}

Usa una ruta absoluta: el cliente lanza el proceso desde su propio directorio de trabajo, no desde el tuyo. Reinicia el cliente y la herramienta get_forecast queda disponible en la conversación.

Compensaciones y qué explorar después

El transporte stdio que usamos aquí es ideal para herramientas locales de un solo usuario: el cliente gestiona el ciclo de vida del proceso y no hay superficie de red que asegurar. Cuando necesites un servidor al que muchos clientes lleguen por la red, cambia al transporte HTTP en streaming: el código de la capacidad es idéntico; solo cambia el transporte al final del archivo. No recurras a HTTP hasta que de verdad tengas un consumidor remoto; el modelo de proceso local es más simple y más seguro por defecto.

A partir de aquí, los siguientes pasos naturales son las dos capacidades que omitimos. Los recursos exponen datos de solo lectura (archivos, registros, documentos) que un cliente puede traer al contexto. Los prompts exponen plantillas reutilizables que el usuario invoca por nombre. Ambos se registran con la misma forma que ya usaste para la herramienta, así que añadirlos es más de lo mismo y no algo nuevo.

Ideas clave

• MCP te deja describir una capacidad una vez y que cualquier cliente compatible la descubra e invoque, sin integraciones por cliente.
• Un servidor mínimo son tres movimientos: anúnciate, registra una herramienta con un esquema tipado y conecta un transporte.
• El esquema de Zod es el contrato: el cliente lo lee y el SDK valida cada llamada, de modo que tu handler solo ve entradas válidas.
• En stdio, stdout es el cable del protocolo; registra en stderr y usa una ruta absoluta cuando un cliente lance tu servidor.
• Pasa al transporte HTTP solo cuando tengas un consumidor remoto genuino; mantén las herramientas locales en stdio.

Ahora tienes un servidor que un cliente de IA real puede encontrar, entender y usar. Todo lo más grande —bases de datos, APIs internas, kits completos de herramientas para agentes— son los mismos tres movimientos repetidos, una herramienta a la vez.