Cómo crear un servidor MCP en TypeScript paso a paso

Crear un servidor MCP es más sencillo de lo que parece: con el SDK oficial de TypeScript necesitas un archivo, un par de dependencias y unas 30 líneas de código para tener una herramienta que Claude o Cursor pueden invocar. En esta guía construimos uno desde cero, lo probamos con el MCP Inspector y lo conectamos a tus editores. Todo el código está completo y funciona tal cual.
Si todavía no tienes claro qué es MCP, lo expliqué a fondo en el post de Context7, el servidor MCP de documentación. En resumen: el Model Context Protocol es un estándar abierto que estandariza cómo un asistente de IA se conecta a herramientas y fuentes de datos externas. Un servidor MCP es justo eso: un proceso que expone capacidades (tools, resources, prompts) que el modelo puede usar.
Aquí nos centramos en tools, que es el 90% de los casos de uso: funciones que el modelo llama con argumentos y que devuelven un resultado.
Qué vas a necesitar
- Node.js 22.19 o superior (lo verificas con
node --version). El SDK pide Node 20, pero el MCP Inspector que usamos en el paso 3 exige>=22.19.0. - Un editor (Cursor, VS Code, lo que uses).
- Claude Code o Cursor para la conexión final (opcional, pero es lo divertido).
No necesitas ninguna API key ni cuenta de pago. El servidor corre en tu máquina.
Paso 1: Inicializa el proyecto
Crea la carpeta e instala las dependencias. Usamos el paquete de servidor del SDK oficial (@modelcontextprotocol/server, la versión 2 del SDK) y zod para validar los argumentos de entrada:
mkdir mi-servidor-mcp && cd mi-servidor-mcp
npm init -y
npm install @modelcontextprotocol/server zod
npm install -D typescript @types/node¿Vienes del SDK v1? El paquete anterior,
@modelcontextprotocol/sdk, sigue en la rama v1.x y recibe correcciones de seguridad durante al menos seis meses desde que salió la v2 (27 de julio de 2026). Un servidor v1 conStdioServerTransportsigue funcionando, pero solo atiende a clientes que abren con el handshakeinitializede la era 2025. Para algo nuevo, usa la v2 como en esta guía.
El SDK habla MCP por ti (el protocolo JSON-RPC, la negociación de versión y de capacidades). Tú solo escribes la lógica de tus tools.
Edita el package.json para que use módulos ES y tenga un script de build:
{
"name": "mi-servidor-mcp",
"version": "1.0.0",
"type": "module",
"bin": {
"mi-servidor-mcp": "./build/index.js"
},
"scripts": {
"build": "tsc"
},
"dependencies": {
"@modelcontextprotocol/server": "^2.3.0",
"zod": "^4.2.0"
},
"devDependencies": {
"@types/node": "^22.0.0",
"typescript": "^5.6.0"
}
}
"type": "module"le dice a Node, y a TypeScript con"module": "Node16", que el proyecto usa módulos ES. Es la misma configuración que el tutorial oficial de MCP.
Crea un tsconfig.json:
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./build",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"types": ["node"]
},
"include": [
"src/**/*.ts"
]
}Paso 2: Escribe el servidor (tu primer tool)
Crea src/index.ts. Empezamos con un tool mínimo para entender la forma: una calculadora que suma dos números.
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";
// 1. Una función que crea el servidor y registra sus tools
function createServer() {
const server = new McpServer({
name: "mi-servidor-mcp",
version: "1.0.0",
});
// 2. Registra un tool
server.registerTool(
"calcular",
{
description: "Suma dos números y devuelve el resultado",
inputSchema: z.object({
a: z.number().describe("Primer número"),
b: z.number().describe("Segundo número"),
}),
},
async ({ a, b }) => ({
content: [{ type: "text", text: `El resultado es ${a + b}` }],
})
);
return server;
}
// 3. Sirve el servidor por stdio
serveStdio(createServer, {
onerror: (error) => console.error("Error del servidor MCP:", error),
});
console.error("Servidor MCP en marcha (stdio)");El código tiene tres piezas:
McpServeres la API de alto nivel. Le das un nombre y una versión.registerToolrecibe el nombre del tool, sus metadatos (description+inputSchema) y el handler. ElinputSchemaes unz.object(...): el SDK acepta cualquier esquema compatible con Standard Schema (Zod 4, Valibot, ArkType) y lo convierte a JSON Schema para que el modelo sepa qué argumentos pasar. Los.describe()ayudan al modelo a usar el tool correctamente.serveStdiocomunica el servidor con el cliente vía stdin/stdout, el transporte para integraciones locales: el editor lanza tu servidor como proceso hijo y hablan por esa tubería. Además negocia la versión del protocolo con cada cliente, así que el mismo servidor responde a clientes de la revisión 2026-07-28 y a los que todavía usan el handshake de 2025. Por eso recibe una función y no un servidor ya creado: llama acreateServer()cada vez que necesita una instancia nueva.
Regla de oro del stdio: nunca uses
console.logen un servidor stdio. Stdout es el canal del protocolo; si escribes ahí corrompes los mensajes. Para logs usa siempreconsole.error(va a stderr).
Compílalo:
npm run buildEsto genera build/index.js. Ya tienes un servidor MCP funcional.
Paso 3: Pruébalo con el MCP Inspector
Antes de conectarlo a nada, pruébalo de forma aislada. El MCP Inspector es una herramienta oficial que levanta una UI web para invocar tus tools a mano:
npx @modelcontextprotocol/inspector node build/index.jsAbre la URL que imprime en consola, verás tu servidor conectado. En la pestaña Tools aparece calcular: pulsa List Tools, selecciona el tool, introduce a y b, y ejecuta. Si devuelve "El resultado es...", todo funciona.
Este paso te ahorra horas: si algo falla, lo ves aquí sin el ruido de un editor de por medio.
Si quieres confirmar que responde a clientes de la revisión 2026-07-28, el Inspector también tiene modo línea de comandos:
npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era modern --method tools/listPaso 4: Un tool que sirve de verdad
Sumar números no impresiona a nadie. La gracia de MCP es darle al modelo acceso a datos que no tiene. Añadamos un tool que consulta la API pública de GitHub y devuelve las estrellas y el lenguaje de un repositorio. Agrégalo en src/index.ts, dentro de createServer() y antes del return server:
server.registerTool(
"info_repo",
{
description:
"Obtiene estrellas, lenguaje y descripción de un repositorio público de GitHub",
inputSchema: z.object({
owner: z.string().describe("Usuario u organización dueña del repo"),
repo: z.string().describe("Nombre del repositorio"),
}),
},
async ({ owner, repo }) => {
const res = await fetch(`https://api.github.com/repos/${owner}/${repo}`, {
headers: { "User-Agent": "mi-servidor-mcp" },
});
if (!res.ok) {
return {
content: [
{ type: "text", text: `No encontré ${owner}/${repo} (HTTP ${res.status}).` },
],
isError: true,
};
}
const data = await res.json();
const resumen = [
`Repositorio: ${data.full_name}`,
`Descripción: ${data.description ?? "—"}`,
`Lenguaje: ${data.language ?? "—"}`,
`Estrellas: ${data.stargazers_count}`,
`Forks: ${data.forks_count}`,
].join("\n");
return { content: [{ type: "text", text: resumen }] };
}
);Dos detalles importantes:
- Manejo de errores con
isError: true. Cuando algo sale mal, devuelve el error dentro delcontenty marcaisError. Así el modelo entiende que falló y puede reaccionar (reintentar, avisarte), en vez de recibir una excepción opaca. - Devuelve texto claro y estructurado. El modelo lee la respuesta como contexto; cuanto más legible, mejor la usa.
Recompila (npm run build) y vuelve a probar info_repo en el Inspector con, por ejemplo, owner: upstash y repo: context7.
Paso 5: Conéctalo a Claude Code
La forma más limpia de registrar el servidor en Claude Code es con el comando claude mcp add. No tienes que editar JSON a mano: el comando escribe la configuración por ti en ~/.claude.json (el archivo de config en tu directorio home).
Para un servidor stdio local, pasa el comando que lo lanza después de --. Usa la ruta absoluta al build/index.js:
claude mcp add mi-servidor --scope user -- node /ruta/absoluta/a/mi-servidor-mcp/build/index.jsUn par de detalles:
- Todo lo que va después de
--es el comando que ejecuta tu servidor (node build/index.js); lo de antes son opciones de Claude. --scope userguarda el servidor en~/.claude.jsony lo deja disponible en todos tus proyectos. Sin ese flag se usa el scopelocal(por defecto), que también vive en~/.claude.jsonpero solo se carga en el proyecto actual.
Verifica que quedó registrado:
claude mcp listDentro de una sesión de Claude Code, el comando /mcp te muestra los servidores conectados y sus tools. Pídele algo como "usa info_repo para ver cuántas estrellas tiene upstash/context7" y llamará a tu servidor.
Paso 6: Conéctalo a Claude Desktop
Claude Desktop tiene dos vías. Para un servidor que acabas de programar, lo más directo es editar su configuración desde la propia app (no busques el archivo a mano):
- Abre el menú Claude en la barra de menús del sistema (no los ajustes de dentro de la ventana) y elige Settings….
- Ve a la pestaña Developer y pulsa Edit Config. Eso crea (o abre) el archivo
claude_desktop_config.json:- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
- Añade tu servidor dentro de
mcpServers, con la ruta absoluta albuild/index.js:
{
"mcpServers": {
"mi-servidor": {
"command": "node",
"args": [
"/ruta/absoluta/a/mi-servidor-mcp/build/index.js"
]
}
}
}Guarda y reinicia Claude Desktop por completo (ciérralo del todo, no solo la ventana). Al reabrirlo, según la guía oficial de MCP para servidores locales, pulsa el botón "Add files, connectors, and more" en la esquina inferior izquierda del cuadro de mensaje y entra en Connectors para ver tu servidor y sus tools.
Si en vez de un servidor propio quieres instalar uno ya empaquetado, Claude Desktop también soporta Desktop Extensions (archivos
.mcpb) desde Settings → Extensions, sin tocar JSON.
Paso 7: Conéctalo a Cursor
Cursor usa el mismo formato que Claude Desktop. Crea .cursor/mcp.json en tu proyecto (o ~/.cursor/mcp.json para que esté disponible en todos):
{
"mcpServers": {
"mi-servidor": {
"command": "node",
"args": [
"/ruta/absoluta/a/mi-servidor-mcp/build/index.js"
]
}
}
}Lo verás listado en la página Customize de la barra lateral, desde donde Cursor gestiona los servidores MCP. A partir de ahí, el agente de Cursor puede invocar tus tools dentro del chat.
Próximos pasos
Ya tienes la base. Desde aquí puedes:
- Añadir más tools repitiendo el patrón de
registerTool. Cada uno es una capacidad nueva. - Exponer resources (datos de solo lectura que el modelo puede leer, como archivos o registros) y prompts (plantillas reutilizables).
- Pasar a transporte HTTP si quieres un servidor remoto en vez de local: el SDK v2 lo trae en paquetes aparte, como
@modelcontextprotocol/nodeo los helpers para Express, Fastify y Hono. - Empaquetarlo y compartirlo. Si ya trabajas con skills, te interesa cómo crear un plugin para Claude Code, que incluye conectar un MCP remoto por OAuth.
Y si lo que buscas es no escribir tools de documentación tú mismo, Context7 ya es un servidor MCP listo que inyecta docs actualizadas de cada librería.
Todo lo que he escrito sobre el protocolo, ordenado por dónde estás, vive en la guía de MCP.
Preguntas frecuentes
¿Qué es un servidor MCP?
Es un proceso que expone capacidades (tools, resources y prompts) a un asistente de IA a través del Model Context Protocol, un estándar abierto. Permite que modelos como Claude o el agente de Cursor ejecuten funciones y accedan a datos externos de forma estandarizada.
¿Necesito una API key para crear un servidor MCP?
No. Un servidor MCP local corre en tu máquina y se comunica con el editor por stdio. Solo necesitarías credenciales si tus tools consumen una API externa que las requiera.
¿Puedo escribir un servidor MCP en otro lenguaje?
Sí. Existe SDK oficial para TypeScript, Python y otros lenguajes. En esta guía usamos el de TypeScript porque encaja con el ecosistema de Cursor, VS Code y Node, pero el protocolo es el mismo en todos.
¿Por qué no debo usar console.log en un servidor MCP?
Porque con el transporte stdio la salida estándar (stdout) es el canal del protocolo. Cualquier console.log corrompe los mensajes JSON-RPC y rompe la comunicación. Para depurar usa console.error, que escribe en stderr.
¿Cómo pruebo un servidor MCP sin conectarlo a un editor?
Con el MCP Inspector: npx @modelcontextprotocol/inspector node build/index.js. Levanta una interfaz web donde puedes listar e invocar tus tools a mano antes de integrarlo en Claude o Cursor.
Fuentes
- Build an MCP server (documentación oficial de MCP)
- Connect to local MCP servers (documentación oficial de MCP)
- MCP Inspector (documentación oficial de MCP)
- modelcontextprotocol/inspector (repositorio oficial)
- modelcontextprotocol/typescript-sdk (repositorio oficial del SDK v2)
- modelcontextprotocol/typescript-sdk, rama v1.x (repositorio oficial del SDK v1)
- Connect Claude Code to tools via MCP (documentación oficial de Claude Code)
- Model Context Protocol (MCP) (documentación oficial de Cursor)
- modelcontextprotocol/mcpb (repositorio oficial)
¿Tienes un proyecto en mente?
Trabajo con Laravel, WordPress, SEO técnico y servidores MCP. El primer paso es una llamada de descubrimiento, sin costo ni compromiso, donde me cuentas qué necesitas y te digo con honestidad si puedo ayudarte.