Construye tu primer servidor MCP en TypeScript

MCP (Model Context Protocol) es el mecanismo que permite a Claude Code conectarse con herramientas externas. Un servidor MCP expone funciones que Claude puede invocar, igual que un LLM invoca function calls en la OpenAI API, pero con un protocolo estandarizado que funciona con cualquier cliente MCP.

Qué es exactamente un servidor MCP

Un servidor MCP es un proceso que expone un conjunto de herramientas (tools) a través de un protocolo JSON-RPC. Claude Code se conecta a él en el arranque y puede invocar esas herramientas durante la sesión.

Los casos de uso más útiles: conectar Claude con tu base de datos, exponerle APIs internas, darle acceso a servicios que no tiene de serie (Slack, Jira, tu propio CMS).

Setup inicial

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript @types/node ts-node

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "outDir": "dist",
    "strict": true
  }
}

El servidor mínimo

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "my-tools", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_timestamp",
      description: "Devuelve el timestamp actual en formato ISO",
      inputSchema: { type: "object", properties: {}, required: [] },
    },
  ],
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "get_timestamp") {
    return {
      content: [{ type: "text", text: new Date().toISOString() }],
    };
  }
  throw new Error(`Tool not found: ${request.params.name}`);
});

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

Conectarlo a Claude Code

En tu .claude/settings.json:

{
  "mcpServers": {
    "my-tools": {
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

Después de npx tsc && claude, Claude Code tiene acceso a tu herramienta get_timestamp. Desde ahí, puedes añadir las herramientas que necesites: queries a base de datos, llamadas a APIs, lectura de archivos de configuración.

El SDK de MCP maneja todo el protocolo. Tu trabajo es solo definir las herramientas y su lógica.