MCP: conectar herramientas y fuentes
MCP ofrece un contrato entre un cliente AI y servidores que exponen herramientas o recursos. El valor no es «conectarlo todo», sino hacer explícitas, inspeccionables y limitadas a la tarea las capacidades y los datos.
Qué trabajarás, paso a paso
Cliente, servidor, herramientas, recursos y prompts
MCP, Model Context Protocol, es un contrato que permite a una aplicación con un agente descubrir y usar capacidades externas de manera estructurada. Para razonar bien sobre él debes separar quién pide, quién expone la capacidad y el sistema que realmente realiza el trabajo.
El cliente gestiona la sesión del agente. El servidor MCP puede exponer herramientas, recursos y prompts: una herramienta ejecuta una operación con entrada estructurada, un recurso proporciona contenido legible, un prompt ofrece una solicitud reutilizable. En Claude Code puedes invocar los recursos con `@`; los prompts MCP aparecen como comandos.
El servicio final, como GitHub o un filesystem, puede estar detrás del servidor. Nombres vagos y esquemas incompletos aumentan las llamadas erróneas incluso si la conexión funciona. Con Tool Search, Claude Code descubre los esquemas completos cuando hacen falta: por eso las descripciones precisas siguen siendo esenciales.
Un operador pregunta si el repuesto `BRK-204` está disponible y qué política de devolución se aplica. El sistema de gestión de almacén sigue detrás de un servidor MCP.
- El cliente descubre `getInventory`, herramienta de solo lectura con entrada obligatoria `sku`, y `return-policy`, recurso textual versionado y sin datos de cliente.
- El agente usa el recurso para leer las condiciones generales y luego propone la llamada a `getInventory` con el único código `BRK-204`.
- El servidor valida el código, consulta el sistema de gestión y devuelve cantidad, sede y hora del dato; no expone credenciales ni consultas internas.
- Si el sistema de gestión no responde, la herramienta devuelve `service_unavailable` y ninguna cantidad estimada; el operador ve que la disponibilidad no ha sido verificada.
Resultado: Política y disponibilidad siguen siendo dos capacidades reconocibles. El agente puede citar la fuente leída y no transforma un error del almacén en una respuesta inventada.
Local o remoto es una decisión de confianza
Local y remoto no describen solo dónde se ejecuta un servidor MCP. Describen un límite de confianza: qué datos salen de la máquina, qué identidad puede leerlos y de qué servicio dependes para seguir trabajando.
Un servidor local usa normalmente un proceso `stdio`; un servidor remoto usa normalmente HTTP. Local no significa offline: ese proceso aún puede llamar a Internet. Un servidor remoto centraliza actualizaciones y disponibilidad, pero envía datos más allá del límite de la máquina. Evalúa la procedencia, los datos transmitidos, la latencia y el comportamiento cuando el servicio no responde.
Dibuja el límite antes de la configuración: ¿qué datos salen, quién los recibe, cuánto tiempo existen y qué identidad autoriza la operación?
El equipo legal quiere buscar términos de renovación en una carpeta de contratos de clientes. Un servicio remoto sería más fácil de actualizar, pero recibiría el texto de los documentos.
- Clasifica los datos y traza el flujo: consulta, extractos del contrato, nombres de clientes, logs y resultados. Confirma que los documentos no estén autorizados a salir de la máquina.
- Elige un servidor local de solo lectura, confinado a la carpeta aprobada; excluye adjuntos, carpetas temporales y enlaces simbólicos que apunten a otro lugar.
- Expone `searchClauses` con consulta y límite de resultados; devuelve ruta relativa, extracto breve y página, sin copiar el documento completo en el log.
- Apaga la red durante la prueba, intenta una ruta excluida y simula un PDF ilegible; verifica que cada error sea distinto y que no se modifique ningún archivo.
Resultado: La búsqueda sigue siendo útil sin transferir los contratos. El coste de la gestión local es explícito y el perímetro está probado también en los casos de error.
Scopes y tokens mínimos
Un token es una credencial que representa una identidad y las operaciones permitidas. Los scopes son los permisos asociados. La regla práctica es simple: concede la capacidad mínima necesaria durante el tiempo mínimo necesario.
Un token no debe ser más potente que la tarea. Para leer issues no hace falta crear branches ni administrar el repositorio. Scopes estrechos limitan el daño si la credencial es robada, el servidor se ve comprometido o una solicitud es manipulada.
No muestres tokens en logs, configuraciones compartidas o capturas de pantalla. Prevé rotación y revocación. El agente debe poder explicar qué capacidad requiere cada permiso.
Un agente prepara el briefing de la mañana leyendo título, severidad y estado de los incidentes. No debe cerrarlos, modificar turnos ni ver datos de facturación.
- Enumera solo las llamadas necesarias: lista de incidentes y detalle de un incidente en el entorno de producción; ninguna operación de escritura.
- Crea una identidad de servicio dedicada con `incidents:read`, vencimiento breve y acceso solo al proyecto implicado; guarda el token en el secret store.
- Configura el servidor para que filtre los campos devueltos y enmascare posibles datos personales presentes en las notas antes de pasarlos al cliente.
- Prueba lectura válida, intento de cierre y token revocado: la primera funciona, la segunda es rechazada, la tercera produce un error de autenticación sin imprimir la credencial.
Resultado: El briefing contiene lo necesario, mientras que una llamada equivocada no puede cambiar el estado de los incidentes. La revocación se probó antes de depender de la conexión.
Handshake, prueba mínima y diagnóstico
Cuando una conexión MCP no funciona, «el servidor está roto» es una conclusión demasiado amplia. La llamada atraviesa varias capas y cada una puede fallar de una manera distinta: proceso, configuración, descubrimiento, autenticación, validación y servicio final.
El handshake es el saludo inicial con el que cliente y servidor acuerdan versión y capacidades. Después verifica la conexión por capas: configuración leída, proceso o endpoint accesible, inicialización completada, capacidades disponibles, autenticación válida y llamada mínima exitosa. En Claude Code, `/mcp` muestra el estado y la autenticación del servidor.
Los logs deben mostrar nombres de las capacidades, tiempos y errores sin revelar secretos. Si una herramienta es visible pero falla, compara el esquema de los argumentos y el scope antes de cambiar de servidor.
- Inicia y verifica que el proceso del servidor sea accesible.
- Comprueba que el cliente lea la configuración prevista.
- Inspecciona herramientas, recursos y sus esquemas descubiertos.
- Ejecuta una sola llamada de lectura con una entrada conocida.
- Registra resultado, duración y límite del fallo sin exponer tokens.
El cliente declara la conexión activa, pero el agente no ve la herramienta que debería recuperar un pedido de prueba.
- Comprueba el proceso con una solicitud de salud y confirma que el cliente use el archivo de configuración del entorno de prueba, no una copia anterior.
- Solicita la lista de capacidades: descubres que el servidor publica `get_order`, mientras la documentación y el cliente esperan `getOrder`.
- Alinea nombre y esquema, reinicia solo el componente necesario y verifica el descubrimiento antes de tocar tokens o el servicio de pedidos.
- Ejecuta una lectura sobre el pedido ficticio `TEST-104`; registra duración y estado. Después prueba ID vacío y servicio no disponible para confirmar errores distintos y sin secretos.
Resultado: La avería se atribuye al descubrimiento de capacidades, no a la autenticación. La corrección es pequeña y el conjunto de pruebas hace visibles posibles problemas posteriores.
Issue reader en solo lectura
Task Notes usa issues públicas como backlog, sin modificar el repositorio remoto.
Server: repositorio remoto verificado
Herramientas: listIssues, getIssue
Scope: contents:read, issues:read
Excluidos: createIssue, push, merge, admin
Prueba: recupera una issue conocida y registra el tiempo de respuesta