Crea un MCP Server usando el SDK oficial en TypeScript: la alternativa para desarrolladores de JavaScript.
MCP cuenta con dos SDK oficiales mantenidos por Anthropic: el @modelcontextprotocol/sdk para TypeScript y el fastmcp para Python. Ambos implementan la misma especificación y producen servers totalmente compatibles entre sí. La elección entre ellos depende de tu stack y tus preferencias personales: el resultado final es idéntico para el client.
El SDK de TypeScript (@modelcontextprotocol/sdk) es más verboso que Python, pero ofrece tipado fuerte con interfaces y tipos definidos para cada request y response. El SDK de Python (fastmcp) usa decorators y es más conciso, ideal para crear prototipos rápidamente. Ambos se comunican mediante JSON-RPC sobre stdio o SSE y producen servers 100% compatibles con cualquier cliente MCP. La elección depende únicamente de tus preferencias — el protocolo es el mismo.
El ecosistema MCP está dividido entre los dos SDKs: aproximadamente 55% de los servidores de la comunidad están escritos en Python (por su simplicidad) y 45% en TypeScript (por la robustez de tipos). Servers oficiales como filesystem, fetch e memory están escritos en TypeScript. Ambos SDK reciben actualizaciones simultáneas cuando evoluciona la spec.
Crear un MCP Server en TypeScript sigue el flujo estándar de cualquier proyecto Node.js/TS: inicializar con npm, configurar TypeScript, instalar el SDK y escribir el código en el directorio src/. La estructura es sencilla y familiar para quienes ya trabajan con TypeScript.
La estructura mínima de un MCP Server TypeScript consiste en: package.json con la dependencia @modelcontextprotocol/sdk, tsconfig.json configurado para ESModules y target ES2020+, y src/index.ts con el código del server. El entry point crea una instancia de Server, registra los handlers y se conecta al transporte stdio con StdioServerTransport.
mkdir meu-mcp-server && cd meu-mcp-server && npm init -y — Crea el directorio del proyecto e inicializa package.json.
npm install @modelcontextprotocol/sdk — Instala el SDK oficial de MCP para TypeScript.
npx tsc --init — Genera tsconfig.json. Configura "module": "ESNext", "target": "ES2020" e "outDir": "./dist".
mkdir src && touch src/index.ts — Crea el archivo principal donde se implementará el servidor.
Agrega "type": "module" en tu package.json para usar ESModules de forma nativa. En el tsconfig.json, define "moduleResolution": "node16" para compatibilidad. Agrega también un script "build": "tsc" e "start": "node dist/index.js" en package.json para facilitar el workflow.
En el SDK TypeScript, las tools se registran usando request handlers. A diferencia de Python, donde los decorators simplifican la sintaxis, en TS defines explícitamente el handler para CallToolRequestSchema y declara las entradas mediante JSON Schema. Es más verboso, pero cada tipo es explícito y se valida en tiempo de compilación.
Para implementar tools en TypeScript, usas server.setRequestHandler(ListToolsRequestSchema, ...) para listar las tools disponibles (que devuelve name, description e inputSchema) y server.setRequestHandler(CallToolRequestSchema, ...) para ejecutarlas. El inputSchema se define como JSON Schema estándar con type, properties y required. Dentro del handler de CallTool, haces un switch en el request.params.name para despachar la lógica correcta.
El patrón en TS es devolver { content: [{ type: "text", text: resultado }] } del handler de CallTool. Para errores, agrega isError: true a la respuesta. Crea una función auxiliar makeTextResponse(text: string) para evitar repeticiones, un patrón común en servers TS bien estructurados.
Además de Tools, el SDK TypeScript admite Resources e Prompts usando el mismo patrón de request handlers. Resources exponen datos para que el modelo los lea, mientras que Prompts proporcionan templates reutilizables. La API sigue la misma filosofía: registrar un handler para el schema correspondiente.
Para Resources, usa server.setRequestHandler(ListResourcesRequestSchema, ...) para listar recursos y server.setRequestHandler(ReadResourceRequestSchema, ...) para servir el contenido. Cada recurso tiene una URI única (ej.: file:///config.json) y devuelve contenido como text o blob. Para Prompts, el patrón es idéntico: ListPromptsRequestSchema e GetPromptRequestSchema. La misma arquitectura, diferentes schemas.
Registrar el handler de ListResources que devuelve la lista de resources con uri, name y description.
Registrar el handler de ReadResource que recibe la URI y devuelve el contenido con el mimeType apropiado.
Comprobar en MCP Inspector si los resources aparecen y devuelven contenido correctamente.
En la práctica, Tools es la funcionalidad más usada (presente en ~95% de los servers), seguidas por Resources (~40%) y Prompts (~15%). Sin embargo, Resources son especialmente valiosos en escenarios enterprise donde el modelo necesita acceder a documentación, configs o datos sin ejecutar acciones. Prompts son ideales para estandarizar interacciones recurrentes con el modelo.
A diferencia de Python, donde ejecutas el archivo directamente, en TypeScript es necesario compilar antes de ejecutar. El comando tsc compila TypeScript a JavaScript en el directorio dist/, y después ejecutas con node dist/index.js. La configuración de Claude Desktop apunta al archivo JavaScript compilado.
El workflow de build es: npm run build (que ejecuta tsc) para compilar y luego node dist/index.js para ejecutar. En Claude Desktop, la configuración queda así: "command": "node", "args": ["/caminho/absoluto/dist/index.js"]. Usa siempre rutas absolutas en el config para evitar problemas. Como alternativa, usa npx ts-node src/index.ts durante el desarrollo para omitir el build.
Agrega "build": "tsc" e "watch": "tsc --watch" en los scripts de package.json. Durante el desarrollo, usa npm run watch en una terminal para recompilar automáticamente con cada cambio. Para producción, siempre ejecuta npm run build y prueba con node dist/index.js antes de configurarlo en Claude Desktop.
¡Siempre compila antes de ejecutar! Un error común es editar el archivo .ts y olvidarte de volver a compilar, ejecutando la versión antigua de .js. Si tus cambios no parecen surtir efecto, verifica si ejecutaste tsc antes de reiniciar el server. Consejo: configura un script "dev": "tsc && node dist/index.js" que compila y ejecuta en secuencia.
Probar un MCP Server TypeScript sigue el mismo flujo que en Python: usa el MCP Inspector para depuración interactiva y el Claude Desktop para una prueba de uso real. El resultado debe ser idéntico al de un server de Python equivalente: si ambos implementan la misma tool, el output para el cliente es el mismo.
O MCP Inspector (npx @modelcontextprotocol/inspector node dist/index.js) se conecta a tu server y te permite probar cada tool, resource y prompt individualmente. Ves los requests JSON-RPC enviados y las responses recibidas en tiempo real. Para hacer pruebas en producción, configura el server en el Claude Desktop y úsalo en conversaciones reales. Compara el resultado con un servidor Python equivalente para garantizar la compatibilidad.
Ejecutar npm run build y verificar que no haya errores de compilación de TypeScript.
Probar en MCP Inspector: verificar que tools, resources y prompts aparezcan y respondan correctamente.
Configura Claude Desktop y haz pruebas en conversaciones reales para validar la experiencia de usuario.
Si tienes un server de Python equivalente, compara los outputs para garantizar un comportamiento idéntico.
Siguiente Módulo: 5.5 — Explorando servidores de la comunidad