Construya su primer servidor MCP

¿Por qué construir un servidor personalizado?

Los servidores MCP oficiales cubren los casos de uso más comunes, pero sus flujos de trabajo son únicos. Un servidor personalizado le permite exponer cualquier API, herramienta interna o fuente de datos a su cliente de IA con exactamente la interfaz que necesita. Una vez escrito, el servidor funciona con cualquier cliente compatible con MCP: Claude Desktop, Cursor o su propio agente.

Requisitos previos

• Node.js 18+
• Familiaridad con TypeScript (tipos básicos, async/await)
• Una terminal y un editor de código

Inicializar el proyecto

Cree un nuevo directorio e inicialice un proyecto de Node:

mkdir my-mcp-server
cd my-mcp-server
npm init -y

Instale el SDK de TypeScript para MCP y los paquetes de soporte:

npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node ts-node

Agregue un tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}

Agregue un script de compilación a package.json:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

Escribir el servidor

Cree src/index.ts. Este ejemplo implementa un servidor de calculadora simple con dos herramientas: add y multiply.

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

// Crear la instancia del servidor
const server = new McpServer({
  name: "calculator",
  version: "1.0.0",
});

// Registrar la herramienta "add"
server.tool(
  "add",
  "Add two numbers together",
  {
    a: z.number().describe("First number"),
    b: z.number().describe("Second number"),
  },
  async ({ a, b }) => {
    return {
      content: [
        {
          type: "text",
          text: String(a + b),
        },
      ],
    };
  }
);

// Registrar la herramienta "multiply"
server.tool(
  "multiply",
  "Multiply two numbers",
  {
    a: z.number().describe("First number"),
    b: z.number().describe("Second number"),
  },
  async ({ a, b }) => {
    return {
      content: [
        {
          type: "text",
          text: String(a * b),
        },
      ],
    };
  }
);

// Iniciar el servidor mediante stdio
const transport = new StdioServerTransport();
await server.connect(transport);

Compilar y ejecutar

npm run build
node dist/index.js

El servidor se iniciará y esperará entradas a través de stdin. Está listo para ser conectado a un cliente.

Probar con el Inspector MCP

El Inspector MCP es una herramienta interactiva basada en navegador para probar servidores sin necesidad de una configuración completa de cliente.

npx @modelcontextprotocol/inspector node dist/index.js

Esto abre una ventana del navegador donde puede explorar sus herramientas, proporcionar entradas e invocarlas de forma interactiva. Verifique que tanto add como multiply aparezcan y devuelvan resultados correctos antes de conectarse a Claude Desktop.

Conectar a Claude Desktop

Agregue el servidor a su archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "calculator": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/dist/index.js"]
    }
  }
}

Reinicie Claude Desktop, luego pruebe en una conversación: "¿Cuánto es 347 multiplicado por 28?" — Claude debería invocar la herramienta multiply y devolver la respuesta.

Desplegar y distribuir

Para compartir su servidor con otros:

1. Publicar en npm. Ejecute npm publish después de establecer un nombre de paquete (p. ej., mcp-server-calculator). Los usuarios podrán ejecutarlo con npx mcp-server-calculator.
2. Agregar al PATH. Compile el binario, máquelo como ejecutable (chmod +x dist/index.js), agregue un shebang (#!/usr/bin/env node) y enlácelo globalmente con npm link.
3. Docker. Empaquete el servidor en una imagen Docker para una ejecución consistente en distintos entornos, especialmente útil para servidores con dependencias nativas.

Para patrones más avanzados — recursos, prompts, autenticación, streaming — consulte la documentación del SDK de TypeScript para MCP.