Integrazione MCP (accesso per strumenti IA)

Canopy 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 Canopy (:8001, interno)
    │
    │  OAuth 2.1 con PKCE
    │  delega al provider SSO
    ▼
Backend Canopy (:8000)
    │
    │  RBAC per utente
    ▼
PostgreSQL

1. Un utente aggiunge l'URL del server MCP al proprio strumento IA.
2. Alla prima connessione, lo strumento IA apre una finestra del browser per l'autenticazione SSO.
3. Dopo il login, il server MCP emette il proprio token di accesso (supportato dal JWT Canopy dell'utente). Il token viene rinnovato automaticamente circa un'ora prima della scadenza.
4. Lo strumento IA utilizza questo token per tutte le richieste successive.
5. Ogni query passa attraverso il normale sistema di permessi di Canopy — 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 -d

Questo avvia un container Python leggero (porta 8001, solo interna) accanto al backend e al frontend. Nginx inoltra automaticamente le richieste /mcp/ verso di esso — se il container non è in esecuzione, le richieste ricevono una pulita risposta 502 invece di mandare in crash il proxy perimetrale.

Passaggio 2: Configurare le variabili d'ambiente

Aggiungere queste al file .env:

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

Variabile	Predefinito	Descrizione
CANOPY_URL	http://backend:8000	URL interno del backend con cui comunica il container MCP (nome del servizio Docker — raramente necessita di modifica).
CANOPY_PUBLIC_URL	http://localhost:8920	L'URL pubblico dell'istanza Canopy.
MCP_PUBLIC_URL	http://localhost:8920/mcp	L'URL pubblico del server MCP (usato negli URI di reindirizzamento OAuth e nei metadati).
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 Canopy), 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

1. Andare su Impostazioni nell'area di amministrazione e selezionare la scheda AI.
2. Scorrere fino alla sezione Integrazione MCP (Accesso strumenti IA).
3. Attivare l'interruttore per abilitare MCP.
4. 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

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

VS Code (GitHub Copilot / Cursor)

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

{
  "servers": {
    "canopy": {
      "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": {
    "canopy": {
      "command": "python",
      "args": ["-m", "canopy_mcp", "--stdio"],
      "env": {
        "CANOPY_URL": "http://localhost:8000",
        "CANOPY_EMAIL": "[email protected]",
        "CANOPY_PASSWORD": "tua-password"
      }
    }
  }
}

In questa modalità, il server si autentica direttamente con email/password (senza OAuth) e rinnova automaticamente il JWT di Canopy in background.

---

Funzionalità disponibili

Il server MCP espone 47 strumenti: 30 strumenti di lettura suddivisi in nove cluster e 17 strumenti di scrittura (13 additivi, 4 distruttivi). Ogni strumento porta ToolAnnotations (readOnlyHint / destructiveHint / idempotentHint), in modo che i connettori come Claude Desktop possano segnalare nella propria interfaccia la pericolosità di una chiamata prima che l'utente la approvi.

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 una conferma esplicita dovrebbe richiamare nuovamente lo strumento con dry_run=false per confermare la modifica. Questo evita che un agente troppo zelante crei silenziosamente centinaia di card a partire da un foglio di calcolo interpretato in modo errato.

Per le conferme più grandi esiste un secondo cancello: qualsiasi conferma che superi MCP_BATCH_CONFIRMATION_THRESHOLD (predefinito 20 righe) deve restituire il confirm_token monouso emesso dalla precedente esecuzione di prova. Il token ha un TTL di 15 minuti. Questo controllo viene applicato due volte — prima dal wrapper MCP, ancor prima che chiami il backend, e poi di nuovo dal backend stesso sull'endpoint di conferma — così un client che salta il passaggio di esecuzione di prova non può far passare inosservato un batch ampio e non revisionato.

Batch di mutazione (audit trail)

Ogni chiamata di scrittura — che sia un'esecuzione di prova o meno — apre una riga mutation_batches prima di toccare qualsiasi dato, e ogni evento che genera (card creata, relazione creata/aggiornata, commento pubblicato, …) viene etichettato con l'id di quel batch, oltre al nome dello strumento chiamante e all'utente autenticato. Lo strumento get_change_history ricostruisce il diff completo evento per evento di un batch a partire dal suo id, mentre rollback_batch può annullare le scritture di un batch (vedi sotto). Questo significa che ogni modifica guidata da MCP è tracciabile fino a sapere esattamente chi ha eseguito quale strumento e quando — distinguendola dalla stessa azione compiuta tramite l'interfaccia web.

Strumenti di lettura

Il server espone 30 strumenti di lettura suddivisi in nove 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, con campi e configurazione
get_relation_types	Elencare i tipi di relazione, con filtro opzionale per tipo di card
resolve_card_refs	Pre-validare i riferimenti a card basati sul nome (es. "Sales / Customer Mgmt / CRM") prima di un'importazione di massa — evidenzia le corrispondenze risolte / ambigue / mancanti
analyze_impact	Analisi d'impatto multi-hop — percorre il grafo delle relazioni a partire da una card fino a 3 salti, raggruppata per profondità, con filtri opzionali per tipo di relazione e 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 di probabilità × impatto
get_card_risks	Tutti i rischi attualmente collegati a una card

GRC — Conformità

Strumento	Descrizione
list_compliance_findings	Riscontri di conformità raggruppati per regolamento (EU AI Act, GDPR, NIS2, DORA, SOC 2, ISO 27001)
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 / card / stato / ricerca
get_adr	ADR singolo con sezioni, card collegate, ADR correlati 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

Diagrammi

Strumento	Descrizione
list_diagrams	Elencare i diagrammi liberi, opzionalmente filtrati su una card
get_diagram	Recuperare un singolo diagramma tramite id, incluso il suo XML DrawIO

Audit e cronologia delle modifiche

Strumento	Descrizione
get_change_history	Cercare un batch di mutazione tramite id (restituisce il batch e tutti gli eventi emessi al suo interno, in ordine), oppure sfogliare i batch recenti per autore, nome dello strumento o origine (mcp / web / api)

Tutti gli strumenti di lettura sono vincolati all'RBAC dell'utente autenticato — un visualizzatore riceverà semplicemente una lista vuota (o un 403) per le aree che non può vedere; non è necessaria alcuna configurazione per singolo strumento a livello MCP.

Strumenti di scrittura

Il server espone 17 strumenti di scrittura: 13 additivi (azioni di creazione/aggiornamento che non distruggono dati) e 4 distruttivi (possono sovrascrivere o rimuovere dati, sebbene molti di questi siano a loro volta recuperabili — vedi le note sotto).

Card e ciclo di vita

Strumento	Annotazione	Descrizione
create_cards_bulk	Additivo	Creare più card in un'unica chiamata a partire da righe estratte da un artefatto (per esempio righe di un foglio di calcolo). Supporta riferimenti al genitore per nome all'interno dello stesso batch, con ordinamento topologico lato server.
update_cards_bulk	Additivo	Aggiornare più card in un'unica chiamata — patch a livello di campo con un diff prima/dopo per ogni riga nell'esecuzione di prova. attributes è una sostituzione completa per riga; strict_attributes=true rifiuta le chiavi di campo sconosciute con un suggerimento per il recupero.
transition_card_lifecycle	Additivo	Far avanzare una card attraverso azioni di approvazione (approve / reject / reset), fasi del ciclo di vita (phaseIn / active / phaseOut / endOfLife) o valori di stato (ACTIVE / PHASING_IN / PHASING_OUT / END_OF_LIFE / ARCHIVED). Restituisce una risposta pending con un collegamento diretto all'interfaccia se il chiamante non dispone del permesso, invece di fallire direttamente.
archive_cards	Distruttivo	Eliminazione logica (archiviazione) di una o più card, con un'anteprima a cascata nell'esecuzione di prova (figli, relazioni orfane). Le card archiviate sono recuperabili per 30 giorni prima della cancellazione automatica definitiva. L'eliminazione fisica/permanente non è intenzionalmente esposta tramite MCP.

Relazioni e diagrammi

Strumento	Annotazione	Descrizione
upsert_relations_bulk	Distruttivo	Creare o eliminare relazioni tra card. action: "delete" è rifiutata per impostazione predefinita (vedi le salvaguardie sotto) — è questo che rende lo strumento annotato come distruttivo, anche se le creazioni sono il caso d'uso comune.
create_diagram	Additivo	Creare un diagramma DrawIO libero, opzionalmente collegato a card esistenti tramite UUID.
update_diagram	Distruttivo	Aggiornare l'XML, il nome, la descrizione o le card collegate di un diagramma esistente — drawio_xml sostituisce la tela (canvas) testualmente.
import_bpmn	Additivo	Salvare un diagramma BPMN 2.0 su una card Processo di business esistente, percorrendo il flusso bozza → invio → approvazione. Se non esiste una card corrispondente, restituisce un errore card_not_found che rimanda a create_cards_bulk invece di creare silenziosamente una card scarna.

GRC — Registro dei rischi

Strumento	Annotazione	Descrizione
create_risks	Additivo	Creare uno o più rischi, collegando opzionalmente le card interessate nella stessa chiamata.
update_risks	Additivo	Applicare patch a rischi esistenti tramite id; linked_card_ids, se fornito, sostituisce l'insieme di card collegate.

Governance e consegna

Strumento	Annotazione	Descrizione
create_soaw	Additivo	Creare uno Statement of Architecture Work per un'iniziativa.
create_adr	Additivo	Creare un Architecture Decision Record (per impostazione predefinita in stato draft).
update_adr	Additivo	Aggiornare titolo, sezioni, stato o card collegate di un ADR esistente.
sign_adr	Additivo	Firmare un ADR. Restituisce una risposta pending con un collegamento diretto se il chiamante non dispone di adr.sign.

Collaborazione

Strumento	Annotazione	Descrizione
add_card_comment	Additivo	Pubblicare un commento (opzionalmente in thread) su una card.
assign_stakeholders	Additivo	Assegnare o rimuovere ruoli di stakeholder sulle card. Il backend non dispone di un endpoint di massa per questa operazione, quindi lo strumento distribuisce le operazioni una per una all'interno di un unico batch di mutazione.

Audit

Strumento	Annotazione	Descrizione
rollback_batch	Distruttivo	Annullare le scritture eseguite in un batch di mutazione percorrendone gli eventi in ordine inverso e applicando l'inverso di ciascuno. Copre card.created / card.updated / card.archived / card.restored / relation.created / relation.upserted; altri tipi di evento compaiono come unsupported_events nel piano dell'esecuzione di prova. Il rollback stesso viene registrato come un nuovo batch, quindi la cronologia non viene mai cancellata. Viene rifiutato se un batch successivo ha toccato le stesse entità, a meno che non venga passato force=true, che richiede admin.events.

Il contenuto memorizzato da questi strumenti (testo dei commenti, testo delle sezioni di ADR/SoAW) viene trattato come dato non affidabile in una successiva rilettura — il server non lo interpreta mai come istruzioni, si limita a mostrarlo.

Flusso tipico di importazione di artefatti

Quando un utente condivide un foglio di calcolo con l'agente di IA:

1. L'agente chiama list_card_types e get_relation_types per comprendere il metamodello.
2. L'agente analizza il foglio di calcolo (nel proprio contesto, non in MCP) e costruisce dizionari di riga.
3. Facoltativamente, l'agente chiama resolve_card_refs per verificare che eventuali riferimenti a genitori/relazioni basati sul nome si risolvano senza ambiguità.
4. L'agente chiama create_cards_bulk(cards=…, dry_run=True) e mostra l'anteprima all'utente.
5. L'utente conferma; l'agente richiama lo strumento con dry_run=False (restituendo confirm_token se il batch supera la soglia di conferma) per confermare la modifica.
6. Se sono presenti colonne di relazione, l'agente chiama quindi upsert_relations_bulk con lo stesso ciclo esecuzione di prova / conferma.

Il server MCP in sé non analizza mai i file caricati — lo strumento di IA chiamante legge l'artefatto sorgente (foglio di calcolo, XML BPMN, XML DrawIO, PDF, immagine) nel proprio contesto e invia righe già strutturate.

Salvaguardie degli strumenti di scrittura

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

• Limiti di dimensione per chiamata. Gli strumenti di scrittura MCP applicano un limite molto più basso rispetto agli endpoint sottostanti dell'importatore Excel: 200 card per create_cards_bulk / update_cards_bulk / archive_cards, 500 operazioni per upsert_relations_bulk. Abbastanza grande per qualsiasi caricamento realistico di un singolo artefatto, abbastanza piccolo perché l'anteprima dell'esecuzione di prova resti facilmente esaminabile. Gli endpoint backend stessi accettano fino a 2000/5000 per il legittimo importatore Excel dell'interfaccia web.
• Token di conferma sopra la soglia. Le conferme che riguardano più di MCP_BATCH_CONFIRMATION_THRESHOLD righe (predefinito 20) devono restituire il confirm_token emesso dalla precedente esecuzione di prova. Applicato sia dal wrapper MCP sia dal backend.
• 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 con un percorso di audit esplicito. Gli operatori possono abilitarla impostando MCP_ALLOW_RELATION_DELETE=true.
• Nessuna eliminazione permanente. Il set di strumenti omette deliberatamente l'eliminazione permanente delle card. archive_cards (eliminazione logica, con finestra di ripristino di 30 giorni) e rollback_batch sono gli unici modi per rimuovere dati tramite MCP, ed entrambi sono vincolati all'esecuzione di prova e annotati come distruttivi. Qualsiasi futuro strumento che esegua una mutazione irreversibile richiede prima una discussione RFC.
• Interruttore di spegnimento. MCP_WRITES_ENABLED=false disattiva tutti i 17 strumenti di scrittura senza dover ridistribuire il codice. I 30 strumenti di lettura continuano a funzionare.
• Etichetta di origine per l'audit. Ogni richiesta al backend proveniente dal server MCP porta un'intestazione X-Canopy-Origin: mcp (limitata lato server ai valori {mcp, web, api} — qualsiasi altro valore viene scartato). Gli eventi generati da queste richieste vengono etichettati con origin: "mcp" nel payload di audit, in modo che gli amministratori possano filtrare le scritture guidate da MCP nella timeline. L'intestazione X-Canopy-Batch propaga l'id del batch di mutazione corrente attraverso ogni chiamata all'interno di una singola invocazione dello strumento.

Le variabili di ambiente di salvaguardia sul container MCP:

Variabile	Predefinito	Effetto
MCP_WRITES_ENABLED	true	Interruttore principale per gli strumenti di scrittura. false → MCP in sola lettura.
MCP_MAX_CARDS_PER_CALL	200	Limite massimo di righe per chiamata per create_cards_bulk, update_cards_bulk, archive_cards.
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".
MCP_BATCH_CONFIRMATION_THRESHOLD	20	Numero di righe oltre il quale una conferma deve restituire un confirm_token proveniente da una precedente esecuzione di prova.
MCP_REQUIRE_DRYRUN_FIRST	true	Quando true, una conferma sopra la soglia senza una precedente esecuzione di prova corrispondente nella stessa sessione viene rifiutata. Gli operatori possono disabilitarlo per pipeline di automazione fidate.

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 da cosa dipende una card e cosa dipende da essa

---

Permessi

Ruolo	Accesso
Amministratore	Configurare le impostazioni MCP (permesso admin.mcp). Accesso completo in lettura e scrittura tramite MCP.
Tutti gli utenti autenticati	Accesso in lettura governato dal loro RBAC esistente. Gli strumenti di scrittura richiedono il permesso backend corrispondente all'azione che eseguono.

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 esistono permessi sui dati specifici per MCP. Permessi selezionati per strumento:

Permesso	Governa
inventory.create	create_cards_bulk
inventory.edit	update_cards_bulk, le transizioni di ciclo di vita/stato tramite transition_card_lifecycle
inventory.approval_status	Transizioni di approvazione (approve / reject / reset) tramite transition_card_lifecycle
inventory.archive	archive_cards
relations.manage	upsert_relations_bulk
diagrams.manage	create_diagram, update_diagram
bpm.edit	import_bpmn (bozza); la pubblicazione richiede inoltre card.approval_status sul processo, detenuto tramite il ruolo di stakeholder process_owner, admin o bpm_admin
risks.manage	create_risks, update_risks
comments.create	add_card_comment
stakeholders.manage	assign_stakeholders
soaw.create	create_soaw
adr.create	create_adr, update_adr
adr.sign	sign_adr
admin.events	rollback_batch(force=True) — per superare un conflitto di rollback con un batch successivo

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.

Diversi strumenti di scrittura si degradano in modo controllato invece di fallire bruscamente quando il chiamante non dispone di un permesso: transition_card_lifecycle e sign_adr restituiscono una risposta pending con un collegamento diretto all'interfaccia web, in modo che una persona con il permesso corretto possa completare l'azione lì.

---

Sicurezza

• Autenticazione delegata tramite SSO: gli utenti si autenticano tramite il provider SSO aziendale. Il server MCP non vede né memorizza mai le password (in modalità HTTP).
• 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 query 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 di validazione-e-annullamento. Lo strumento di IA deve richiamare esplicitamente lo strumento con dry_run=false prima che qualsiasi dato venga persistito, e ogni modifica viene sottoposta ad audit sotto l'identità dell'utente come parte di un batch di mutazione.
• Cancello del token di conferma sulle conferme di grandi dimensioni: le conferme che superano la soglia di righe configurabile richiedono un token generato da una precedente esecuzione di prova, verificato in modo indipendente sia dal wrapper MCP sia dal backend.
• Percorso di audit completo con rollback: get_change_history ricostruisce il diff di qualsiasi batch a partire dal suo id; rollback_batch può annullare i tipi di evento supportati di un batch, venendo a sua volta registrato come un nuovo batch, verificabile in audit.
• 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.
• Nessuna eliminazione permanente tramite MCP: l'eliminazione permanente delle card non è esposta come strumento. Gli unici percorsi di rimozione sono archive_cards (eliminazione logica recuperabile per 30 giorni) e rollback_batch.
• Rotazione dei token: i token di accesso scadono dopo 1 ora e vengono rinnovati automaticamente in anticipo. 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.
• Archivio token a istanza singola: i token OAuth sono mantenuti in memoria sul container MCP. Se si eseguono più repliche dietro un load balancer, ancorare le sessioni a una singola istanza oppure prevedere che gli utenti debbano ri-autenticarsi dopo un failover — i token non sono condivisi tra le repliche.

---

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 caso 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 correttamente.
L'utente ottiene risultati vuoti	MCP rispetta i permessi RBAC. Se un utente ha accesso limitato, vedrà solo le card consentite dal proprio ruolo.
Lo strumento di scrittura restituisce writes_disabled	MCP_WRITES_ENABLED=false su questa installazione. Gli strumenti di lettura continuano a funzionare; chiedere a un operatore di riabilitare le scritture se necessario.
Conferma rifiutata con confirm_token_required	Il batch supera MCP_BATCH_CONFIRMATION_THRESHOLD righe. Rieseguire prima con dry_run=true, quindi passare il confirm_token restituito nella chiamata di conferma.
La connessione si interrompe dopo 1 ora	Lo strumento IA dovrebbe gestire automaticamente il rinnovo del token. In caso contrario, riconnettersi.