🛠️ Crea tu propio servidor MCP

Un servidor MCP es un proceso que se comunica mediante JSON-RPC por stdio (o HTTP). Como mínimo, debe responder a dos métodos: initialize (handshake) y tools/list (listar tools). Cuando el cliente llama a una tool, el servidor la recibe mediante tools/call y devuelve el resultado.

En la práctica, el SDK abstrae todo esto. Solo defines las herramientas y sus handlers. Pero entender la anatomía ayuda a depurar cuando algo sale mal.

El paquete @modelcontextprotocol/sdk es la forma más rápida de crear un servidor MCP. Con 30 líneas tienes un servidor funcional. La clase principal es McpServer, que instancias, registra tools y conecta a un transport.

Instalación: npm init -y && npm install @modelcontextprotocol/sdk zod. Zod se usa para validar las entradas de las herramientas de forma segura en cuanto a tipos.

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
touch index.ts

Cada tool tiene: nombre (cadena única), descripción (lo que hace, en lenguaje natural), y inputSchema (parámetros mediante Zod o JSON Schema). Un schema claro y descriptivo marca la diferencia entre que el agente acierte a la primera o tenga que adivinar.

Consejo: escribe la descripción como si se la explicaras a alguien que está empezando. El agente usa ese texto para decidir cuándo y cómo llamar a la tool.

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

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

server.tool("greet", "Say hello to someone by name", {
  name: z.string().describe("The person's name")
}, async ({ name }) => ({
  content: [{ type: "text", text: `Hello, ${name}!` }]
}));

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

El handler es la función async que recibe los argumentos validados y devuelve un CallToolResult. El resultado es un array de content items, que pueden ser texto, imágenes o recursos embedded. Los errores se devuelven con isError: true.

Patrón básico: recibir args -> ejecutar lógica -> devolver resultado {{ content: [{{ type: 'text', text: resultado }}] }}. Para los errores, devuelve el mensaje de error en el content con isError: true.

O MCP Inspector es la herramienta oficial para probar servidores MCP. Ejecuta npx @modelcontextprotocol/inspector node index.js y abre una interfaz web donde puedes listar herramientas, llamarlas con parámetros y ver las respuestas.

Además del Inspector, prueba la integración directamente en Claude Code: agrega esto al settings.json local y pídele al agente que lo use. Si puede llamar a la tool y recibir un resultado, está funcionando.

# Testar com o MCP Inspector
npx @modelcontextprotocol/inspector node index.js

Para compartir tu server: (1) publícalo en npm con npm publish, (2) asegúrate de que funcione mediante npx (configura el campo bin en package.json), (3) opcionalmente, publícalo en Smithery.ai para darle visibilidad.

Si el servidor tiene dependencias pesadas, considera usar una imagen de Docker. Así te aseguras de que funcione en cualquier máquina sin conflictos de dependencias.