Tu primer servidor MCP en 20 minutos

Qué es realmente MCP

Model Context Protocol es el estándar abierto de Anthropic para dar a los asistentes de IA acceso estructurado a herramientas y datos externos. Piénsalo como un contrato de API bien tipado entre tu host de modelos (Claude Code, Cursor, etc.) y cualquier capacidad que quieras exponer: una base de datos, un web scraper, un vigilante de archivos, un bot de Slack, un disparador de CI.

Cuando construyes un servidor MCP, estás construyendo un puente. El modelo llama a tus herramientas por nombre con argumentos estructurados; tu servidor las ejecuta y devuelve resultados estructurados. Nada de "ve a esta URL y dime qué ves" — solo llamadas a funciones tipadas.

Requisitos previos

• Node.js 22+
• Una configuración de Claude Code o Cursor que soporte MCP
• 20 minutos

Paso 1: Montar el servidor

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

Crea tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "strict": true
  }
}

Paso 2: Escribe tu primera herramienta

Crea src/index.ts:

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-first-mcp",
  version: "0.1.0",
});

// Tool: fetch and summarize a URL's title
server.tool(
  "get_page_title",
  "Fetches the <title> tag from a given URL",
  { url: z.string().url().describe("The URL to fetch") },
  async ({ url }) => {
    try {
      const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
      const html = await res.text();
      const match = html.match(/<title[^>]*>(.*?)<\/title>/is);
      const title = match?.[1]?.trim() ?? "No title found";
      return { content: [{ type: "text", text: title }] };
    } catch (err) {
      return {
        content: [{ type: "text", text: `Error: ${String(err)}` }],
        isError: true,
      };
    }
  }
);

// Tool: simple math evaluator
server.tool(
  "calculate",
  "Evaluates a safe arithmetic expression",
  { expression: z.string().describe("e.g. '2 + 2 * 10'") },
  async ({ expression }) => {
    // Only allow digits, operators, spaces, parens
    if (!/^[0-9+\-*/.() ]+$/.test(expression)) {
      return {
        content: [{ type: "text", text: "Invalid expression" }],
        isError: true,
      };
    }
    const result = Function(`"use strict"; return (${expression})`)();
    return { content: [{ type: "text", text: String(result) }] };
  }
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);

Paso 3: Conéctalo a Claude Code

Añade esto a tu configuración MCP de Claude Code (normalmente ~/.claude/mcp.json o el .mcp.json del workspace):

{
  "mcpServers": {
    "my-first-mcp": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/my-mcp-server/src/index.ts"]
    }
  }
}

Reinicia Claude Code. Abre la paleta de herramientas — tus dos herramientas deberían aparecer.

Paso 4: Pruébalo sin un host

Usa el inspector MCP:

npx @modelcontextprotocol/inspector tsx src/index.ts

Esto abre una UI local donde puedes invocar tus herramientas, inspeccionar esquemas y ver los mensajes JSON-RPC en bruto. Imprescindible para depurar antes de conectar a un host real.

Qué construir a continuación

Una vez que dominas el patrón, los servidores MCP brillan para:

• Memoria persistente — leer/escribir un almacén JSON local para que tu agente recuerde el contexto entre sesiones
• Búsqueda consciente del proyecto — exponer búsqueda semántica sobre tu codebase mediante embeddings
• APIs internas — envolver cualquier API de empresa detrás de una interfaz tipada limpia que el modelo pueda llamar
• Control del navegador — envolver Playwright para interacción web estructurada
• CI hooks — disparar builds, leer resultados de tests, abrir PRs desde dentro de tu bucle de agente

La idea clave

MCP convierte tu agente de una interfaz de chat en un runtime programable. El modelo deja de describir lo que haría y empieza a hacerlo realmente — a través de tus llamadas a funciones tipadas, auditables y registradas. Ese es el salto del vibecoding a construir sistemas agentic reales.

20 minutos para tu primera herramienta. El resto es alcance.