Cómo crear un servidor MCP en TypeScript desde cero

En este tutorial vamos crear un servidor pequeño en TypeScript, anunciar una herramienta llamada somar y probarla con un cliente MCP local. El ejemplo no accede a archivos, red ni cuentas externas, así que es un comienzo seguro para entender el ciclo completo.

En este artículo vas a ver:

• El rol de un MCP server
• Cómo crear una herramienta en TypeScript
• Cómo probar la conexión local
• Cómo conectar el servidor a un host

Qué es un MCP server y dónde encaja

MCP significa Model Context Protocol, un protocolo abierto para conectar aplicaciones de IA a herramientas y fuentes de contexto. El host es la aplicación que la persona usa, como un asistente o editor. Crea un cliente MCP, que se comunica con el servidor responsable de exponer recursos y herramientas.

El diagrama oficial de la arquitectura MCP muestra esta separación. Tu servidor no es, por sí mismo, un agente que decide qué hacer. Publica capacidades descritas para que un host compatible pueda descubrirlas y llamarlas.

Esto ayuda a mantener la integración organizada. Un servicio puede exponer una búsqueda, otro puede consultar tareas y otro puede leer datos autorizados. El host decide cuándo llamar a cada herramienta según la conversación y los permisos disponibles.

Antes de crear un MCP server en TypeScript

Necesitas Node.js 20 o superior y un proyecto TypeScript ejecutado con tsx. El 27 de octubre de 2026, las versiones actuales del SDK MCP para servidor y cliente eran 2.4.0, y el paquete declara compatibilidad con Node.js a partir de la versión 20.

El ejemplo usa Zod para validar los argumentos recibidos. Esta validación evita aceptar valores fuera del contrato esperado y deja la descripción de los parámetros disponible para el cliente MCP.

Crea un directorio e inicializa el paquete. Luego usa esta package.json como base y ejecuta npm install:

{
  "name": "mcp-server-demo",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "tsx src/server.ts",
    "test": "tsx src/client.ts"
  },
  "dependencies": {
    "@modelcontextprotocol/client": "2.4.0",
    "@modelcontextprotocol/server": "2.4.0",
    "zod": "4.2.0"
  },
  "devDependencies": {
    "tsx": "4.23.15"
  }
}

El type activa los módulos ES en Node.js. Los scripts llaman al servidor y al cliente sin requerir una etapa separada de compilación. La documentación actual del SDK TypeScript del Model Context Protocol reúne ejemplos y notas de migración de la versión 2.

Paso 1: prepara el proyecto del MCP server

Crea src/server.ts y registra una herramienta con dos números de entrada. El servidor usa transporte STDIO, en el que los mensajes del protocolo pasan por el flujo estándar del proceso local.

import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod/v4";

serveStdio(() => {
  const server = new McpServer({ name: "servidor-mcp-demo", version: "1.0.0" });

  server.registerTool(
    "somar",
    {
      description: "Soma dois números e devolve o resultado.",
      inputSchema: z.object({
        a: z.number().describe("Primeiro número"),
        b: z.number().describe("Segundo número")
      })
    },
    async ({ a, b }) => ({
      content: [{ type: "text", text: String(a + b) }]
    })
  );

  return server;
});

McpServer organiza las capacidades publicadas por el proceso. registerTool define el nombre, la descripción, el esquema de entrada y la función que se ejecutará. La función devuelve un bloque de texto en el formato esperado por el protocolo.

La herramienta de ejemplo solo calcula la suma. En una aplicación real, reemplaza esa lógica por una tarea delimitada, como consultar un pedido o buscar información interna. Comienza con lectura y mantén las operaciones que alteran datos fuera del primer prototipo.

Paso 2: registrar la herramienta sumar

Para confirmar que el servidor responde, crea src/client.ts. Ese cliente inicia el proceso por el transporte STDIO, lista las herramientas publicadas y llama a somar con los valores 2 y 3.

import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";

const client = new Client({ name: "mcp-server-test", version: "1.0.0" });
const transport = new StdioClientTransport({
  command: process.execPath,
  args: ["--import", "tsx", "src/server.ts"]
});

try {
  await client.connect(transport);
  const { tools } = await client.listTools();
  console.log(`tools=${tools.map((tool) => tool.name).join(",")}`);
  const result = await client.callTool({ name: "somar", arguments: { a: 2, b: 3 } });
  console.log(`result=${result.content.map((part) => part.type === "text" ? part.text : "").join("")}`);
} finally {
  await client.close();
}

Ejecuta npm test. El resultado esperado en este ejemplo es tools=somar y result=5. El listado confirma que el cliente descubrió la herramienta; la segunda línea confirma que el servidor procesó la llamada y devolvió el contenido.

Si el proceso se cierra sin respuesta, revisa primero si el directorio contiene src/server.ts y src/client.ts, si los paquetes están instalados y si Node.js cumple con el requisito mínimo. Los mensajes de diagnóstico deben ir a stderr, no a stdout, porque el transporte STDIO reserva el flujo estándar para el protocolo.

Cómo conectar el MCP server a un host

Después de la prueba local, registra el proceso en un host compatible con MCP. Cada aplicación tiene su propio formato de configuración y política de aprobación, así que sigue la documentación específica del host en lugar de copiar un ejemplo de otro editor.

En la guía para configurar MCP en VS Code, ve cómo agregar un servidor al cliente. Para entender un caso de herramienta MCP orientada a agentes, lee también sobre el Retrieve de Work IQ.

Antes de compartir el servidor, define qué datos puede leer, quién puede llamarlo y qué acciones requieren confirmación. No coloques tokens ni contraseñas en el código, en los argumentos de la herramienta ni en mensajes de log. Si una herramienta modifica archivos, envía mensajes o activa pagos, limita el alcance y prueba la confirmación humana.

Mantén las descripciones cortas y específicas. Una herramienta llamada somar con entradas a y b comunica mejor su intención que una herramienta genérica llamada executar. Para cada herramienta, indica qué hace, qué argumentos acepta y qué ocurre en caso de error.