Inserire un server MCP all'interno di un'app Laravel
Gli agenti AI hanno bisogno di qualcosa di più di una semplice UI sottoposta a scraping. Hanno bisogno di un modo per chiamare strumenti specifici con i permessi corretti. Questo è ciò che fa il Model Context Protocol (MCP).
Recentemente ho integrato un server MCP direttamente in un'applicazione Laravel. Voglio condividere le decisioni architettoniche prese per costruirlo in modo sicuro.
La metafora della receptionist Immagina la tua app come un edificio per uffici.
- L'interfaccia web è la hall per gli umani.
- L'API REST è l'ingresso del personale per i sistemi.
- Il server MCP è il banco della reception per gli agenti AI.
L'agente mostra un documento d'identità e richiede un compito specifico. La receptionist non consegna loro le chiavi dell'edificio. Controlla i permessi, esegue un singolo compito e restituisce una risposta strutturata.
Decisioni di progettazione chiave
Utilizzare un singolo endpoint Non creare molte rotte per diversi strumenti. Usa un unico endpoint
/mcp. Il protocollo gestisce automaticamente la scoperta degli strumenti (tool discovery). Una singola superficie è più facile da mettere in sicurezza e documentare.Supportare la doppia autenticazione Diversi chiamanti necessitano di diversi metodi di sicurezza:
- I chiamanti di prima parte (come gli strumenti CLI) utilizzano i token di accesso personale di Sanctum.
- Gli agenti di terze parti (che agiscono per conto degli utenti) utilizzano OAuth 2.1.
Usa un resolver in stile "driver" per gestire entrambi. Il codice dello strumento dovrebbe occuparsi solo dell'utente autenticato, non di come ha effettuato l'accesso.
Applicare l'RBAC esistente L'autenticazione prova solo chi è il chiamante. Devi comunque controllare cosa può fare. Ogni strumento dovrebbe mappare un'abilità (ability) esistente. Se un utente non può visualizzare i partecipanti nell'interfaccia web, non dovrebbe poterlo fare tramite MCP.
Limitare l'output dei dati Non restituire mai un modello di database completo. Tratta l'output di MCP come un'API pubblica. Restituisci solo i campi specifici di cui l'agente ha bisogno. Questo evita perdite accidentali di dati.
Test per la sicurezza I tuoi test devono dimostrare che il sistema fallisce correttamente. Testa che:
- Un utente non autorizzato riceva un errore 403 Forbidden.
- Un utente autorizzato riceva solo i campi consentiti.
Una buona suite di test è la tua migliore difesa contro le perdite di dati quando utilizzi agenti autonomi.
Sintesi Per costruire un server MCP responsabile, segui queste tre regole:
- Autentica ogni chiamante utilizzando lo schema corretto.
- Autorizza ogni strumento utilizzando il tuo modello di permessi esistente.
- Tratta ogni output dello strumento come una risorsa pubblica limitata.