Cómo crear un servidor MCP con TypeScript en 2026: tutorial paso a paso para Claude Desktop

Si en 2024 el gran salto de los LLM fue el tool use, en 2026 el estándar que lo hace universal se llama Model Context Protocol (MCP). Es el protocolo abierto publicado por Anthropic que se ha convertido en el "USB-C de la IA": un mismo servidor MCP funciona con Claude Desktop, con la API de Claude, con Cursor, con ChatGPT vía adaptador y con cualquier cliente que hable el protocolo. Escribir un servidor MCP hoy es la manera más rentable de exponer datos, APIs o acciones internas a un ecosistema completo de asistentes.

En este tutorial vas a construir, desde cero y en TypeScript, un servidor MCP funcional que expone una herramienta get_weather conectada a la API pública Open-Meteo (gratis y sin autenticación). Cubriremos setup del proyecto, definición de tools con Zod, manejo de errores, transporte STDIO para desarrollo local y HTTP para producción, integración con Claude Desktop y estrategias de testing. Al final tendrás plantilla lista para adaptar a tus propias fuentes de datos.

Qué es MCP y por qué es el USB-C de la IA

Model Context Protocol es un protocolo cliente-servidor basado en JSON-RPC 2.0 que define un vocabulario común para que los asistentes IA descubran y usen recursos externos. Un cliente MCP (por ejemplo, Claude Desktop) inicia el servidor, negocia capacidades y a partir de ahí puede listar y ejecutar tres primitivas: tools, resources y prompts. El resultado es que la lógica de "cómo hablo con esta API" queda encapsulada en un binario reutilizable, y el modelo solo tiene que decidir cuándo llamar cada tool.

La analogía del USB-C es literal: antes de MCP, cada integración era un cable propietario. Hoy escribes el servidor una vez y lo enchufas a Claude Desktop, a la API programática de Claude, a Cursor 3, a Zed, a n8n y a cualquier futuro cliente que implemente el protocolo. Anthropic lo publicó en noviembre de 2024 y, a lo largo de 2025 y 2026, OpenAI, Google, Cursor, JetBrains, Sourcegraph y decenas más lo han adoptado. Si buscas una introducción teórica antes de programar, te recomiendo pasar por la guía completa de MCP publicada en Arkaia; en este artículo vamos directos al código.

Diferencia entre tools, resources y prompts

MCP expone tres primitivas y confundirlas es el error número uno cuando empiezas. Las tools son acciones con efectos secundarios que el modelo decide invocar; los resources son datos legibles bajo un URI; los prompts son plantillas reutilizables que el cliente puede lanzar. Vamos por partes:

• Tools: funciones que el modelo llama activamente. Ejemplos: get_weather(ciudad), send_email(destinatario, cuerpo), run_sql(query). Reciben argumentos, ejecutan y devuelven un resultado. Son análogas a un function calling clásico, pero declaradas por el servidor.
• Resources: datos con un URI estable que el cliente lee cuando lo necesita. Ejemplos: file:///proyecto/README.md, postgres://tabla/usuarios, arkaia://articulos/latest. No tienen efectos secundarios: son solo lectura y suelen cachearse.
• Prompts: plantillas parametrizadas que el usuario del cliente elige (por ejemplo, un menú "Analizar código" en Claude Desktop). El servidor devuelve mensajes preformateados para inyectar en la conversación.

Regla mental: si quieres que la IA haga algo, es una tool; si quieres que lea algo, es un resource; si quieres que el usuario arranque un flujo predefinido, es un prompt. En nuestro tutorial construiremos una tool, porque son la primitiva más habitual y la que más rendimiento saca al modelo.

Requisitos previos

Necesitas cinco cosas antes de empezar. Ninguna requiere tarjeta de crédito:

• Node.js 20 LTS o superior (recomendado 22 LTS en julio de 2026). El SDK oficial usa ESM y APIs modernas de Node.
• pnpm, npm o yarn: usaré pnpm por rapidez, pero los comandos son intercambiables.
• Claude Desktop instalado (macOS, Windows o Linux). Descárgalo gratis desde claude.ai/download. La cuenta gratuita es suficiente para probar servidores MCP locales.
• Editor con TypeScript: VS Code, Cursor, WebStorm o Zed sirven. Cualquiera con soporte de tipos.
• Conocimientos básicos de TypeScript: interfaces, async/await y modules ESM. No hace falta ser experto en tipos avanzados.

Cuenta en console.anthropic.com es opcional: la vas a necesitar solo si quieres invocar el servidor MCP desde la API programática, no desde Claude Desktop. Si prefieres el flujo Python, tienes cubierto ese caso en el tutorial de agentes con Claude API y MCP en Python.

Paso 1: Crear el proyecto TypeScript e inicializar pnpm

Empezamos con un directorio limpio y un package.json configurado para ESM (el SDK de MCP lo requiere). Abre la terminal:

mkdir mcp-weather-server && cd mcp-weather-server
pnpm init

# Editar package.json y añadir:
#   "type": "module"
#   "bin": { "mcp-weather": "./dist/index.js" }

pnpm add -D typescript @types/node tsx
pnpm exec tsc --init --target es2022 --module nodenext --moduleResolution nodenext \
  --outDir dist --rootDir src --strict true --esModuleInterop true

Crea la carpeta src y un archivo src/index.ts vacío. Añade al package.json los scripts de trabajo:

{
  "scripts": {
    "build": "tsc",
    "dev": "tsx watch src/index.ts",
    "start": "node dist/index.js"
  }
}

Con esto tienes el esqueleto: pnpm dev recompila en caliente durante desarrollo y pnpm build && pnpm start ejecuta la versión compilada. Todo lo demás será código dentro de src/.

Paso 2: Instalar el SDK oficial de MCP y Zod

El SDK oficial se publica en npm como @modelcontextprotocol/sdk. Zod nos servirá para declarar el esquema de entrada de cada tool con validación en tiempo de ejecución y tipos derivados automáticos. Instala ambos:

pnpm add @modelcontextprotocol/sdk zod

# Verifica versiones instaladas
pnpm list @modelcontextprotocol/sdk zod

En julio de 2026 la versión estable del SDK es la 1.x y Zod está en la serie 3.x. Ambos exponen APIs ESM puras, motivo por el que hemos configurado module: nodenext en el tsconfig.json. Si intentas mezclarlo con CommonJS, obtendrás errores de require vs import.

Zod es opcional (podrías escribir el inputSchema a mano como JSON Schema), pero te ahorra doble trabajo: defines el esquema una sola vez y obtienes validación runtime más tipado estático. En un servidor MCP de producción esta doble red de seguridad es oro puro.

Paso 3: Crear el servidor MCP básico

Vamos al primer bloque de código serio. El SDK expone la clase McpServer, que abstrae la gestión de sesión, listado de capacidades y despacho de llamadas. Escribe en src/index.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({
  name: "mcp-weather-server",
  version: "0.1.0",
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  // El proceso queda vivo escuchando por stdin/stdout
}

main().catch((err) => {
  console.error("Fallo fatal del servidor MCP:", err);
  process.exit(1);
});

Este archivo ya es un servidor MCP válido, aunque todavía no expone ninguna tool. Compílalo con pnpm build y prueba a lanzarlo: node dist/index.js. Verás que se queda escuchando. Ese es el comportamiento correcto: en modo STDIO el servidor espera mensajes JSON-RPC por la entrada estándar y responde por la salida estándar. Sal con Ctrl+C.

Fíjate en dos detalles clave: los imports terminan en .js aunque los archivos sean .ts (regla ESM de Node) y todos los mensajes de log del servidor deben ir a stderr (nunca a stdout, porque compartes ese canal con el protocolo).

Paso 4: Definir la primera tool get_weather con esquema Zod

Ahora la parte jugosa: registramos una tool llamada get_weather que acepta una ciudad y una unidad opcional. Actualiza src/index.ts:

import { z } from "zod";

const weatherInputSchema = {
  latitude: z
    .number()
    .min(-90)
    .max(90)
    .describe("Latitud en grados decimales, entre -90 y 90"),
  longitude: z
    .number()
    .min(-180)
    .max(180)
    .describe("Longitud en grados decimales, entre -180 y 180"),
  units: z
    .enum(["celsius", "fahrenheit"])
    .optional()
    .default("celsius")
    .describe("Unidades de temperatura (celsius por defecto)"),
};

server.registerTool(
  "get_weather",
  {
    title: "Consultar el tiempo",
    description:
      "Devuelve el clima actual para una latitud y longitud dadas usando Open-Meteo.",
    inputSchema: weatherInputSchema,
  },
  async ({ latitude, longitude, units }) => {
    // Implementación en el siguiente paso
    return {
      content: [
        { type: "text", text: `TODO: consultar clima en ${latitude}, ${longitude} en ${units}` },
      ],
    };
  }
);

Tres decisiones de diseño importantes aquí:

1. Pedimos latitud y longitud, no el nombre de la ciudad. Open-Meteo requiere coordenadas; si le pides al modelo que devuelva la lat/lon exacta suele acertar para ciudades conocidas, y el usuario puede corregir. Alternativa: añadir un paso previo de geocoding.
2. El campo describe de Zod no es decorativo. El SDK lo pasa como description en el JSON Schema que ve el modelo. Buenas descripciones = menos llamadas fallidas.
3. La firma del handler es async ({ ... }) => {}: devolvemos un objeto con content, un array de bloques. Un bloque tipo text es lo mínimo; más adelante veremos image y resource.

Paso 5: Implementar la lógica con fetch a Open-Meteo

Node 22 trae fetch global, así que no necesitamos axios ni node-fetch. Sustituye el handler del paso anterior por la implementación real:

async ({ latitude, longitude, units }) => {
  const tempUnit = units === "fahrenheit" ? "fahrenheit" : "celsius";

  const params = new URLSearchParams({
    latitude: latitude.toString(),
    longitude: longitude.toString(),
    current: "temperature_2m,wind_speed_10m,relative_humidity_2m,weather_code",
    temperature_unit: tempUnit,
    timezone: "auto",
  });

  const url = `https://api.open-meteo.com/v1/forecast?${params.toString()}`;
  const response = await fetch(url);

  if (!response.ok) {
    throw new Error(
      `Open-Meteo respondió ${response.status} ${response.statusText}`
    );
  }

  const data = (await response.json()) as {
    current: {
      temperature_2m: number;
      wind_speed_10m: number;
      relative_humidity_2m: number;
      weather_code: number;
    };
    current_units: { temperature_2m: string };
  };

  const c = data.current;
  const unitLabel = data.current_units.temperature_2m;

  const resumen = [
    `Temperatura: ${c.temperature_2m}${unitLabel}`,
    `Humedad: ${c.relative_humidity_2m}%`,
    `Viento: ${c.wind_speed_10m} km/h`,
    `Código de tiempo WMO: ${c.weather_code}`,
  ].join(" | ");

  return {
    content: [
      { type: "text", text: `Clima actual en ${latitude}, ${longitude}: ${resumen}` },
    ],
  };
},

Open-Meteo devuelve un JSON con un objeto current muy manejable. El campo weather_code sigue el estándar WMO (0 = despejado, 3 = nublado, 61 = lluvia leve, etc.). Un ejercicio útil: extiende el código con un diccionario que traduzca weather_code a texto en español antes de devolverlo al modelo.

Paso 6: Añadir manejo de errores robusto

En producción, cualquier tool falla tarde o temprano: red caída, API que responde 500, JSON malformado. MCP distingue entre errores de protocolo (excepciones que rompen la sesión) y errores de tool (que se devuelven al modelo para que decida qué hacer). Queremos siempre lo segundo, salvo desastre absoluto.

El patrón recomendado: capturar excepciones en el handler, devolver un objeto con isError: true y un texto explicativo. Envuelve la lógica del paso 5 en un try/catch:

async ({ latitude, longitude, units }) => {
  try {
    // ... la lógica del paso anterior ...
    return {
      content: [{ type: "text", text: `Clima actual: ${resumen}` }],
    };
  } catch (err) {
    const mensaje = err instanceof Error ? err.message : String(err);
    return {
      isError: true,
      content: [
        {
          type: "text",
          text: `No se pudo obtener el clima para ${latitude}, ${longitude}: ${mensaje}. Sugerencia: verifica coordenadas válidas o reintenta en unos segundos.`,
        },
      ],
    };
  }
},

Con isError: true, el modelo recibe el mensaje como resultado de tool pero sabe que algo falló. Suele reaccionar reintentando, pidiendo aclaración al usuario o cambiando de tool. Nunca lances excepciones no capturadas: rompen la conexión MCP y Claude Desktop marca el servidor como caído.

Añade también un timeout de red con AbortSignal.timeout(5000) en la llamada fetch. Sin timeout, una API colgada bloquea el servidor entero durante minutos. Cinco segundos es un buen punto de partida para APIs públicas rápidas como Open-Meteo.

Paso 7: Configurar el transporte STDIO

Ya lo hemos visto de pasada, pero conviene entenderlo. STDIO significa que el cliente (Claude Desktop) lanza tu binario como subproceso y se comunica con él por stdin/stdout intercambiando mensajes JSON-RPC. Ventajas: cero configuración de red, aislamiento por proceso, credenciales locales bajo tu control. Inconveniente: cada cliente arranca su propia instancia, no compartible entre máquinas.

El fragmento del paso 3 ya conecta el transporte:

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

Punto crítico: todo el logging debe ir a console.error o process.stderr.write. Si escribes en console.log, contaminas el canal del protocolo y el cliente descartará mensajes o cortará la conexión. Es el error más frecuente en servidores MCP nuevos: revisa tu código y todas las librerías que uses.

Paso 8: Conectar el servidor con Claude Desktop

Compila el proyecto con pnpm build. Luego localiza el archivo de configuración del cliente. En cada sistema operativo está en un sitio distinto:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Si no existe, créalo. Añade una entrada mcpServers apuntando al binario compilado:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/ruta/absoluta/a/mcp-weather-server/dist/index.js"]
    }
  }
}

La ruta debe ser absoluta: Claude Desktop lanza el proceso desde un contexto donde tu PATH puede no estar disponible. Si tu servidor necesita variables de entorno (claves API, por ejemplo), añádelas en el campo env:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/ruta/absoluta/a/dist/index.js"],
      "env": { "LOG_LEVEL": "debug" }
    }
  }
}

Guarda y reinicia Claude Desktop por completo (cierra desde el menú, no solo la ventana). En la esquina inferior derecha del chat aparecerá un icono de herramientas: pulsa y comprueba que get_weather figura activa. Ahora prueba a preguntar: "¿Qué tiempo hace en Bilbao? Latitud 43.26 longitud -2.93". Verás que Claude solicita permiso para usar la tool y devuelve la respuesta con datos reales.

Paso 9: Testing y debugging

Depurar por STDIO es complicado porque no puedes usar console.log. Tres estrategias que te salvarán tiempo:

1. Inspector oficial: ejecuta npx @modelcontextprotocol/inspector node dist/index.js. Abre una interfaz web con listado de tools, resources, prompts y ejecución manual con formulario. Es la mejor herramienta para iterar antes de tocar Claude Desktop.
2. Logs a fichero: escribe con fs.appendFileSync a /tmp/mcp-weather.log. Sigue con tail -f en otra terminal. Nunca mezclarás logs con el protocolo.
3. Tests unitarios del handler: separa la lógica de negocio (llamada a Open-Meteo) del handler MCP. Testéala con vitest como cualquier módulo TypeScript. El handler MCP se convierte en un wrapper delgado que no necesita mock del transporte.

En Claude Desktop, si el servidor no aparece, revisa el log del propio cliente: en macOS lo tienes en ~/Library/Logs/Claude/mcp*.log. Los errores más comunes: JSON malformado, ruta incorrecta, permisos de ejecución o versión antigua de Node.

Bonus: transporte HTTP para producción

STDIO es genial para desarrollo local, pero si quieres exponer tu servidor a varios usuarios, a Claude en la nube o a clientes remotos, necesitas HTTP. El SDK ofrece StreamableHTTPServerTransport, que combina HTTP tradicional con Server-Sent Events para respuestas en streaming. Reemplaza el bloque del paso 3 así:

import express from "express";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamable-http.js";

const app = express();
app.use(express.json());

app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: () => crypto.randomUUID(),
  });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(3333, () => console.error("MCP HTTP en :3333"));

Para producción real añade autenticación (una API key en cabecera Authorization: Bearer es un mínimo), rate limiting con express-rate-limit y despliega detrás de HTTPS. Fly.io, Railway, Render o un VPS con Caddy funcionan bien. En julio de 2026, Anthropic mantiene un registry oficial de servidores MCP donde puedes listar el tuyo si es público: modelcontextprotocol.io.

Ejemplos de servidores MCP populares en 2026

Antes de escribir tu propio servidor, mira lo que ya existe. Puede que la integración que necesitas esté hecha:

• GitHub: gestión de repos, issues y pull requests. Oficial de Anthropic. Ideal para asistentes de código.
• Notion: crea páginas, edita bases de datos, busca contenido. Excelente para gestión del conocimiento.
• Slack: envía mensajes, consulta canales, gestiona hilos. Combina bien con agentes que reportan estado.
• Postgres: read_query, list_tables, describe_table. Convierte a Claude en un analista SQL de emergencia.
• Filesystem: lectura y escritura restringidas a un directorio sandbox. Es el ejemplo canónico del protocolo.
• Playwright: navegación web programática. Útil para scraping controlado y testing E2E.
• Google Drive, Sentry, Linear, Cloudflare, Sequential Thinking: todos con implementaciones oficiales o de la comunidad.

El repositorio github.com/modelcontextprotocol/servers mantiene la lista oficial y mcp.so agrega los de la comunidad. Antes de reinventar la rueda, busca. Si necesitas comparar arquitecturas de agentes con y sin MCP, la guía de agentes IA 2026 desglosa las opciones.

Errores comunes y troubleshooting

Estos son los tropiezos más habituales cuando montas tu primer servidor MCP en TypeScript:

• Servidor no aparece en Claude Desktop: casi siempre es una ruta relativa en el JSON de configuración o un JSON malformado. Valida el archivo con jq . claude_desktop_config.json.
• Cannot use import statement outside a module: falta "type": "module" en package.json o module: nodenext en tsconfig.
• Extensiones .js en imports .ts: en ESM son obligatorias. import x from "./foo.js" aunque el archivo sea foo.ts.
• Protocol error / mensajes descartados: alguien está escribiendo en stdout. Busca console.log, banners de librerías o process.stdout.write y redirige a stderr.
• Zod parse errors visibles al modelo: mejora las descripciones del schema y añade .default() a los campos opcionales para que el modelo tenga menos dudas.
• Fetch cuelga indefinidamente: añade siempre AbortSignal.timeout().
• Cambios en el código no se reflejan: Claude Desktop cachea el binario. Cierra el cliente completo, no solo reiniciar la conversación.

Si un problema resiste, activa modo verbose del inspector (--verbose) y revisa el handshake completo. Suele revelar dónde se rompe el flujo.

Cómo publicar tu servidor MCP en el registry oficial

Cuando tu servidor esté maduro, publícalo. Los pasos:

1. Publica el paquete en npm como @tu-usuario/mcp-nombre. Añade el binario en package.json con "bin": { "mcp-nombre": "dist/index.js" } para que sea ejecutable con npx.
2. Añade README con instrucciones de configuración: bloque JSON de ejemplo listo para copiar al claude_desktop_config.json.
3. Envía un PR al repo modelcontextprotocol/servers o registra el servidor en mcp.so siguiendo su formulario.
4. Versiona con SemVer: los cambios de esquema de tool son breaking; súbelos como versión mayor.
5. Documenta permisos y datos accedidos: los usuarios revisarán qué hace tu servidor antes de instalarlo. Transparencia total gana instalaciones.

Un servidor MCP que resuelve un caso de uso concreto (facturación con tu ERP, monitorización con tu APM, integración con tu CRM) tiene demanda inmediata. Publicar es la manera más rápida de posicionarte como referente. Si trabajas con vibecoding y MCPs en Cursor, echa un ojo también al tutorial de Cursor 3 Composer 2.

Material recomendado para desarrollar servidores MCP

Estos son los productos que mejor complementan un flujo de trabajo escribiendo servidores MCP en TypeScript. Todos con enlaces de afiliado Amazon (tag webmasteroson-21):

• Logitech MX Master 3S: el ratón de referencia para programadores. Scroll ultrarrápido, clics silenciosos, tres dispositivos emparejables. Ver precio actual en Amazon.
• BenQ RD280U: monitor 4K específico para programación con modo Coding y proporción 3:2 ideal para leer código. Ver precio actual en Amazon.
• Dell S2725QS: monitor 27" 4K 120Hz USB-C, gran opción polivalente para código y multimedia. Ver precio actual en Amazon.
• Mac mini M4 16GB/512 SSD: máquina silenciosa y potente para desarrollar servidores MCP en local sin sobrecalentar el portátil. Ver precio actual en Amazon.
• Libro Learning TypeScript (Josh Goldberg, O'Reilly): la mejor introducción moderna al lenguaje, cubre exactamente el nivel que necesitas para escribir servidores MCP sólidos. Ver precio actual en Amazon.
• Libro Programming TypeScript (Boris Cherny, O'Reilly): profundiza en tipos avanzados, ideal cuando tu esquema Zod se vuelva complejo. Ver precio actual en Amazon.
• Libro Aprende Claude Code CLI: complemento perfecto para dominar el CLI de Claude y probar tu servidor MCP desde la terminal. Ver precio actual en Amazon.

Conclusión

Acabas de construir un servidor MCP funcional en TypeScript en menos de 100 líneas de código útil. Con lo que has aprendido puedes exponer cualquier API, base de datos o script interno a Claude Desktop y a todo el ecosistema de clientes MCP compatibles. La curva de entrada al protocolo es baja y la palanca de productividad, enorme: un servidor bien escrito ahorra decenas de horas al año en tareas que antes eran clics manuales.

Los siguientes pasos naturales son: añadir resources además de tools, montar autenticación en el transporte HTTP para exponerlo a tu equipo, y explorar el elicitation (una novedad del SDK 1.x que permite al servidor pedir aclaraciones al usuario a mitad de una tool call). Si quieres seguir mejorando el flujo de agentes IA, no te pierdas la guía de prompt engineering 2026 y el tutorial de Claude Code CLI.

Preguntas frecuentes