Integrar un servidor MCP dentro de una aplicación Laravel
Los agentes de IA necesitan algo más que una interfaz web extraída (scraped). Necesitan una forma de llamar a herramientas específicas con los permisos adecuados. Esto es lo que hace el Model Context Protocol (MCP).
Recientemente integré un servidor MCP directamente en una aplicación Laravel. Quiero compartir las decisiones arquitectónicas para construir esto de forma segura.
La metáfora del recepcionista Imagina que tu aplicación es un edificio de oficinas.
- La interfaz web es el vestíbulo para los humanos.
- La API REST es la entrada de empleados para los sistemas.
- El servidor MCP es un mostrador de recepción para los agentes de IA.
El agente muestra una identificación y solicita una tarea específica. El recepcionista no les entrega las llaves del edificio. Verifica los permisos, realiza una tarea y devuelve una respuesta estructurada.
Decisiones de diseño clave
Usar un único endpoint No crees muchas rutas para diferentes herramientas. Usa un único endpoint
/mcp. El protocolo gestiona el descubrimiento de herramientas automáticamente. Una única superficie es más fácil de asegurar y documentar.Soportar autenticación dual Diferentes clientes necesitan diferentes métodos de seguridad:
- Los clientes de primera parte (como herramientas CLI) utilizan tokens de acceso personal de Sanctum.
- Los agentes de terceros (que actúan en nombre de los usuarios) utilizan OAuth 2.1.
Usa un resolver de tipo driver para gestionar ambos. El código de la herramienta solo debe preocuparse por el usuario autenticado, no por cómo inició sesión.
Aplicar el RBAC existente La autenticación solo demuestra quién es el cliente. Aún debes verificar qué puede hacer. Cada herramienta debe mapearse a una capacidad (ability) existente. Si un usuario no puede ver a los participantes en la interfaz web, no debería poder hacerlo a través de MCP.
Limitar la salida de datos Nunca devuelvas un modelo de base de datos completo. Trata la salida de MCP como una API pública. Devuelve solo los campos específicos que el agente necesita. Esto evita filtraciones de datos accidentales.
Pruebas de seguridad Tus pruebas deben demostrar que el sistema falla correctamente. Prueba que:
- Un usuario no autorizado recibe un error 403 Forbidden.
- Un usuario autorizado recibe solo los campos permitidos.
Una buena suite de pruebas es tu mejor defensa contra las filtraciones de datos al usar agentes autónomos.
Resumen Para construir un servidor MCP responsable, sigue estas tres reglas:
- Autentica a cada cliente utilizando el esquema correcto.
- Autoriza cada herramienta utilizando tu modelo de permisos existente.
- Trata cada salida de herramienta como un recurso público limitado.