Un servidor MCP ofrece herramientas con entradas claramente descritas a una aplicación de IA. Para empezar basta una función local. Pasa a una interfaz remota cuando la herramienta y el cliente funcionen juntos.
La guía sigue la versión 2 estable del SDK oficial de TypeScript y la revisión del protocolo 2026-07-28, con datos de 30 de septiembre de 2026. Los tutoriales con @modelcontextprotocol/sdk y transportes con sesiones corresponden al SDK v1. No mezcles las dos API.
Crear el proyecto con Node.js 20 o posterior#
mkdir mein-mcp-server
cd mein-mcp-server
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/server@2 zod@4 tsx
mkdir src
type=module es necesario porque el SDK utiliza módulos ES. Aquí tsx ejecuta TypeScript directamente: no hay compilación con tsc ni una supuesta dist/index.js. Para distribuir JavaScript necesitas además una configuración de compilación; tsc --init por sí solo no establece esa ruta de salida.
Registrar una herramienta#
Guarda el siguiente código en src/index.ts:
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";
serveStdio(() => {
const server = new McpServer({ name: "mein-server", version: "1.0.0" });
server.registerTool(
"add_numbers",
{
description: "Add two numbers and return their sum",
inputSchema: z.object({ a: z.number(), b: z.number() })
},
async ({ a, b }) => ({
content: [{ type: "text", text: String(a + b) }]
})
);
return server;
});
El esquema valida los dos números. La descripción explica al asistente cuándo utilizar la herramienta. serveStdio gestiona la comunicación por los flujos estándar del proceso. Arranca con npx tsx src/index.ts; es normal que espere entradas sin imprimir un mensaje de bienvenida.
Conectar un cliente local#
La configuración local de Claude Desktop está en ~/Library/Application Support/Claude/claude_desktop_config.json en macOS y %APPDATA%\Claude\claude_desktop_config.json en Windows. Utiliza rutas absolutas al ejecutable instalado de tsx y a tu archivo:
{
"mcpServers": {
"mein-server": {
"command": "/absolute/path/to/node_modules/.bin/tsx",
"args": ["/absolute/path/to/mein-mcp-server/src/index.ts"]
}
}
}
En Windows adapta también la ruta del ejecutable. Reinicia el cliente y comprueba que aparece add_numbers. Pide al asistente que sume dos números con esa herramienta y verifica el resultado y la llamada real.
En Claude Code puedes registrar el mismo proceso local:
claude mcp add mein-server -- /absolute/path/to/node_modules/.bin/tsx /absolute/path/to/mein-mcp-server/src/index.ts
Antes de utilizarlo en producción#
Con stdio no imprimas depuración en stdout: ese flujo solo debe contener mensajes del protocolo. Envía los registros locales a stderr. Limita entradas, trata los errores esperables de forma comprensible y devuelve los errores de herramienta adecuadamente. Los servicios externos necesitan tiempos límite y, cuando corresponda, límites de llamadas.
La suma no depende de servicios externos ni modifica datos. Si una herramienta escribe archivos o llama a una API externa, necesita permisos reales, gestión de secretos y comprobaciones de efectos secundarios. El transporte local no garantiza que el servidor no envíe datos a la red.
Publicarlo por HTTP#
Sigue la documentación HTTP del SDK v2 y una integración completa para tu entorno, en lugar de copiar un ejemplo antiguo con sesiones. La revisión 2026-07-28 utiliza metadatos por petición; las sesiones del protocolo y el flujo GET separado no forman parte de esa revisión.
Comprueba la validación de origen, autenticación y permisos. Las pruebas HTTP locales deberían escuchar solo en localhost. Un endpoint accesible no basta para una integración segura en producción. Comprueba también qué revisión soporta el cliente previsto.
Fuentes: inicio del SDK v2, transportes MCP, stdio, stdio frente a HTTP.
