Cómo crear un plugin MCP para conectarse a una API REST en Node.js

¿Qué es un plugin MCP y para qué sirve?

Un plugin MCP (Model Context Protocol) es una extensión que permite a modelos de lenguaje como Claude acceder a herramientas externas, como APIs REST, bases de datos o sistemas de archivos. La idea es que el modelo pueda ejecutar acciones concretas en el mundo real, como consultar datos, enviar información o modificar recursos, todo desde una conversación natural. Al crear un plugin MCP para una API REST en Node.js, consigues que tu asistente pueda interactuar con servicios web de manera estructurada y segura, sin necesidad de intervención manual cada vez. Esto es especialmente útil si trabajas con sistemas internos, dashboards o cualquier servicio que tenga una interfaz HTTP.

Estructura básica de un plugin MCP

Un plugin MCP se compone de tres elementos principales: la definición del servidor, las herramientas (tools) y los recursos (resources). En Node.js, lo más común es usar el paquete @modelcontextprotocol/sdk para construir el servidor. La estructura típica incluye un archivo package.json con las dependencias, un archivo index.js donde configuras el servidor y defines las herramientas, y un archivo .env para variables sensibles como tokens de API. La conexión a la API REST se hace mediante axios o fetch dentro de cada herramienta. El servidor MCP expone estas herramientas para que el modelo las invoque cuando el usuario haga una petición relevante.

Para empezar, crea un proyecto nuevo con npm init e instala las dependencias:

• npm install @modelcontextprotocol/sdk

• npm install axios dotenv

Luego, crea un archivo index.js con la configuración básica del servidor MCP. Aquí defines un servidor que escucha en un puerto local (por ejemplo, 3000) y que expone herramientas que llaman a tu API REST. Cada herramienta tiene un nombre, una descripción y un esquema de parámetros. El modelo usa esa descripción para decidir cuándo invocar la herramienta y qué parámetros enviar.

Implementación paso a paso: herramientas para una API REST

Imagina que tienes una API REST de gestión de tareas (como un TODO list) con endpoints como GET /tasks, POST /tasks y DELETE /tasks/:id. Quieres que tu plugin MCP permita al modelo listar, crear y eliminar tareas. Para ello, defines tres herramientas: listar_tareas, crear_tarea y eliminar_tarea. Cada herramienta se registra en el servidor MCP con un nombre único y un esquema JSON que describe los parámetros esperados.

Aquí tienes un ejemplo de cómo definir la herramienta listar_tareas:

PROMPTconst { Server } = require('@modelcontextprotocol/sdk/server');

const axios = require('axios');

const server = new Server({

name: 'task-manager-mcp',

version: '1.0.0'

});

server.tool('listar_tareas', {

// sin parámetros requeridos

}, async (args) => {

try {

const response = await axios.get('https://api.ejemplo.com/tasks');

return {

content: [{ type: 'text', text: JSON.stringify(response.data) }]

};

} catch (error) {

return {

content: [{ type: 'text', text: 'Error al obtener tareas: ' + error.message }]

};

}

});

Para la herramienta crear_tarea, necesitas un parámetro titulo y otro descripcion. El esquema se define así:

PROMPTserver.tool('crear_tarea', {

titulo: { type: 'string', description: 'Título de la tarea' },

descripcion: { type: 'string', description: 'Descripción de la tarea' }

}, async (args) => {

try {

const response = await axios.post('https://api.ejemplo.com/tasks', {

titulo: args.titulo,

descripcion: args.descripcion

});

return {

content: [{ type: 'text', text: Tarea creada con ID: ${response.data.id} }]

};

} catch (error) {

return {

content: [{ type: 'text', text: 'Error al crear tarea: ' + error.message }]

};

}

});

Finalmente, para eliminar una tarea, defines un parámetro id:

PROMPTserver.tool('eliminar_tarea', {

id: { type: 'number', description: 'ID de la tarea a eliminar' }

}, async (args) => {

try {

await axios.delete(https://api.ejemplo.com/tasks/${args.id});

return {

content: [{ type: 'text', text: 'Tarea eliminada correctamente' }]

};

} catch (error) {

return {

content: [{ type: 'text', text: 'Error al eliminar tarea: ' + error.message }]

};

}

});

Luego, inicia el servidor con server.listen(3000) y listo. Ahora, cuando el modelo reciba un mensaje como "muéstrame mis tareas", invocará la herramienta listar_tareas y devolverá el resultado al usuario.

Tip para depurar y probar tu plugin MCP

Para probar tu plugin MCP localmente sin necesidad de conectarlo a un modelo de lenguaje, puedes usar el comando npx @modelcontextprotocol/inspector en la terminal. Esta herramienta abre una interfaz web en tu navegador donde puedes simular invocaciones a tus herramientas, ver los logs de las peticiones y depurar errores de conexión con la API REST. Es ideal para verificar que cada herramienta funciona antes de integrarla con Claude u otro asistente.

Consideraciones de seguridad y buenas prácticas

Al conectar un plugin MCP a una API REST, ten en cuenta que el modelo puede invocar las herramientas en cualquier momento. Por eso es importante limitar los endpoints expuestos solo a los necesarios y nunca incluir tokens o contraseñas directamente en el código. Usa variables de entorno para almacenar claves de API y valida los parámetros de entrada en cada herramienta para evitar inyecciones. Además, implementa un manejo de errores robusto: si la API responde con un error (por ejemplo, 404 o 500), el plugin debe devolver un mensaje claro al usuario, no solo un código de estado. También es recomendable agregar un límite de tiempo (timeout) a las peticiones HTTP para que el plugin no se cuelgue si la API tarda en responder.

Otra buena práctica es documentar bien cada herramienta con descripciones precisas en el esquema. El modelo usa esas descripciones para decidir qué herramienta llamar, así que sé específico: en lugar de "obtener datos", usa "obtener lista de tareas pendientes". Esto mejora la precisión del asistente y evita invocaciones incorrectas. Finalmente, prueba el plugin con diferentes escenarios: consultas exitosas, errores de red, parámetros faltantes o incorrectos. Cuanto más robusto sea el plugin, mejor será la experiencia del usuario final.

Herramienta

Endpoint API

Parámetros

listar_tareas

GET /tasks

Ninguno

crear_tarea

POST /tasks

titulo, descripcion

eliminar_tarea

DELETE /tasks/:id

id

Con estos pasos, ya tienes un plugin MCP funcional que conecta a una API REST en Node.js. Puedes extenderlo fácilmente añadiendo más herramientas (por ejemplo, actualizar tareas o filtrar por estado) o conectándolo a APIs más complejas como servicios de autenticación, bases de datos externas o microservicios. La clave está en mantener la estructura clara y la documentación actualizada para que el modelo interprete correctamente cada acción.