Cómo Construir Tu Primer Servidor MCP: Guía Práctica

Tabla de contenidos

Actualizado junio 2026.

TL;DR: MCP (Model Context Protocol) es cómo le das a Claude acceso estructurado a herramientas y datos externos — bases de datos, archivos, APIs — sin saturar la ventana de contexto. El servidor es más sencillo de lo que parece: instala el SDK, define tus herramientas con JSON schema, implementa los manejadores y conecta vía stdio. Puedes tener a Claude llamando tus herramientas personalizadas en menos de 30 minutos.

[Perspectiva de operador] Conecto herramientas nuevas a mis agentes regularmente, y MCP es ahora el camino estándar para hacerlo limpiamente. Una vez construido el servidor, cualquier cliente compatible — Claude Desktop, Claude Code, cualquier aplicación que use el SDK de Anthropic — puede usarlo sin cambios en el código que llama. Ese es el valor: construir una vez, reutilizar en todo.

Qué es MCP en realidad

El Model Context Protocol es un protocolo abierto que estandariza cómo los modelos de IA se conectan a contexto externo y herramientas. Piénsalo como un estándar USB-C para integraciones de IA: antes de él, cada aplicación que quería que Claude leyera una base de datos o llamara una API tenía que inventar su propia instalación. Con él, construyes un servidor MCP y cualquier cliente compatible puede usarlo.

MCP define tres cosas que un servidor puede ofrecer:

• Herramientas — funciones que Claude puede llamar (leer un archivo, consultar una BD, enviar un mensaje de Slack)
• Recursos — datos que Claude puede leer (documentos, filas de base de datos, árboles de archivos)
• Prompts — plantillas de prompts reutilizables que el host puede inyectar

Para la mayoría de casos de uso operativos, estás construyendo servidores de herramientas. Los recursos y prompts vienen después, una vez que tienes lo básico funcionando.

La arquitectura es cliente-servidor, con el cliente (Claude Desktop, Claude Code, tu aplicación personalizada) controlando todo. El servidor es pasivo — simplemente escucha solicitudes de llamadas de herramientas y devuelve resultados. El cliente decide cuándo llamar a qué herramienta basándose en el output de Claude.

Las tres piezas de todo servidor MCP

Todo servidor MCP que construyas tiene la misma estructura:

1. El objeto servidor — declara el nombre, versión y capacidades de tu servidor (herramientas, recursos, prompts)
2. Definiciones de herramientas — una lista de herramientas con nombres, descripciones y esquemas JSON para sus entradas
3. Manejadores de solicitudes — las funciones que se ejecutan cuando Claude llama a una herramienta

Eso es todo. No se necesita base de datos, stack HTTP ni capa de auth para empezar. El servidor mínimo tiene menos de 30 líneas de TypeScript.

Prerrequisitos (2 minutos)

• Node.js 18+ — verifica con node --version
• TypeScript 5+ (incluido como dependencia de desarrollo)
• Un cliente MCP para probar — Claude Desktop es gratuito y la forma más fácil de ver tu servidor funcionando

No se necesita clave API de Anthropic para ejecutar un servidor MCP. La clave API vive en el cliente (Claude Desktop), no en tu servidor.

Paso 1: Configurar el proyecto (3 minutos)

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

Agrega a package.json:

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts"
  }
}

Crea tsconfig.json:

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

Paso 2: Escribir el servidor mínimo (5 minutos)

Crea src/index.ts:

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-mcp-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// Declara qué herramientas ofrece este servidor
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_word_count",
      description: "Cuenta las palabras en un bloque de texto.",
      inputSchema: {
        type: "object",
        properties: {
          text: {
            type: "string",
            description: "El texto en el que contar palabras",
          },
        },
        required: ["text"],
      },
    },
  ],
}));

// Maneja las llamadas de herramientas del cliente
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_word_count") {
    const { text } = args as { text: string };
    const count = text.trim().split(/\s+/).filter(Boolean).length;
    return {
      content: [{ type: "text", text: `Conteo de palabras: ${count}` }],
    };
  }

  throw new Error(`Herramienta desconocida: ${name}`);
});

// Conectar vía stdio — así es como Claude Desktop habla con el servidor
const transport = new StdioServerTransport();
await server.connect(transport);

Este es el servidor completo. Registra una herramienta (get_word_count) y la implementa. La estructura es lo que importa.

Paso 3: Compilar y registrar en Claude Desktop (5 minutos)

Compila TypeScript:

npm run build

Ahora regístralo en el archivo de configuración de Claude Desktop.

En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json En Windows: %APPDATA%\Claude\claude_desktop_config.json

Si el archivo no existe, créalo:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["/ruta/absoluta/a/my-mcp-server/build/index.js"]
    }
  }
}

Usa la ruta absoluta. Reinicia Claude Desktop después de guardar. Verás un ícono de martillo (🔨) en el campo de entrada — eso significa que Claude ha descubierto tus herramientas.

Paso 4: Construir una herramienta útil

El conteo de palabras es ilustrativo. Aquí hay una herramienta más útil: leer archivos de un directorio de proyecto, que es lo que uso para agentes de inyección de contexto que resumen bases de código, changelogs o archivos de configuración.

import { readFileSync, readdirSync } from "fs";
import { join, extname } from "path";

const ALLOWED_EXTENSIONS = [".md", ".txt", ".ts", ".json", ".yaml"];
const PROJECT_DIR = process.env.PROJECT_DIR ?? process.cwd();

La lógica es la misma: define las herramientas con esquemas JSON precisos, implementa los manejadores, valida entradas para prevenir path traversal, y retorna texto al cliente.

Los errores que cometí (para que no los cometas)

La ruta debe ser absoluta. Las rutas relativas en el config de Claude Desktop no se resuelven como esperas. Usa siempre la ruta completa /home/usuario/....

Stdio significa que no puedes usar console.log. Claude Desktop se comunica con tu servidor por stdin/stdout. Un console.log de depuración corrompe el stream JSON-RPC. Usa stderr:

process.stderr.write(`Debug: ${message}\n`);

Reinicia Claude Desktop después de cada cambio de config. Los servidores MCP se cargan al inicio. Un archivo de config editado no hace nada hasta que cierras y reabres la app.

Las descripciones de herramientas son el producto. Claude decide si llamar tu herramienta basándose en el campo description. Una descripción vaga significa que Claude no sabrá cuándo usarla. Una precisa significa que Claude la alcanza en el momento correcto. Invierte más tiempo en las descripciones que en la implementación.

Cómo uso servidores MCP en producción

El patrón stdio funciona excelente para Claude Desktop y Claude Code (local). Para agentes en producción — los 30+ que ejecuto en Cloudflare Workers — uso la API de tool-use del SDK de Anthropic directamente, porque necesito la flexibilidad de enrutar a Haiku vs Sonnet por paso.

Los patrones que uso en producción:

1. Herramientas de desarrollo local — servidores MCP para Claude Code que exponen herramientas específicas del proyecto
2. Inyección de contexto — servidores MCP que precargan documentos relevantes sin copiar archivos manualmente
3. Puente prototipo-a-API — construyo MCP primero (más rápido para iterar), luego migro la lógica a SDK tool-use para producción

Qué construir después

Una vez que la estructura del servidor hace clic, las herramientas útiles son las que acceden al contexto externo de Claude:

• Lector de base de datos — ejecuta una consulta SQL de solo lectura y devuelve resultados como JSON
• Lector de Slack — obtiene los últimos N mensajes de un canal
• Lector de GitHub — lista PRs abiertas, lee un archivo en un commit específico
• Wrapper de API interna — llama tu propia API REST con encabezados de auth integrados

Preguntas frecuentes

¿Necesito una clave API de Anthropic para construir un servidor MCP?

No. Tu servidor MCP no llama a la API de Anthropic. Solo responde solicitudes de llamadas de herramientas del cliente. La clave API vive en el cliente, no en el servidor.

¿Puede mi servidor MCP llamar APIs externas?

Sí — el manejador es solo código TypeScript asíncrono. Puedes consultar una API del clima, consultar una base de datos, escribir en un archivo. Al servidor no le importa qué hace el manejador internamente.

¿Cuál es la diferencia entre transporte stdio y HTTP?

Stdio es para servidores locales — misma máquina que Claude Desktop o Claude Code. HTTP con SSE es para servidores remotos que puedes desplegar como servicio web. Empieza con stdio; es más simple de depurar.

¿Cómo sabe Claude cuándo llamar mi herramienta?

Claude decide basándose en el campo description de la herramienta y el contexto de la conversación. Si Claude sigue ignorando tu herramienta, perfecciona la descripción.