Patrones de Servidor MCP
El Protocolo de Contexto de Modelo (MCP) permite que asistentes de IA invoquen herramientas, lean recursos y usen prompts desde tu servidor. Usa esta skill al construir o mantener servidores MCP. La API del SDK evoluciona; consulta Context7 (query-docs para "MCP") o la documentación oficial de MCP para nombres y firmas de métodos actuales.
Para la decisión más amplia de enrutamiento sobre cuándo una capacidad debe ser una regla, una skill, MCP, o un flujo CLI/API simple, consulta docs/capability-surface-selection.md.
Cuándo Usar
Úsala al: implementar un nuevo servidor MCP, agregar herramientas o recursos, elegir entre stdio o HTTP, actualizar el SDK, o depurar problemas de registro y transporte en MCP.
Cómo Funciona
Conceptos clave
- Herramientas: Acciones que el modelo puede invocar (ej. búsqueda, ejecutar un comando). Regístralas con
registerTool()otool()según la versión del SDK. - Recursos: Datos de solo lectura que el modelo puede obtener (ej. contenido de archivos, respuestas de API). Regístralos con
registerResource()oresource(). Los handlers generalmente reciben un argumentouri. - Prompts: Plantillas de prompt reutilizables y parametrizadas que el cliente puede mostrar (ej. en Claude Desktop). Regístralos con
registerPrompt()o equivalente. - Transporte: stdio para clientes locales (ej. Claude Desktop); Streamable HTTP es preferido para remoto (Cursor, nube). HTTP/SSE heredado es para compatibilidad hacia atrás.
El SDK de Node/TypeScript puede exponer tool() / resource() o registerTool() / registerResource(); el SDK oficial ha cambiado con el tiempo. Siempre verifica contra la documentación actual de MCP o Context7.
Conexión con stdio
Para clientes locales, crea un transporte stdio y pásalo al método de conexión de tu servidor. La API exacta varía según la versión del SDK (ej. constructor vs fábrica). Consulta la documentación oficial de MCP o haz una consulta a Context7 para "MCP stdio server" para el patrón actual.
Mantén la lógica del servidor (herramientas + recursos) independiente del transporte para que puedas conectar stdio o HTTP en el punto de entrada.
Remoto (Streamable HTTP)
Para Cursor, nube u otros clientes remotos, usa Streamable HTTP (un único endpoint HTTP de MCP según la especificación actual). Soporta HTTP/SSE heredado solo cuando se requiera compatibilidad hacia atrás.
Ejemplos
Instalación y configuración del servidor
npm install @modelcontextprotocol/sdk zod
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
const server = new McpServer({ name: "mi-servidor", version: "1.0.0" });
Registra herramientas y recursos usando la API que proporcione tu versión del SDK: algunas versiones usan server.tool(nombre, descripción, esquema, handler) (argumentos posicionales), otras usan server.tool({ name, description, inputSchema }, handler) o registerTool(). Lo mismo para los recursos: incluye un uri en el handler cuando la API lo proporcione. Consulta la documentación oficial de MCP o Context7 para las firmas actuales de @modelcontextprotocol/sdk para evitar errores de copia y pega.
Usa Zod (o el formato de esquema preferido del SDK) para la validación de entrada.
Mejores Prácticas
- Primero el esquema: Define esquemas de entrada para cada herramienta; documenta los parámetros y la forma de retorno.
- Errores: Devuelve errores estructurados o mensajes que el modelo pueda interpretar; evita trazas de pila crudas.
- Idempotencia: Prefiere herramientas idempotentes cuando sea posible para que los reintentos sean seguros.
- Tasa y costo: Para herramientas que llaman a APIs externas, considera límites de tasa y costo; documéntalo en la descripción de la herramienta.
- Versionado: Fija la versión del SDK en package.json; revisa las notas de lanzamiento al actualizar.
SDKs y Documentación Oficial
- JavaScript/TypeScript:
@modelcontextprotocol/sdk(npm). Usa Context7 con el nombre de librería "MCP" para patrones actuales de registro y transporte. - Go: SDK oficial de Go en GitHub (
modelcontextprotocol/go-sdk). - C#: SDK oficial de C# para .NET.