De la idea a un servidor MCP funcionando: qué herramientas exponer, cómo diseñar sus parámetros, qué devolver, cómo tratar los permisos y qué probar antes de conectarlo a nada importante.
Cuándo usarlo: Diseñar e implementar un servidor MCP propio para exponer un sistema interno a un asistente de IA con control de permisos y auditoría
Herramienta recomendada: Claude Code
Actúa como ingeniero con experiencia construyendo servidores MCP (Model Context Protocol) en producción. Quiero exponer un sistema interno a un asistente de IA mediante un servidor propio. ## Contexto que necesito 1. Qué sistema quieres exponer y qué operaciones tiene disponibles (API, base de datos, servicio interno). 2. Qué quieres que el asistente pueda hacer y qué NO debe poder hacer nunca. 3. Lenguaje y entorno de ejecución preferidos. 4. Quién lo va a usar: solo tú, tu equipo o toda la empresa. ## Paso 0 — La pregunta previa ¿De verdad hace falta un servidor MCP? Si el trasiego de datos entre sistemas ocurre una vez a la semana, un script y un prompt bien escrito cuestan una décima parte de mantenimiento. Dime honestamente si mi caso lo justifica antes de escribir código. ## Paso 1 — Diseño de las herramientas Para cada operación a exponer, define: | Campo | Criterio | |---|---| | Nombre | Verbo + objeto, sin ambigüedad: `buscar_pedido`, no `pedidos` | | Descripción | Qué hace, cuándo usarla y cuándo NO. Es lo que decide si el modelo la elige bien | | Parámetros | Los mínimos, con tipos estrictos y valores permitidos enumerados | | Salida | Datos estructurados y acotados; nunca volcados enormes | | Efecto | Solo lectura o escritura, declarado explícitamente | Regla de oro del diseño: una herramienta que devuelve 20.000 tokens de JSON es una herramienta que nadie puede usar bien. Pagina, resume y ofrece un parámetro de detalle. ## Paso 2 — Separar lectura de escritura Empieza exponiendo solo lectura. Añade escritura cuando el uso real esté probado, y entonces: - Cada operación de escritura devuelve qué cambió exactamente. - Las operaciones destructivas no se exponen, o exigen confirmación explícita fuera del modelo. - Todo queda registrado: quién, qué herramienta, con qué parámetros y con qué resultado. ## Paso 3 — Seguridad Trata todo el contenido que entra por el servidor como datos, nunca como instrucciones: un ticket, un correo o una fila de base de datos pueden contener texto dirigido al asistente. Diseña en consecuencia: 1. Credenciales del lado del servidor, nunca en el contexto del modelo. 2. Permisos mínimos: el servidor solo puede lo que necesita para sus herramientas. 3. Validación de parámetros en el servidor, sin confiar en el esquema. 4. Límites de frecuencia y de tamaño de respuesta. 5. Registro de auditoría revisable. ## Paso 4 — Implementación y pruebas Entrega el código del servidor con: - Definición de las herramientas con sus esquemas. - Manejo de errores que devuelve mensajes útiles para el modelo (qué ha fallado y qué hacer), no trazas internas. - Pruebas: cada herramienta con parámetros válidos, inválidos, vacíos y maliciosos. - Instrucciones de conexión y de configuración local. ## Entregables 1. Veredicto sobre si mi caso justifica el servidor. 2. Tabla de diseño de herramientas con nombres, descripciones y esquemas. 3. Código del servidor funcionando, comentado en los puntos no obvios. 4. Batería de pruebas y cómo ejecutarla. 5. Lista de comprobación de seguridad antes de conectarlo a datos reales.