Construir un Servidor MCP Custom: Guía Práctica

MCP (Model Context Protocol) es el protocolo de Anthropic que da a Claude herramientas personalizadas: llamadas API, consultas a bases de datos, manipulación de archivos. Aquí está cómo construir tu propio servidor MCP.

Qué Hace un Servidor MCP

Un servidor MCP expone tools (funciones que Claude puede llamar), resources (datos legibles) y prompts (plantillas predefinidas).

Setup Mínimo

npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript tsx @types/node

Servidor Básico

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: "mi-servidor-mcp", version: "1.0.0" });

server.tool(
  "buscar_cliente",
  "Busca un cliente en la base de datos por nombre o email",
  {
    query: z.string().describe("Nombre o email del cliente"),
    limit: z.number().optional().default(5),
  },
  async ({ query, limit }) => {
    const results = await searchDatabase(query, limit);
    return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
  }
);

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

Gestión de Errores

server.tool("llamada_api", "...", { url: z.string() }, async ({ url }) => {
  try {
    const response = await fetch(url);
    if (!response.ok) {
      return {
        content: [{ type: "text", text: `Error HTTP ${response.status}` }],
        isError: true,
      };
    }
    return { content: [{ type: "text", text: JSON.stringify(await response.json()) }] };
  } catch (err) {
    return {
      content: [{ type: "text", text: `Error de red: ${err instanceof Error ? err.message : String(err)}` }],
      isError: true,
    };
  }
});

Configuración en Claude Code

{
  "mcpServers": {
    "mi-servidor": {
      "command": "npx",
      "args": ["tsx", "/ruta/hacia/servidor.ts"],
      "env": { "DATABASE_URL": "postgresql://..." }
    }
  }
}

Casos de Uso Reales

Servidor MCP que uso internamente: acceso a PostgreSQL + APIs internas de negocio. Claude consulta datos directamente en lenguaje natural sin que yo tenga que codificar un endpoint cada vez.

Patrón recomendado: un servidor por dominio de negocio (CRM, facturación, soporte) en lugar de un servidor omnisciente — más fácil de mantener y securizar.