Patrones de Servidor MCP
El Protocolo de Contexto de Modelo (MCP) permite a los asistentes de IA invocar herramientas, leer recursos y usar prompts desde tu servidor. Usa este 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 obtener los nombres y firmas de métodos actuales.
Para la decisión más amplia de cuándo una capacidad debe ser una regla, un skill, MCP o un flujo CLI/API simple, consulta docs/capability-surface-selection.md.
Cuándo Usarlo
Úsalo cuando: implementes un nuevo servidor MCP, añadas herramientas o recursos, elijas entre stdio y HTTP, actualices el SDK, o depures problemas de registro y transporte en MCP.
Cómo Funciona
Conceptos Clave
- Herramientas: Acciones que el modelo puede invocar (ej. buscar, ejecutar un comando). Se registran 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). Se registran con
registerResource()oresource(). Los manejadores suelen recibir un argumentouri. - Prompts: Plantillas de prompt reutilizables y parametrizadas que el cliente puede mostrar (ej. en Claude Desktop). Se registran con
registerPrompt()o equivalente. - Transporte: stdio para clientes locales (ej. Claude Desktop); se prefiere Streamable HTTP para acceso remoto (Cursor, cloud). 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 connect 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 busca en Context7 "MCP stdio server" para el patrón actual.
Mantén la lógica del servidor (herramientas + recursos) independiente del transporte para poder conectar stdio o HTTP en el punto de entrada.
Remoto (Streamable HTTP)
Para Cursor, cloud 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: "my-server", version: "1.0.0" });
Registra herramientas y recursos usando la API que proporciona tu versión del SDK: algunas versiones usan server.tool(nombre, descripción, esquema, manejador) (argumentos posicionales), otras usan server.tool({ name, description, inputSchema }, handler) o registerTool(). Lo mismo para los recursos: incluye una uri en el manejador cuando la API lo proporcione. Consulta la documentación oficial de MCP o Context7 para las firmas actuales de @modelcontextprotocol/sdk y evitar errores de copia y pegado.
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 la respuesta.
- Errores: Devuelve errores estructurados o mensajes que el modelo pueda interpretar; evita trazas de pila sin procesar.
- Idempotencia: Prefiere herramientas idempotentes cuando sea posible para que los reintentos sean seguros.
- Tasa y costo: Para herramientas que llaman APIs externas, considera límites de tasa y costos; documéntalo en la descripción de la herramienta.
- Versionado: Fija la versión del SDK en package.json; revisa las notas de versión 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.