Cómo crear tu primera herramienta MCP en 30 minutos (con plantilla descargabl...

Si eres desarrollador y has escuchado hablar del protocolo MCP (Model Context Protocol) pero aún no lo has probado, este tutorial es para ti. En menos de media hora tendrás tu primera herramienta funcionando, lista para conectar con asistentes de IA como Claude Desktop o cualquier cliente compatible.

¿Qué necesitas antes de empezar?

• Node.js 18+ instalado
• Un editor de código (VS Code recomendado)
• Conocimientos básicos de JavaScript/TypeScript
• ganas de ensuciarte las manos

No necesitas experiencia previa con MCP. Vamos directo al grano.

1. Configuración del proyecto (5 minutos)

Crea una carpeta para tu proyecto y ejecuta:

PROMPTmkdir mi-primer-mcp cd mi-primer-mcp npm init -y Instala las dependencias necesarias:

PROMPTnpm install @modelcontextprotocol/sdk npm install -D typescript @types/node Crea un archivo tsconfig.json básico:

PROMPT{ "compilerOptions": { "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext", "outDir": "./dist", "rootDir": "./src", "strict": true, "esModuleInterop": true }, "include": ["src//*"] } 💡 Tip: Si prefieres JavaScript, puedes omitir TypeScript. El SDK funciona igual, solo cambia la extensión a .js y elimina los tipos.

2. Escribe tu primera herramienta (15 minutos)

Crea la carpeta src y dentro un archivo index.ts. Aquí va el código completo de tu herramienta:

PROMPTimport { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js"; // 1. Define tu herramienta const CALCULADORA_TOOL = { name: "calculadora", description: "Realiza operaciones aritméticas básicas", inputSchema: { type: "object", properties: { operacion: { type: "string", enum: ["suma", "resta", "multiplica", "divide"], description: "Tipo de operación", }, a: { type: "number", description: "Primer número", }, b: { type: "number", description: "Segundo número", }, }, required: ["operacion", "a", "b"], }, }; // 2. Crea el servidor MCP const server = new Server( { name: "calculadora-mcp", version: "1.0.0", }, { capabilities: { tools: {}, }, } ); // 3. Maneja la solicitud de listar herramientas server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [CALCULADORA_TOOL], })); // 4. Ejecuta la lógica de la herramienta server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; if (name !== "calculadora") { throw new Error(Herramienta desconocida: ${name}); } const { operacion, a, b } = args as { operacion: string; a: number; b: number; }; let resultado: number; switch (operacion) { case "suma": resultado = a + b; break; case "resta": resultado = a - b; break; case "multiplica": resultado = a * b; break; case "divide": if (b === 0) { return { content: [ { type: "text", text: "Error: No se puede dividir por cero", }, ], isError: true, }; } resultado = a / b; break; default: throw new Error(Operación no soportada: ${operacion}); } return { content: [ { type: "text", text: Resultado de ${operacion}: ${resultado}, }, ], }; }); // 5. Inicia el servidor async function main() { const transport = new StdioServerTransport(); await server.connect(transport); console.error("Servidor MCP de calculadora iniciado"); } main().catch((error) => { console.error("Error fatal:", error); process.exit(1); }); 🔧 Prompt funcional: Copia y pega este código. Luego ejecuta npx tsc para compilar a JavaScript. Si todo sale bien, tendrás tu herramienta lista en dist/index.js.

3. Prueba local y conexión (5 minutos)

Primero, prueba que tu servidor responde correctamente. Desde la terminal ejecuta:

PROMPTnode dist/index.js No verás nada porque espera entrada por STDIO. Para probarlo, usa este comando en otra terminal:

PROMPTecho '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js Deberías ver una respuesta JSON con el listado de herramientas. Si ves algo como {"jsonrpc":"2.0","id":1,"result":{"tools":[...]}}, ¡felicidades! Tu MCP funciona.

Para una prueba más completa, puedes enviar una solicitud de ejecución:

PROMPTecho '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"calculadora","arguments":{"operacion":"suma","a":5,"b":3}}}' | node dist/index.js

4. Conecta con Claude Desktop (5 minutos)

Ahora vamos a conectar tu herramienta con Claude Desktop:

• Abre Claude Desktop
• Ve a Configuración > Desarrollador > Editar Configuración
• Agrega esta configuración en claude_desktop_config.json:

PROMPT{ "mcpServers": { "calculadora": { "command": "node", "args": ["ruta/absoluta/hacia/tu/proyecto/dist/index.js"] } } } Reemplaza ruta/absoluta/hacia/tu/proyecto con la ruta completa donde creaste el proyecto.

• Guarda el archivo y reinicia Claude Desktop
• Verás un ícono de martillo 🔨 en la interfaz indicando que hay herramientas disponibles

Ahora puedes pedirle a Claude: "Usa la calculadora para sumar 15 y 27" y verás cómo ejecuta tu herramienta.

⚡ Tip profesional: Para desarrollo, activa el modo verbose añadiendo "env": { "DEBUG": "mcp:*" } en la configuración. Esto te mostrará logs detallados de cada petición en la terminal de Claude.

Plantilla descargable

Para ahorrarte tiempo, aquí tienes una plantilla lista para usar. Crea un archivo plantilla-mcp.sh y ejecútalo:

PROMPT#!/bin/bash Plantilla MCP - Crea tu proyecto en segundos NOMBRE=${1:-"mi-herramienta-mcp"} mkdir $NOMBRE && cd $NOMBRE npm init -y npm install @modelcontextprotocol/sdk mkdir src cat > src/index.js ({ tools: [MI_HERRAMIENTA], })); server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; if (name !== "saludar") throw new Error(Herramienta desconocida: ${name}); return { content: [{ type: "text", text: ¡Hola, ${args.nombre}! Bienvenido a MCP. }], }; }); const transport = new StdioServerTransport(); await server.connect(transport); console.error("Servidor MCP iniciado"); EOF echo "Proyecto $NOMBRE creado. Ejecuta: cd $NOMBRE && node src/index.js" Guárdalo como crear-mcp.sh, dale permisos con chmod +x crear-mcp.sh y ejecuta ./crear-mcp.sh mi-calculadora. Tendrás una base funcional en segundos.

¿Y ahora qué?

Ya tienes tu primera herramienta MCP funcionando. Los siguientes pasos naturales son:

• Añadir más herramientas al mismo servidor (solo agrega más objetos al array)
• Conectarte a APIs externas (clima, noticias, bases de datos)
• Implementar autenticación y rate limiting
• Publicar tu herramienta como paquete npm

El protocolo MCP está diseñado para ser minimalista por diseño. Con lo que has aprendido hoy, puedes extenderlo a cualquier caso de uso que imagines. Lo importante es mantener el contrato de comunicación limpio y predecible.

Ahora ve y construye algo útil para la comunidad de IA.