Cómo crear un servidor MCP en TypeScript (SDK v2) | We.Inc
Crea un servidor MCP funcional con el SDK oficial de TypeScript v2: instálalo, registra una herramienta con un esquema Zod, conéctala por stdio y pruébala en el Inspector.
Instala el paquete oficial @modelcontextprotocol/server y Zod, crea un McpServer con un nombre y una versión, registra cada herramienta con registerTool, una descripción y un esquema de entrada Zod, y luego conecta un StdioServerTransport. Ejecuta npx @modelcontextprotocol/inspector para invocar tus herramientas a mano antes de que ninguna aplicación de IA las toque.
Las piezas que necesitas
Pieza
De dónde viene
Qué hace
McpServer
@modelcontextprotocol/server
Contiene tus herramientas y responde a las peticiones del protocolo
registerTool
Método de McpServer
Añade una herramienta: nombre, descripción, esquema de entrada, handler
StdioServerTransport
@modelcontextprotocol/server/stdio
Se comunica con el host por la entrada y la salida estándar
z.object(...)
zod/v4
Describe y valida los argumentos de la herramienta
Inspector
npx @modelcontextprotocol/inspector
Te permite listar e invocar herramientas a mano
Marca cada paso a medida que avanzas. La lista de comprobación guarda tu progreso, y cada paso tiene el comando o el archivo exacto que necesitas. El servidor terminado busca en una pequeña lista de notas, suficiente para ver todas las piezas en movimiento sin una base de datos.
Crea una carpeta, añade el package.json que se muestra abajo e instala las dos dependencias.
Pega server.ts y cambia el array de notas por tus propios datos o por una llamada a una API.
Arranca el Inspector y apúntalo al comando que ejecuta tu servidor.
Lista las herramientas, invoca notes_search con una palabra y confirma el texto que vuelve.
No escribas nunca en stdout desde un servidor stdio. Ese flujo transporta los mensajes del protocolo, así que un console.log perdido los corrompe. Usa console.error, que va a stderr.
Mantén cada herramienta pequeña y específica. A un modelo le resulta más fácil elegir entre dos herramientas llamadas notes_search y notes_create que entre una sola herramienta de notas con un selector de modo.
Valida también dentro del handler, además de en el esquema, cuando una herramienta toca dinero, archivos o datos de otras personas. El esquema comprueba la forma, no los permisos.
Fija la versión principal del SDK en package.json. La versión 1 estaba en otro paquete, @modelcontextprotocol/sdk, así que los tutoriales antiguos no coincidirán con estos imports.
Preguntas frecuentes
¿Qué paquete npm instalo?
Para la versión 2 del SDK, instala @modelcontextprotocol/server para servidores y @modelcontextprotocol/client para clientes. El paquete anterior de la v1, @modelcontextprotocol/sdk, vive en una rama v1.x y recibe correcciones de errores y de seguridad durante al menos seis meses después del lanzamiento de la v2.
¿Necesito Zod?
El README de la v2 usa Zod v4 para los esquemas de entrada y lo importa desde zod/v4, y dice que otras librerías de Standard Schema como Valibot y ArkType también funcionan. Instala la que elijas junto al SDK.
¿El servidor puede ejecutarse en Bun o Deno?
El README del SDK dice que funciona en Node.js, Bun y Deno. El Inspector es una herramienta de Node aparte y su README pide Node 22.19.0 o posterior.
¿Cómo hago que el servidor esté disponible en remoto?
Cambia el transporte stdio por Streamable HTTP y aloja el proceso en algún lugar accesible. Añade autenticación antes de exponer cualquier herramienta que modifique datos, porque cualquiera que pueda llegar a la URL puede enviar peticiones.
¿Cómo sé que una aplicación de IA entenderá mi herramienta?
Lee tu descripción y tu esquema como si no supieras nada más del proyecto. Si un desconocido no pudiera saber cuándo invocar la herramienta y qué pasarle, un modelo también tendrá que adivinar. El Inspector muestra exactamente lo que verá un host.
Por qué empezar con stdio
Un servidor stdio es simplemente un programa que arranca el host. No hay puerto, ni hosting, ni inicio de sesión, lo que lo convierte en la vía más rápida hacia una herramienta funcional que puedes probar en tu propia máquina.
Cuando las herramientas funcionan bien, pasar a Streamable HTTP cambia la línea del transporte y el hosting, no el código de las herramientas. Esa separación es el motivo principal para mantener la lógica de negocio en funciones simples que invocan los handlers.
Cómo diseñar la respuesta del handler
Un handler devuelve un objeto con un array content. Los elementos de texto son el caso habitual, y un texto corto y concreto funciona mejor: di qué coincidió y cuántos resultados hay, en lugar de volcar un conjunto de registros entero.
Cuando nada coincide, devuelve una frase que lo diga. Una cadena vacía deja al modelo adivinando si la llamada falló o si la búsqueda simplemente no encontró nada.
El servidor completo
Dos archivos. Cambia el array de notas por lo que tu servidor deba buscar.
type module permite ejecutar directamente la sintaxis import de ES; el script start usa tsx para que te saltes el paso de compilación.
Una herramienta con un esquema Zod, una función de búsqueda simple y una conexión stdio. Los logs van a stderr para que nunca se mezclen con los mensajes del protocolo.
Pruébalo con el Inspector
El Inspector tiene tres modos. La interfaz web es el sitio más fácil para empezar; el modo CLI va bien para scripts y CI.
Modos del Inspector
En la interfaz web, conéctate con el comando que arranca tu servidor (npx tsx server.ts) y luego abre la lista de herramientas.
Instala el SDK, Zod y un ejecutor de TypeScript
Escribe server.ts con una herramienta
Arranca el servidor una vez para comprobar que no falla
Abre el Inspector y conéctalo a tu servidor
Lista las herramientas e invoca notes_search a mano