Construyendo Tu Primer Servidor MCP

Configurando el Proyecto

Vamos a construir un MCP server real desde cero usando TypeScript. Comienza inicializando tu proyecto:

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

Configura "module": "node16" y "moduleResolution": "node16" en tu tsconfig.json. Los MCP servers usan ES modules, así que agrega "type": "module" a tu package.json.

Definiendo Tu Primer Tool

Crea src/index.ts. El SDK proporciona una clase McpServer que maneja todos los detalles del protocolo:

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

server.tool(
  "get-weather",
  "Get current weather for a city",
  { city: z.string().describe("City name") },
  async ({ city }) => {
    // En producción, llama a una API real de clima
    return {
      content: [
        { type: "text", text: `Weather in ${city}: 22°C, partly cloudy` },
      ],
    };
  }
);

El método server.tool() toma cuatro argumentos: un nombre, una descripción (usada por el modelo de IA para decidir cuándo llamarlo), un schema Zod para validación de entrada, y una función handler async.

Agregando Resources

Los resources le dan al modelo acceso de lectura a datos. Agreguemos un resource de configuración:

server.resource(
  "config",
  "app://config/current",
  { description: "Current application configuration" },
  async () => ({
    contents: [
      {
        uri: "app://config/current",
        text: JSON.stringify({ env: "production", debug: false }),
        mimeType: "application/json",
      },
    ],
  })
);

Conectando el Transporte

El paso final es conectar el transporte e iniciar el server:

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

Compila con npx tsc y tu server está listo.

Testeando con MCP Inspector

Antes de conectar a un host real, prueba con el MCP Inspector — una herramienta basada en navegador para depurar MCP servers:

npx @modelcontextprotocol/inspector node dist/index.js

El Inspector muestra todos los tools, resources y prompts registrados. Puedes invocarlos interactivamente y ver el ciclo completo de request/response.

Conectando a Claude Desktop

Agrega tu server al archivo de configuración de Claude Desktop (claude_desktop_config.json):

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

Reinicia Claude Desktop y tus tools aparecen automáticamente. Claude los llamará cuando sean relevantes para la conversación.

Conectando a Claude Code

Para Claude Code, agrega el server al .mcp.json de tu proyecto:

{
  "mcpServers": {
    "my-first-server": {
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

Claude Code lo detecta inmediatamente — tus tools están disponibles en el flujo de trabajo de código.

Ejemplos en Producción

Los servers de clima simples están bien para aprender, pero los MCP servers escalan a uso serio en producción. MCP-Vanguard expone 89 tools de seguridad — desde escaneo de vulnerabilidades hasta threat intelligence — todo a través de un único MCP server. InfraOps-MCP proporciona 92 tools de gestión de infraestructura para Docker, monitoreo de sistemas, networking y más.

Estos proyectos demuestran el patrón: toma el tooling y expertise existente de tu equipo, envuélvelo en MCP tools bien tipados con descripciones claras, y de repente todo tu flujo de trabajo potenciado por IA tiene acceso a ello.

En la siguiente lección, exploraremos cómo diseñar los agentes que usan estos tools de forma efectiva.