Integrazione MCP (accesso per strumenti IA)¶

Turbo EA include un server MCP (Model Context Protocol) integrato che consente agli strumenti di IA — come Claude Desktop, GitHub Copilot, Cursor e VS Code — di interrogare e aggiornare i dati EA direttamente. Gli strumenti di IA possono inoltre caricare artefatti (fogli di calcolo, diagrammi BPMN, diagrammi DrawIO, documenti liberi) e trasformarli in card, relazioni e diagrammi che rispettano il metamodello esistente. Gli utenti si autenticano tramite il loro provider SSO esistente, e ogni azione rispetta i loro permessi individuali.

Questa funzionalità è opzionale e non si avvia automaticamente. Richiede che l'SSO sia configurato, che il profilo MCP sia attivato in Docker Compose e che un amministratore lo abiliti nell'interfaccia delle impostazioni.

Come funziona¶

Strumento IA (Claude, Copilot, ecc.)
    │
    │  Protocollo MCP (HTTP + SSE)
    ▼
Server MCP di Turbo EA (:8001, interno)
    │
    │  OAuth 2.1 con PKCE
    │  delega al provider SSO
    ▼
Backend Turbo EA (:8000)
    │
    │  RBAC per utente
    ▼
PostgreSQL

Un utente aggiunge l'URL del server MCP al proprio strumento IA.
Alla prima connessione, lo strumento IA apre una finestra del browser per l'autenticazione SSO.
Dopo il login, il server MCP emette il proprio token di accesso (supportato dal JWT Turbo EA dell'utente).
Lo strumento IA utilizza questo token per tutte le richieste successive. I token si rinnovano automaticamente.
Ogni query passa attraverso il normale sistema di permessi di Turbo EA — gli utenti vedono solo i dati a cui hanno accesso.

Prerequisiti¶

Prima di abilitare MCP, è necessario avere:

SSO configurato e funzionante — MCP delega l'autenticazione al provider SSO (Microsoft Entra ID, Google Workspace, Okta o OIDC generico). Consultare la guida Autenticazione e SSO.
HTTPS con un dominio pubblico — Il flusso OAuth richiede un URI di reindirizzamento stabile. Distribuire dietro un reverse proxy con terminazione TLS (Caddy, Traefik, Cloudflare Tunnel, ecc.).

Configurazione¶

Passaggio 1: Avviare il servizio MCP¶

Il server MCP è un profilo opzionale di Docker Compose. Aggiungere --profile mcp al comando di avvio:

docker compose --profile mcp up --build -d

Questo avvia un container Python leggero (porta 8001, solo interno) accanto al backend e frontend. Nginx reindirizza automaticamente le richieste /mcp/ verso di esso.

Passaggio 2: Configurare le variabili d'ambiente¶

Aggiungere queste al file .env:

TURBO_EA_PUBLIC_URL=https://il-tuo-dominio.esempio.com
MCP_PUBLIC_URL=https://il-tuo-dominio.esempio.com/mcp

Variabile	Predefinito	Descrizione
`TURBO_EA_PUBLIC_URL`	`http://localhost:8920`	L'URL pubblico dell'istanza Turbo EA
`MCP_PUBLIC_URL`	`http://localhost:8920/mcp`	L'URL pubblico del server MCP (usato negli URI di reindirizzamento OAuth)
`MCP_PORT`	`8001`	Porta interna del container MCP (raramente necessita di modifica)

Passaggio 3: Aggiungere l'URI di reindirizzamento OAuth all'app SSO¶

Nella registrazione dell'applicazione del provider SSO (la stessa configurata per il login di Turbo EA), aggiungere questo URI di reindirizzamento:

https://il-tuo-dominio.esempio.com/mcp/oauth/callback

Questo è necessario per il flusso OAuth che autentica gli utenti quando si connettono dal loro strumento IA.

Passaggio 4: Abilitare MCP nelle impostazioni di amministrazione¶

Andare su Impostazioni nell'area di amministrazione e selezionare la scheda AI.
Scorrere fino alla sezione Integrazione MCP (Accesso strumenti IA).
Attivare l'interruttore per abilitare MCP.
L'interfaccia mostrerà l'URL del server MCP e le istruzioni di configurazione da condividere con il team.

Warning

L'interruttore è disabilitato se l'SSO non è configurato. Configurare prima l'SSO.

Connettere gli strumenti IA¶

Una volta abilitato MCP, condividere l'URL del server MCP con il team. Ogni utente lo aggiunge al proprio strumento IA:

Claude Desktop¶

Aprire Impostazioni > Connettori > Aggiungi connettore personalizzato.
Inserire l'URL del server MCP: https://il-tuo-dominio.esempio.com/mcp
Fare clic su Connetti — si apre una finestra del browser per il login SSO.
Dopo l'autenticazione, Claude può interrogare i dati EA.

VS Code (GitHub Copilot / Cursor)¶

Aggiungere al file .vscode/mcp.json del workspace:

{
  "servers": {
    "turbo-ea": {
      "type": "http",
      "url": "https://il-tuo-dominio.esempio.com/mcp/mcp"
    }
  }
}

Il doppio /mcp/mcp è intenzionale — il primo /mcp/ è il percorso del proxy Nginx, il secondo è l'endpoint del protocollo MCP.

Test locale (modalità stdio)¶

Per lo sviluppo locale o i test senza SSO/HTTPS, è possibile eseguire il server MCP in modalità stdio — Claude Desktop lo avvia direttamente come processo locale.

1. Installare il pacchetto del server MCP:

pip install ./mcp-server

2. Aggiungere alla configurazione di Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "turbo-ea": {
      "command": "python",
      "args": ["-m", "turbo_ea_mcp", "--stdio"],
      "env": {
        "TURBO_EA_URL": "http://localhost:8000",
        "TURBO_EA_EMAIL": "tua@email.com",
        "TURBO_EA_PASSWORD": "tua-password"
      }
    }
  }
}

In questa modalità, il server si autentica con email/password e rinnova il token automaticamente in background.

Funzionalità disponibili¶

Il server MCP espone 30 strumenti suddivisi in due gruppi: 25 strumenti di lettura che interrogano i dati EA e 5 strumenti di scrittura che trasformano gli artefatti che uno strumento di IA ha nel proprio contesto (fogli di calcolo, BPMN XML, DrawIO XML, documenti, immagini) in card, relazioni e diagrammi.

Sicurezza tramite esecuzione di prova nelle scritture¶

Ogni strumento di scrittura usa per impostazione predefinita dry_run=true. In questa modalità il backend esegue ogni validatore e risolutore, costruisce il piano completo e poi annulla la transazione in modo che nulla venga persistito. Lo strumento di IA restituisce l'anteprima all'utente; solo dopo conferma esplicita deve richiamare lo strumento con dry_run=false per confermare. Questo evita che un agente troppo zelante crei silenziosamente centinaia di card a partire da un foglio di calcolo interpretato male.

Strumenti di lettura¶

Il server espone 25 strumenti di lettura raggruppati in sei cluster.

Card & metamodello

Strumento	Descrizione
`search_cards`	Cercare e filtrare le card per tipo, stato o testo libero
`get_card`	Ottenere i dettagli completi di una card tramite UUID
`get_card_relations`	Ottenere tutte le relazioni connesse a una card
`get_card_hierarchy`	Ottenere antenati e figli di una card
`list_card_types`	Elencare tutti i tipi di card nel metamodello
`get_relation_types`	Elencare i tipi di relazione, con filtro opzionale per tipo di card

Dashboard

Strumento	Descrizione
`get_dashboard`	Dashboard KPI (conteggi, qualità dei dati, approvazioni, attività)
`get_landscape`	Card di un tipo raggruppate per un tipo correlato

GRC — Registro dei rischi

Strumento	Descrizione
`list_risks`	Elenco paginato e filtrabile dei rischi EA (TOGAF Fase G)
`get_risk`	Dettaglio di un rischio con card collegate e percorso di audit
`get_risk_metrics`	KPI + matrici 4×4 iniziale e residua
`get_card_risks`	Tutti i rischi attualmente collegati a una card

GRC — Conformità

Strumento	Descrizione
`list_compliance_findings`	Riscontri di conformità raggruppati per regolamento
`get_compliance_overview`	Punteggi di conformità + matrice di stato per regolamento + metadati dell'ultima scansione

Governance & Consegna

Strumento	Descrizione
`list_principles`	Principi EA pubblicati (enunciato, motivazione, implicazioni)
`list_adrs`	Architecture Decision Records, filtrabili per iniziativa / stato
`get_adr`	ADR singolo con sezioni, card collegate e percorso di firma
`list_soaws`	Statements of Architecture Work di un'iniziativa

Report

Strumento	Descrizione
`get_portfolio_report`	Dati di grafico a bolle per un tipo di card (default: fit funzionale × tecnico)
`get_cost_treemap`	Treemap dei costi, opzionalmente raggruppato per un tipo correlato
`get_capability_heatmap`	Heatmap gerarchica delle capacità di business
`get_data_quality_report`	Suddivisione della completezza per tipo di card

Contesto card

Strumento	Descrizione
`get_card_stakeholders`	Utenti + ruoli assegnati a una card
`get_card_comments`	Thread di commenti di una card
`get_card_documents`	Link a documenti allegati a una card (URL, non file)

Tutti gli strumenti rispettano l'RBAC dell'utente autenticato — un visualizzatore riceverà semplicemente una lista vuota (o 403) per ciò che non può vedere; non serve alcuna configurazione per-tool a livello MCP.

Strumenti di scrittura — caricamento di artefatti¶

Cinque strumenti permettono a un agente di IA di trasformare gli artefatti in dati EA strutturati. L'agente legge il file sorgente nel proprio contesto (visione multimodale, allegati), estrae righe strutturate e chiama questi strumenti. Il server MCP in sé non analizza mai i file — si aspetta un input già strutturato.

Strumento	Descrizione
`create_cards_bulk`	Crea più card in una sola chiamata (per esempio righe di foglio di calcolo). Supporta riferimenti al genitore per nome all'interno dello stesso batch, con ordinamento topologico lato server.
`resolve_card_refs`	Pre-valida i riferimenti per nome prima di un'importazione di massa — utile per mostrare all'utente genitori ambigui o mancanti.
`upsert_relations_bulk`	Crea o elimina relazioni tra card. Sorgente / destinazione / tipo sono validati contro il metamodello.
`create_diagram`	Crea un diagramma DrawIO libero con collegamenti opzionali a card esistenti.
`import_bpmn`	Salva un diagramma BPMN 2.0 XML su una card Processo di business esistente. Se nessuna card corrisponde al nome fornito, lo strumento restituisce un errore `card_not_found` che rimanda l'agente a `create_cards_bulk` — questo forza la creazione esplicita della card con descrizione, sottotipo e attributi prima, invece di una scorciatoia che produce una card scarna.

Flusso tipico quando un utente condivide un foglio di calcolo con l'agente di IA:

L'agente chiama list_card_types e get_relation_types per comprendere il metamodello.
L'agente analizza il foglio di calcolo (nel proprio contesto, non in MCP) e costruisce dizionari di riga.
L'agente chiama create_cards_bulk(cards=…, dry_run=True) e mostra l'anteprima all'utente.
L'utente conferma; l'agente richiama con dry_run=False per confermare.
Se sono presenti colonne di relazione, l'agente chiama poi upsert_relations_bulk con lo stesso ciclo esecuzione di prova / conferma.

Salvaguardie degli strumenti di scrittura¶

Difesa in profondità sopra l'esecuzione di prova, in modo che un errore del LLM non possa causare danni massicci:

Limite di dimensione per chiamata. Gli strumenti di scrittura MCP applicano un limite molto più piccolo rispetto agli endpoint sottostanti dell'importatore Excel: 200 righe per create_cards_bulk, 500 operazioni per upsert_relations_bulk. Sufficientemente grande per qualsiasi caricamento realistico di un singolo artefatto, sufficientemente piccolo perché un'anteprima di esecuzione di prova rimanga visionabile.
Nessuna eliminazione di relazioni per impostazione predefinita. upsert_relations_bulk rifiuta le operazioni action: "delete" — per rimuovere relazioni, utilizzare l'interfaccia web dove l'azione viene registrata sotto l'identità dell'utente. Gli operatori possono abilitarla impostando MCP_ALLOW_RELATION_DELETE=true.
Interruttore di spegnimento. MCP_WRITES_ENABLED=false disattiva tutti e cinque gli strumenti di scrittura senza ridistribuire codice. I 25 strumenti di lettura continuano a funzionare.
Etichetta di origine per l'audit. Ogni richiesta al backend dal server MCP porta un'intestazione X-Turbo-EA-Origin: mcp. Gli eventi emessi da queste richieste vengono etichettati con origin: "mcp" nel payload del log di audit, in modo che gli amministratori possano filtrare le scritture guidate da MCP fuori dalla timeline, separate dalle azioni dell'interfaccia web.
Nessuno strumento di distruzione di massa. Il set di strumenti omette deliberatamente l'eliminazione, l'archiviazione e l'aggiornamento di massa delle card. Aggiungere uno di questi strumenti richiederebbe una revisione di progettazione esplicita.

Le quattro variabili di ambiente di salvaguardia sul container MCP:

Variabile	Predefinito	Effetto
`MCP_WRITES_ENABLED`	`true`	Interruttore principale degli strumenti di scrittura. `false` → MCP in sola lettura.
`MCP_MAX_CARDS_PER_CALL`	`200`	Limite massimo di righe `create_cards_bulk` per richiesta.
`MCP_MAX_RELATIONS_PER_CALL`	`500`	Limite massimo di operazioni `upsert_relations_bulk` per richiesta.
`MCP_ALLOW_RELATION_DELETE`	`false`	Quando `true`, `upsert_relations_bulk` accetta operazioni `action: "delete"`.

Risorse¶

URI	Descrizione
`turbo-ea://types`	Tutti i tipi di card nel metamodello
`turbo-ea://relation-types`	Tutti i tipi di relazione
`turbo-ea://dashboard`	KPI del dashboard e statistiche riepilogative

Prompt guidati¶

Prompt	Descrizione
`analyze_landscape`	Analisi a più passaggi: panoramica del dashboard, tipi, relazioni
`find_card`	Cercare una card per nome, ottenere dettagli e relazioni
`explore_dependencies`	Mappare le dipendenze di una card

Permessi¶

Ruolo	Accesso
Amministratore	Configurare le impostazioni MCP (permesso `admin.mcp`). Accesso completo in lettura + scrittura tramite MCP.
Tutti gli utenti autenticati	Accesso in lettura governato dal loro RBAC esistente. Gli strumenti di scrittura richiedono i corrispondenti permessi backend — `inventory.create` (card), `relations.manage` (relazioni), `diagrams.manage` (diagrammi), `bpm.edit` (BPMN).

Il permesso admin.mcp controlla chi può gestire le impostazioni MCP. È disponibile solo per il ruolo Amministratore per impostazione predefinita. Ai ruoli personalizzati può essere concesso questo permesso tramite la pagina di amministrazione dei Ruoli.

L'accesso ai dati tramite MCP — in lettura o in scrittura — segue lo stesso modello RBAC dell'interfaccia web. Se un utente non può creare card nell'interfaccia di inventario, non può crearle nemmeno tramite MCP; non ci sono permessi dati specifici per MCP.

Sicurezza¶

Autenticazione delegata tramite SSO: Gli utenti si autenticano tramite il provider SSO aziendale. Il server MCP non vede né memorizza mai le password.
OAuth 2.1 con PKCE: Il flusso di autenticazione utilizza Proof Key for Code Exchange (S256) per prevenire l'intercettazione dei codici di autorizzazione.
RBAC per utente: Ogni azione MCP — in lettura o in scrittura — viene eseguita con i permessi dell'utente autenticato. Nessun account di servizio condiviso.
Esecuzione di prova predefinita sulle scritture: Gli strumenti di scrittura propongono per impostazione predefinita un'anteprima valida-e-annulla. Lo strumento di IA deve richiamare esplicitamente con dry_run=false prima che qualunque dato venga persistito, e ogni modifica è registrata sotto l'identità dell'utente.
Nessuna analisi di file in MCP: Il server MCP in sé non accetta PDF, file Excel, immagini o altri artefatti binari. Lo strumento di IA chiamante li analizza nel proprio contesto e invia righe strutturate. Questo mantiene la superficie di attacco ridotta ed evita di esporre il server a input binari malformati.
Rotazione dei token: I token di accesso scadono dopo 1 ora. I token di rinnovo durano 30 giorni. I codici di autorizzazione sono monouso e scadono dopo 10 minuti.
Porta solo interna: Il container MCP espone la porta 8001 solo sulla rete Docker interna. Tutto l'accesso esterno passa attraverso il reverse proxy Nginx.

Risoluzione dei problemi¶

Problema	Soluzione
L'interruttore MCP è disabilitato nelle impostazioni	L'SSO deve essere configurato prima. Andare su Impostazioni > scheda Autenticazione e configurare un provider SSO.
«host not found» nei log di Nginx	Il servizio MCP non è in esecuzione. Avviarlo con `docker compose --profile mcp up -d`. La configurazione di Nginx gestisce questo in modo elegante (risposta 502, nessun crash).
Il callback OAuth fallisce	Verificare di aver aggiunto `https://il-tuo-dominio.esempio.com/mcp/oauth/callback` come URI di reindirizzamento nella registrazione dell'app SSO.
Lo strumento IA non riesce a connettersi	Verificare che `MCP_PUBLIC_URL` corrisponda all'URL accessibile dalla macchina dell'utente. Assicurarsi che HTTPS funzioni.
L'utente ottiene risultati vuoti	MCP rispetta i permessi RBAC. Se un utente ha accesso limitato, vedrà solo le card consentite dal suo ruolo.
La connessione si interrompe dopo 1 ora	Lo strumento IA dovrebbe gestire il rinnovo dei token automaticamente. In caso contrario, riconnettersi.