MCP server personalizzati per Claude Code: estendere il workflow aziendale con tool custom

Il 9 dicembre 2025 Anthropic ha ufficializzato una mossa strategica che molti nel settore hanno sottovalutato: la donazione del Model Context Protocol alla Linux Foundation attraverso la nuova Agentic AI Foundation, co-fondata con Block e OpenAI e con il supporto esplicito di Google, Microsoft, AWS, Cloudflare e Bloomberg. MCP è adesso un open standard governato dalla stessa organizzazione che stewarda Kubernetes, Node.js e PyTorch - e questo cambia radicalmente il calcolo architetturale per chi sta costruendo integrazioni agent-based in contesti aziendali. Fino al 2024 integrare Claude Code con il gestionale interno di un cliente significava scrivere codice vendor-specific che sarebbe diventato debito tecnico il giorno in cui avessi cambiato provider LLM; da dicembre 2025 la stessa integrazione costruita come MCP server è portabile su ChatGPT, Cursor, Gemini, Microsoft Copilot, VS Code, e il resto dell'ecosistema che ha convergato sullo standard. Nella mia pipeline personale ho costruito tra ottobre 2025 e aprile 2026 quattro MCP server PHP diversi per sperimentare il perimetro operativo dello standard, e racconto qui l'esperienza di un MCP server che sintetizza le scelte architetturali che tengo come baseline per il lavoro di consulenza.

Cosa cambia operativamente con MCP rispetto a integrazioni API tradizionali?

Claude Code fuori dalla scatola è potente per task self-contained - leggere file, eseguire comandi, analizzare stack trace - ma nei workflow aziendali complessi il valore nasce dall'integrazione con i sistemi che già costituiscono il perimetro informativo dell'azienda: database aziendali, API di gestionali proprietari, documentazione tecnica strutturata, ticket system, knowledge base interne. MCP è la risposta architetturale: un protocollo aperto che permette di esporre tool e resource strutturati all'agente LLM senza che l'agente debba "sapere" i dettagli del sistema sottostante.

La differenza rispetto a un'integrazione tradizionale via API tradizionale è di responsabilità. In un'integrazione API classica, tu scrivi prompt che dicono all'agente "se ti servono dati dal gestionale, chiama POST /api/fetch con questo payload": il contract è implicito e verbale, l'agente lo può dimenticare o interpretare male, e ogni cambiamento dell'API richiede aggiornamento del prompt. In MCP il contract è strutturato e auto-descrittivo: l'agente richiede la lista dei tool disponibili e riceve uno schema JSON formale che dichiara nomi dei parametri, tipi, vincoli, comportamento atteso; l'agente non può inventarsi tool, non può passare parametri fuori schema, e ogni chiamata è validabile prima dell'esecuzione. Il modello è contract-first invece di prompt-first, che in termini ingegneristici è la differenza tra un'API REST documentata e una API raccontata a voce.

Al 25 novembre 2025 la specifica MCP ha raggiunto una nuova release con supporto a asynchronous operations, statelessness esplicita, server identity e official extensions. Esistono oggi SDK ufficiali in Python, TypeScript, Go, Java, C# con oltre 97 milioni di download mensili. Il registry ufficiale della community lista oltre 10.000 MCP server pubblici attivi a fine 2025 - una maturità che un anno prima sarebbe stata impensabile. Il momento in cui ha senso investire nel costruire MCP server custom per un cliente è adesso: lo standard è frozen enough da garantire portabilità, new enough da evitare lock-in su vendor specifico.

Il caso concreto: MCP server per audit Laravel codebase

Nella mia pipeline personale il primo MCP server serio che ho costruito è uno strumento che espone tool strutturati per audit di codebase Laravel. Il caso d'uso specifico è quello che affronto regolarmente quando subentro su un progetto legacy: ho bisogno che Claude Code possa, in una sessione di analisi, leggere lo schema del database, ispezionare le migration storiche, correlare le model Eloquent con le tabelle reali, eseguire PHPStan su sottoinsiemi del codebase, e generare un report di debito tecnico. Senza MCP, ogni sessione iniziava con quindici minuti di back-and-forth dove Claude Code chiedeva di leggere file e io dovevo autorizzare ogni comando. Con MCP il protocollo dichiara upfront cosa l'agente può fare, l'autorizzazione è strutturata a livello di tool, e la sessione entra in regime produttivo in meno di un minuto.

Il server è scritto in PHP 8.3 (non Python, deliberatamente) perché voglio che rimanga allineato con lo stack dei progetti che audito. Le dipendenze Composer sono minimali: l'SDK ufficiale MCP per PHP mantenuto da Anthropic, un parser di schema database (doctrine/dbal), un wrapper per PHPStan CLI. Il server espone sei tool con schema JSON rigoroso:

{
  "tools": [
    {
      "name": "load_migration_history",
      "description": "Retrieves all migration files in chronological order with up/down SQL diff summary",
      "inputSchema": {"type": "object", "properties": {}}
    },
    {
      "name": "inspect_eloquent_model",
      "description": "Returns model attributes, relations, and scope methods for a given class",
      "inputSchema": {"type": "object", "required": ["class"], "properties": {"class": {"type": "string"}}}
    },
    {
      "name": "run_phpstan_on_path",
      "description": "Executes PHPStan level 6 on specified path, returns JSON findings",
      "inputSchema": {"type": "object", "required": ["path"], "properties": {"path": {"type": "string"}, "level": {"type": "integer", "minimum": 0, "maximum": 9}}}
    }
  ]
}

Il pattern di design che tengo come baseline è quello della responsabilità minima esposta: ogni tool fa una cosa sola e la fa con parametri strettamente tipizzati. Non esporre mai un tool "run_arbitrary_bash" (è la strada più corta per un disastro); non esporre tool che modificano il database o il filesystem senza un secondo gate umano. L'agente può leggere, analizzare, proporre - non può agire autonomamente su risorse produttive.

Come ho gestito i rischi di sicurezza specifici

OWASP nella Top 10 per LLM Applications 2025 classifica come LLM06 Excessive Agency il rischio di agenti con privilegi o autonomia eccessivi. Un MCP server custom che espone tool aziendali è esattamente un vettore di questo rischio se progettato senza disciplina. Nella mia pipeline ho tre controlli non negoziabili.

Il primo è il principio di privilege minimo applicato sui tool: il server non gira con credenziali di superadmin sul database, ma con un utente dedicato che ha SELECT sulle tabelle business e zero permessi di scrittura. Se per un'analisi serve scrittura (tipicamente generazione di migration proposta come diff), il tool la produce come output testuale - non la esegue. L'esecuzione resta competenza di chi fa code review del diff.

Il secondo è il logging strutturato tamper-evident: ogni chiamata dei tool è registrata in un file append-only con timestamp, input, output, caller. Il log è hash-chained - ogni entry contiene l'hash della precedente, rendendo evidente qualsiasi manomissione post-hoc. Questo non è teoria: l'incident MJ Rathbun/matplotlib documentato pubblicamente il 12 febbraio 2026 su theshamblog.com - dove un agent autonomo ha attaccato pubblicamente un maintainer open source - mostra come attack chain basate su agenti siano passate da scenario ipotetico a evidenza in-the-wild nel 2026. Il log audit-ready è la tua polizza assicurativa quando qualcosa va storto.

Il terzo è il time boxing e rate limiting delle chiamate tool. Nessun tool può essere invocato più di N volte per sessione (tipicamente N=50 per i tool di lettura, N=5 per quelli che toccano risorse costose tipo PHPStan full scan). Questo previene sia gli infinite loop accidentali dell'agente, sia il denial-of-wallet via token burning.

Se stai costruendo integrazioni agent-based su progetti PHP e vuoi una metodologia applicata per progettare MCP server sicuri e portabili, nel mio hub dedicato ai workflow AI per sviluppatori trovi raccolti gli articoli tecnici che documentano come costruisco questi strumenti nei progetti PMI.

Come Claude Code consuma i miei MCP server in sessione

Il flow operativo che tengo nella mia pipeline è il seguente. All'avvio di una sessione di audit su un nuovo codebase, Claude Code riceve nella sua configurazione il path al mio MCP server Laravel. La prima cosa che Claude Code fa autonomamente è la discovery: invoca il metodo MCP tools/list e riceve lo schema strutturato dei sei tool disponibili. A quel punto sa cosa può chiedere e come.

Durante la sessione, quando io scrivo "analizza il modello User", Claude Code non scrive bash per navigare il filesystem e trovare il file; invoca il tool inspect_eloquent_model con parametro class: "App\Models\User". Il server PHP autentica la richiesta (MCP supporta OAuth 2.1 dalla spec di marzo 2025), carica la classe via reflection con i permessi che ha ricevuto, ritorna JSON strutturato con attributes, relations, casts. Claude Code riceve l'output, lo interpreta, presenta a me una sintesi leggibile. Il roundtrip è nell'ordine dei 200-400 millisecondi, contro i 5-10 secondi di un'analisi via bash che richiederebbe 3-4 iterazioni di read-compute-decide.

Il vantaggio non è solo la velocità. È la prevedibilità: l'output del tool è strutturato, validato a schema, e non dipende dalla capacità di parsing testuale dell'agente. Un modello LLM che deve estrarre da un stack trace PHP di 200 righe il nome della classe coinvolta può sbagliare; un tool che restituisce {"class": "App\\Models\\User", "relations": [...]} non può. La spostata da prompt engineering puro a schema engineering è la seconda grande evoluzione della pratica LLM production-grade, dopo la output validation.

Quando MCP NON è lo strumento giusto

Un MCP server custom è lavoro ingegneristico non banale - almeno 200-400 righe per un server minimamente utile, più test, più documentazione. Vale la pena solo se il volume di interazioni con il sistema esposto giustifica l'investimento. I miei criteri operativi: se il task richiede meno di 5 invocazioni del sistema esterno per sessione, probabilmente non serve MCP - un prompt che dice "leggi il file X" è sufficiente. Se il task richiede 20+ invocazioni per sessione, MCP paga l'investimento nella sola velocità. Se il task è ripetuto su 10+ progetti diversi, MCP paga l'investimento nella portabilità.

Un altro caso dove MCP non è la risposta giusta è quando il sistema esterno è un'applicazione stateful complessa - un CRM con workflow multi-step, un ERP con dipendenze transazionali. Qui il confine del tool singolo diventa arbitrario, e le stesse interazioni sono più pulite se affidate a un workflow engine esterno (tipicamente basato su BPMN) invocato a sua volta via MCP come tool unitario. Mescolare logica di business process dentro il tool MCP produce server ingestibili.

La regola empirica che applico: usa MCP per esporre capacità di lettura e analisi, costruisci workflow engine separati per le azioni side-effecting. Il boundary pulito tra lettura (agente può fare libero) e azione (human-in-the-loop obbligatorio) è la linea architetturale che separa gli MCP server production-grade dalle sperimentazioni rischiose.

Cosa mi aspetto di vedere evolvere nel 2026-2027

Il report Deloitte "State of AI in the Enterprise 2026" del 21 gennaio 2026 riporta che il 75% delle aziende pianifica deployment di agent autonomi entro 2 anni ma solo il 21% ha un modello di governance agent-maturo. Questo gap strutturale è esattamente il terreno dove MCP come standard aperto può fare la differenza: senza uno standard condiviso ogni azienda costruirebbe silos proprietari, con lo standard c'è la possibilità che la governance si standardizzi a sua volta attraverso best practice comuni. Il mio investimento in MCP server PHP non è una scommessa su una singola tecnologia; è una scommessa sull'ecosistema che Linux Foundation sta stewardando.

Dal punto di vista pratico mi aspetto nei prossimi 12-18 mesi la maturazione di librerie ufficiali di authorization MCP (estensioni OAuth 2.1 specifiche per agent-to-tool), la nascita di MCP server marketplace verticali (per ERP specifici, per CRM specifici, per piattaforme e-commerce italiane), e probabilmente la comparsa di servizi managed tipo "Cloudflare MCP proxy" che semplifichino l'autenticazione e il logging. Anticiparne l'arrivo non cambia il lavoro che fai oggi: costruisci MCP server minimali, contract-first, con security non negoziabile, e sarai pronto a consumare l'ecosistema quando matura.

Un'altra evoluzione probabile è l'emergere di MCP server con auto-discovery a livello di rete aziendale: registri interni che elencano automaticamente i server disponibili e le loro capacità, permettendo agli agenti di scoprire dinamicamente gli strumenti accessibili senza configurazione statica. Questo sposterà il pain point dalla costruzione dei singoli server alla definizione di policy di discovery e trust - un problema già affrontato nel mondo service mesh con strumenti come Consul e Istio che potrebbero ispirare soluzioni equivalenti per l'ecosistema agent-based. Per chi oggi costruisce MCP server singoli è utile tenere questa evoluzione a mente: lo schema di ogni tool dovrebbe includere metadata sufficienti (versioning, categorizzazione, descrizione sintatticamente parsabile) perché un futuro registry automatico possa classificarlo correttamente senza riscrittura. Il lavoro che fai oggi sulle description dei tool è l'investimento che paghi interessi quando l'ecosistema arriva al livello successivo di maturità.

Se il tuo team sta valutando l'integrazione di agent LLM con sistemi aziendali esistenti e vuoi una qualificazione rapida su quando MCP è la strada giusta e quando invece una semplice API classica basta, il modulo di preventivo gratuito ti risponde in sette domande - circa due minuti - e ti dice se il tuo scenario rientra nel mio ambito o ti indirizzo verso figure più adatte. Per il lavoro preliminare sull'architettura Laravel che ospiterà il server, il percorso parte dalle fondamenta di qualità: trovi un inquadramento operativo nel mio articolo su audit tecnico iniziale di un progetto PHP legacy nei primi 30 giorni e nella checklist di hardening Laravel e Symfony NIS2-ready in 14 giorni. MCP su un codebase disordinato non porta ordine: porta un'interfaccia elegante al disordine. Su un codebase pulito porta vera amplificazione di produttività.