Módulo 4: MCP Server en TypeScript

Descripción de la cápsula

Has llegado a la Phase 2. Los módulos 1-3 construyeron tu vocabulario y modelo mental: sabes qué es MCP, cómo funciona la arquitectura Host-Client-Server, y qué son Resources, Tools y Prompts. Incluso construiste un server mínimo con las 3 primitivas. Pero ese server era un prototipo — código en un solo archivo, sin estructura, sin validación robusta, sin configuración de transports.

Ahora vas a construir un MCP server de verdad.

TypeScript no es una elección arbitraria — es el lenguaje del ecosistema MCP. La mayoría de MCP servers open source están escritos en TypeScript. El SDK oficial de TypeScript (@modelcontextprotocol/sdk) es el más maduro. La documentación oficial de Anthropic usa TypeScript como referencia. Si miras los repositorios de MCP servers en GitHub, TypeScript domina por un margen amplio. Empezar con TypeScript significa que puedes leer, entender y contribuir a la mayoría del ecosistema desde el día uno.

Este módulo es el más denso de la Phase 2, y es intencional. Los patrones que aprendes aquí — setup de proyecto, Zod schemas, error handling, transports — se repiten en Python (módulo 5), en MCP Apps (módulo 6), y en el proyecto integrador (módulo 8). Dominar el MCP server en TypeScript es dominar los fundamentos que se aplican a cualquier lenguaje.

¿Dónde estamos?

Contexto en la guía

Phase 1: Fundamentos MCP (Módulos 1-3)
  ✅ Módulo 1: Qué es MCP y por qué importa
  ✅ Módulo 2: Arquitectura Host-Client-Server
  ✅ Módulo 3: Tres Primitivas — Resources, Tools, Prompts

Phase 2: Construir MCP Servers (Módulos 4-6)
  → Módulo 4: MCP Server en TypeScript (ESTÁS AQUÍ)
  ○ Módulo 5: MCP Server en Python
  ○ Módulo 6: MCP Apps y UI Interactivo

Phase 3: Producción (Módulos 7-8)
  ○ Módulo 7: Testing, Debugging e Integración
  ○ Módulo 8: Proyecto — MCP Server Real

Lo que ya sabes

De los módulos anteriores traes:

El modelo mental M×N vs M+N — por qué un protocolo estándar es necesario
La arquitectura Host-Client-Server — cómo se conectan las piezas
Las 3 primitivas — Resources (datos), Tools (acciones), Prompts (templates)
Un MCP server mínimo — 1 resource, 1 tool, 1 prompt funcionando en Claude Code
Experiencia con el SDK básico — McpServer, StdioServerTransport, z de Zod

Lo que falta

Tu server del módulo 3 era un archivo monolítico. No tenía estructura de proyecto real. Los schemas de Zod eran básicos. No exploraste recursos dinámicos ni templates de URI. Y solo usaste stdio como transport. En este módulo vas a cerrar esas brechas.

Por qué TypeScript domina el ecosistema MCP

Los números

Si exploras los repositorios de MCP servers en GitHub, el patrón es claro:

Distribución de MCP servers open source (aproximada):
├── TypeScript/JavaScript  ~65%
├── Python                 ~25%
├── Go                     ~5%
├── Rust                   ~3%
└── Otros                  ~2%

No es accidental. Hay razones técnicas y de ecosistema:

1. El SDK nació en TypeScript

El @modelcontextprotocol/sdk de TypeScript fue el primer SDK oficial. Tiene la API surface más completa, la documentación más detallada, y los ejemplos de referencia más pulidos. Cuando Anthropic construye un nuevo MCP server oficial, lo hace en TypeScript primero.

2. Zod como estándar de validación

Zod es la librería de validación que el SDK usa para definir schemas de tools. No es un wrapper sobre JSON Schema — es una librería de validación tipada que genera JSON Schema automáticamente. Esto significa:

// Con Zod: definición tipada + validación + JSON Schema, todo en uno
{
  filePath: z.string().describe("Ruta del archivo"),
  content: z.string().min(1).describe("Contenido"),
  overwrite: z.boolean().default(false),
}

// Equivalente en JSON Schema manual:
{
  "type": "object",
  "properties": {
    "filePath": { "type": "string", "description": "Ruta del archivo" },
    "content": { "type": "string", "minLength": 1, "description": "Contenido" },
    "overwrite": { "type": "boolean", "default": false }
  },
  "required": ["filePath", "content"]
}

Zod es más conciso, más legible, y te da validación en runtime gratis. Verás esto en detalle en la cápsula 03.

3. El ecosistema Node.js es el match natural

MCP servers necesitan acceso al filesystem, ejecución de procesos, networking. Node.js tiene APIs maduras para todo esto. Además, muchas integraciones que un MCP server necesita (GitHub API, Slack API, database clients) tienen SDKs de primera clase en JavaScript/TypeScript.

4. TypeScript strict mode atrapa errores antes del runtime

Cuando usas strict: true en tu tsconfig.json, TypeScript atrapa una categoría entera de errores que en JavaScript o Python solo aparecen cuando el código se ejecuta:

// ❌ TypeScript strict mode lo detecta en compilación
function processResult(result: ToolResult) {
  console.log(result.content[0].text.toUpperCase());
  //                               ^^^^ Error: 'text' is possibly undefined
}

// ✅ La corrección es explícita
function processResult(result: ToolResult) {
  const text = result.content[0]?.text;
  if (text) {
    console.log(text.toUpperCase());
  }
}

En un MCP server, donde los inputs vienen de un modelo de lenguaje y los outputs van a un protocolo con formato estricto, este nivel de type safety previene bugs reales.

Comparación: TypeScript vs Python para MCP servers

Aspecto	TypeScript SDK	Python SDK
Madurez	Más maduro, API más completa	Maduro, API en evolución
Validación	Zod (tipado + runtime)	Pydantic / type hints
Estilo	Métodos: `server.tool()`	Decoradores: `@server.tool()`
Concurrencia	Event loop nativo (Node.js)	asyncio
Ecosistema	Más MCP servers de referencia	Más librerías de ML/AI
Comunidad	Dominante en MCP servers	Dominante en AI/ML apps
Setup	npm + tsconfig	pip + venv
Error handling	try/catch + isError	try/except + raise

La elección no es "uno es mejor que otro" — es "cuál se adapta mejor a tu caso de uso." Para MCP servers, TypeScript tiene ventaja por ecosistema. Para integrar con pipelines de ML, Python tiene ventaja. Tú aprenderás ambos.

Qué dice la comunidad

Si revisas los repositorios más populares de MCP servers, el patrón es claro:

Filesystem Server (Anthropic) → TypeScript
GitHub Server (Anthropic) → TypeScript
Slack Server (Anthropic) → TypeScript
PostgreSQL Server (comunidad) → TypeScript
Brave Search Server (comunidad) → TypeScript

Los servers oficiales de Anthropic están todos en TypeScript. Los servers más mantenidos de la comunidad tienden a estar en TypeScript. Esto no significa que Python sea peor — significa que cuando busques ejemplos, documentación, o servers para estudiar, TypeScript será tu primer recurso.

El factor Zod

Zod merece mención especial porque es más que una librería de validación — es el sistema de tipos runtime del ecosistema MCP en TypeScript. Cuando defines un schema Zod para un tool:

TypeScript infiere los tipos del handler automáticamente
El SDK genera JSON Schema para el protocolo MCP
La validación ocurre en runtime antes de que tu código se ejecute
Los errores de validación se formatean automáticamente para el modelo

Esto significa que un solo schema Zod resuelve tres problemas: tipado, validación, y documentación del protocolo. En Python, necesitas combinar type hints (tipado), Pydantic (validación), y docstrings (documentación) para lograr lo mismo.

No es que Python sea inferior — los decoradores de FastMCP son elegantes y concisos. Pero Zod ofrece una experiencia más integrada para el caso específico de MCP servers.

Objetivo del módulo

Al completar este módulo, serás capaz de:

✅ Crear un proyecto MCP en TypeScript desde cero — npm init, dependencias, tsconfig, estructura
✅ Implementar múltiples tools con Zod schemas que validan inputs automáticamente
✅ Implementar resources estáticos y dinámicos con URI templates
✅ Entender y configurar transports — stdio para desarrollo local, HTTP/SSE para uso remoto
✅ Manejar error handling robusto en tools y resources
✅ Construir un MCP server completo con múltiples tools para un caso de uso real
✅ Conectar tu server a Claude Code y verificar que funciona end-to-end

El salto del módulo 3 al módulo 4

Para que entiendas la magnitud del avance:

Módulo 3 — Server mínimo:
├── 1 archivo (src/index.ts)
├── 1 resource (estático)
├── 1 tool (básico)
├── 1 prompt (simple)
├── Schemas Zod triviales
├── Sin estructura de proyecto
├── Solo stdio
└── ~150 líneas de código

Módulo 4 — Server completo:
├── Estructura de proyecto profesional
├── Múltiples resources (estáticos + templates)
├── Múltiples tools (con validación completa)
├── Zod schemas avanzados (enums, arrays, nested objects)
├── Error handling robusto
├── Transports: stdio + HTTP/SSE + Streamable HTTP
├── Código modular y mantenible
└── ~500+ líneas de código

No te preocupes por la magnitud — vas paso a paso. Cada cápsula agrega una pieza, y al final todo encaja.

Roadmap del módulo

Cápsula	Tema	Qué aprenderás
02	Setup proyecto y SDK	Crear un proyecto desde cero: npm, TypeScript, dependencias, estructura
03	Implementar Tools	Tools con Zod schemas: básicos, complejos, con error handling
04	Implementar Resources	Resources estáticos, dinámicos, URI templates, descubrimiento
05	Transports: stdio y HTTP	Configurar stdio para local, HTTP/SSE para remoto, cuándo usar cada uno
06	Proyecto: MCP Server TS	Server completo con múltiples tools para un caso de uso real

Flujo de aprendizaje

La progresión es deliberada:

Setup (cápsula 02) — primero lo primero: un proyecto que compila y se ejecuta. Sin esto, nada más funciona.
Tools (cápsula 03) — la primitiva más importante. Aquí pasas el 80% del tiempo de implementación de un MCP server real.
Resources (cápsula 04) — datos contextuales con URI templates. Complementan los tools y hacen tu server más rico.
Transports (cápsula 05) — cómo se comunica tu server con el host. Determina dónde y cómo se ejecuta.
Proyecto (cápsula 06) — todo junto: un MCP server completo que podrías usar en tu trabajo real.

Cada cápsula es ~40% teoría y ~60% práctica. Vas a escribir mucho código.

Conexión con el proyecto integrador (Módulo 8)

El server que construyes en la cápsula 06 de este módulo es el prototipo del proyecto integrador del Módulo 8. Los patrones son los mismos:

Módulo 4 → Módulo 8:
├── Setup de proyecto          → Mismo patrón, más dependencias
├── Zod schemas                → Misma librería, schemas más complejos
├── Error handling             → Mismos patrones, más edge cases
├── Resources con templates    → Misma API, conectadas a DB real
├── Tools con validación       → Mismos patterns, operaciones más complejas
└── Transport configuration    → Mismo setup, posible deploy remoto

Cada decisión que tomes en este módulo — cómo estructuras tu código, cómo defines tus schemas, cómo manejas errores — la usarás directamente en el proyecto final. No estás aprendiendo algo temporal; estás construyendo hábitos que aplicarás en cada MCP server que crees.

Prerequisitos

Para este módulo necesitas:

✅ Node.js v18+ instalado — node --version
✅ npm instalado — npm --version
✅ Claude Code instalado y funcionando — claude --version
✅ Un editor de código con soporte TypeScript (VS Code, Cursor, etc.)
✅ Módulos 1-3 completados — especialmente el mini-proyecto del módulo 3

Conocimiento de TypeScript necesario

No necesitas ser un experto en TypeScript. Lo que necesitas saber:

// Variables tipadas
const name: string = "hello";
const count: number = 42;
const items: string[] = ["a", "b"];

// Interfaces / types
interface User {
  id: string;
  name: string;
  email: string;
}

// Funciones async
async function getData(): Promise<string> {
  const result = await fetch("...");
  return result.text();
}

// Imports/exports
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
export function helper() { ... }

Si esto te resulta familiar, estás listo. Si no, puedes aprender sobre la marcha — los ejemplos son autoexplicativos.

Límites: qué NO se cubre en este módulo

❌ Implementación en Python — Eso viene en módulo 5
❌ MCP Apps con UI — Se cubren en módulo 6
❌ Testing automatizado — Se cubre en módulo 7
❌ Deploy a producción — Se cubre en módulo 8
❌ Sampling (server-initiated LLM calls) — Feature avanzada fuera del scope de esta guía
❌ MCP Roots — Feature de contexto que el host puede enviar, mencionada pero no implementada

Este módulo es construcción pura. Estás construyendo el "cómo hacerlo en TypeScript" después de haber entendido el "qué puede hacer" en los módulos anteriores.

Evidencia de éxito

Al terminar este módulo, sabrás que tuviste éxito si:

✅ Puedes crear un proyecto MCP en TypeScript desde cero en menos de 5 minutos
✅ Tus tools tienen schemas Zod que validan inputs automáticamente
✅ Puedes implementar resources con URI templates que se descubren dinámicamente
✅ Entiendes cuándo usar stdio vs HTTP/SSE y puedes configurar ambos
✅ Tienes un MCP server funcional con múltiples tools conectado a Claude Code
✅ Te sientes cómodo leyendo código de MCP servers open source en TypeScript
✅ Estás listo para implementar lo mismo en Python (módulo 5) o escalar al proyecto final (módulo 8)

Mentalidad para este módulo

Este módulo es un taller. No es una clase magistral donde escuchas pasivamente. La proporción es ~80% código, ~20% explicación. Cada concepto se demuestra con código ejecutable que puedes copiar, compilar y probar.

Cuatro principios para aprovecharlo al máximo:

Escribe el código, no lo copies mentalmente. La diferencia entre leer código y escribirlo es enorme. Escribe cada ejemplo, compila, ejecuta. Los errores de compilación que encuentres son parte del aprendizaje.
Prueba con MCP Inspector antes de Claude Code. El Inspector te da feedback inmediato y visual. Claude Code es el destino final, pero el Inspector es tu herramienta de desarrollo.
Rompe cosas a propósito. ¿Qué pasa si envías un string donde Zod espera un number? ¿Qué pasa si el resource apunta a un archivo que no existe? ¿Qué pasa si el transport no conecta? Descubrir los modos de fallo te enseña más que solo seguir el happy path.
Lee código de servers existentes. Cuando termines cada cápsula, abre un MCP server open source en GitHub y busca los mismos patrones. Ver cómo otros developers implementan tools y resources solidifica tu comprensión.

Preguntas frecuentes antes de empezar

"¿Necesito saber TypeScript para este módulo?"

Necesitas lo básico: tipos, interfaces, async/await, imports. No necesitas conocer generics avanzados, mapped types, o conditional types. Los ejemplos son autoexplicativos y el foco está en los patrones MCP, no en TypeScript avanzado.

"¿Puedo saltar al módulo 5 (Python) directamente?"

Puedes, pero no lo recomiendo. Los conceptos se explican con más profundidad aquí porque TypeScript es el módulo principal. El módulo 5 asume que ya entiendes los patrones de este módulo y se enfoca en las diferencias idiomáticas de Python.

"¿Mi server del módulo 3 sigue sirviendo?"

Sí. De hecho, puedes usar tu server del módulo 3 como referencia mientras construyes el de este módulo. Vas a ver los mismos patrones, pero más completos y robustos.

"¿Cuánto código voy a escribir?"

El proyecto de la cápsula 06 tiene ~500+ líneas distribuidas en varios archivos. No las escribes todas de golpe — cada cápsula agrega una pieza. Al final, todo se integra.

"¿Necesito un IDE con soporte TypeScript?"

Altamente recomendado. VS Code o Cursor con TypeScript Language Server te dan autocompletado, detección de errores en tiempo real, y navegación de código. Si no usas un IDE con soporte TS, los errores de compilación son tu único feedback — es más lento pero funciona.

Herramientas que usarás en este módulo

Herramienta	Para qué la usas
Node.js	Runtime de tu MCP server
npm	Gestión de dependencias
TypeScript (tsc)	Compilador — convierte `.ts` a `.js`
@modelcontextprotocol/sdk	SDK oficial para crear MCP servers
Zod	Validación de schemas para tools
MCP Inspector	Testing visual de tu server (tools, resources, prompts)
Claude Code	El host que consume tu MCP server
VS Code / Cursor	IDE recomendado con soporte TypeScript

No necesitas instalar todo ahora — la cápsula 02 te guía paso a paso.

Resumen

Este módulo marca el inicio de la Phase 2: Construir MCP Servers
TypeScript es el lenguaje dominante del ecosistema MCP — SDK más maduro, más servers de referencia, Zod para validación
Pasas de un server mínimo (1 archivo, 3 primitivas) a un server profesional (estructura de proyecto, schemas complejos, transports)
Las cápsulas siguen un arco: Setup → Tools → Resources → Transports → Proyecto
Los patrones que aprendes aquí se aplican directamente al proyecto integrador del Módulo 8
Este módulo es ~80% código — es un taller, no una clase magistral
TypeScript primero no es una preferencia arbitraria — es donde está el ecosistema, la documentación, y los ejemplos de referencia

Recursos adicionales

MCP TypeScript SDK - SDK oficial que usarás en todo el módulo
Zod Documentation - Librería de validación para schemas de tools
TypeScript Handbook - Referencia de TypeScript si necesitas repasar
MCP Specification - Especificación oficial del protocolo
MCP Inspector - Herramienta de testing y debugging visual
Awesome MCP Servers - Directorio de MCP servers de la comunidad (la mayoría en TypeScript)
Node.js fs/promises API - API de filesystem que usarás frecuentemente
MCP Servers oficiales (Anthropic) - Servers de referencia implementados en TypeScript

Siguiente cápsula: Setup del proyecto y SDK — crear un proyecto MCP en TypeScript desde cero, configurado y listo para implementar tools y resources.

← AnteriorMini-Proyecto: MCP Server con 1 Resource, 1 Tool, 1 Prompt Siguiente →Setup del Proyecto y SDK de TypeScript