MCP: come collegare un modello AI agli strumenti reali. Il caso OpenCode, Ollama e ArtCraft

Un modello linguistico ti spiega come si crea un documento Word, ti scrive la formula di Excel, ti dice quali filtri applicare a una foto. Poi però il file lo crei tu, la formula la incolli tu, i filtri li applichi tu. Descrivere un'operazione non vuol dire eseguirla.

Per far fare il salto serve un ponte tra il modello e gli strumenti che uso ogni giorno: applicazioni, file, database, API. Quel ponte, sempre più spesso, si chiama MCP, Model Context Protocol.

In questo articolo racconto come l'ho messo in piedi sulla mia macchina Fedora: OpenCode come host, un modello locale servito da Ollama e tre applicazioni della famiglia ArtCraft (PhotoCraft, WordCraft e GridCraft) esposte come server MCP. Non è una guida teorica: ci sono le configurazioni che hanno funzionato, quella che non ha funzionato come mi aspettavo e le cose che controllerei prima di dare a un assistente il permesso di scrivere sul disco.

La domanda di partenza è semplice: posso chiedere a un assistente AI di lavorare davvero su documenti, fogli di calcolo e immagini, senza scrivere da zero un'integrazione per ogni applicazione?

Che cos'è MCP e come funziona

MCP è un protocollo aperto che definisce un'architettura client-server per far parlare un'applicazione AI con strumenti esterni. Invece di costruire un'integrazione diversa per ogni coppia modello-applicazione, si usa un'interfaccia comune.

I ruoli sono tre:

• Host: l'applicazione che ospita l'esperienza AI e coordina il lavoro. Nel mio caso è OpenCode.
• Client MCP: il componente dell'host che gestisce la connessione con un singolo server. Un host può averne più d'uno, uno per ogni server collegato.
• Server MCP: il processo che espone le funzionalità vere e proprie. Può leggere dati, modificare documenti, interrogare servizi.

Il modello interpreta la richiesta e decide quali strumenti usare. L'host gestisce il flusso, il client parla con il server, il server esegue.

Faccio un esempio. Chiedo:

Crea un foglio Excel con le spese mensili, calcola il totale e genera un grafico.

Il modello pianifica i passaggi e guarda quali strumenti ha a disposizione. Via MCP chiede la creazione del foglio, l'inserimento dei dati, le formule, il grafico. Il server restituisce i risultati e l'assistente può controllare quello che ha fatto. Il modello non ha bisogno di conoscere l'interno dell'applicazione: gli basta sapere quali strumenti esistono, quali parametri vogliono e cosa restituiscono.

Sotto il cofano la comunicazione usa JSON-RPC e può viaggiare su trasporti diversi: stdio per i processi locali, Streamable HTTP per le connessioni di rete. Quello che uso io è stdio.

Documentazione ufficiale: modelcontextprotocol.io e architettura MCP.

Tools, resources e prompts

MCP non è solo un modo standard per chiamare una funzione. Definisce tre primitive.

Tools. Sono le operazioni che il client può invocare. Ognuna ha un nome, una descrizione e uno schema dei parametri. Un server per fogli di calcolo può esporre strumenti per leggere un intervallo, modificare una cella, valutare una formula, inserire un grafico. L'assistente scopre l'elenco e chiama quelli pertinenti.

Resources. Sono dati e contenuti che il server mette a disposizione del client: documenti, informazioni, risorse di vario tipo. Servono a dare contesto al modello.

Prompts. Sono modelli di interazione riutilizzabili che il server può offrire, utili per standardizzare procedure ricorrenti.

Il punto da tenere a mente è questo: MCP standardizza il modo in cui le funzionalità vengono esposte, ma non obbliga nessun server a implementarle tutte. Molti server espongono solo tools. Cosa c'è davvero dietro lo scopri leggendo la documentazione del server, non quella del protocollo.

Perché MCP e non integrazioni su misura

Senza un protocollo condiviso, ogni applicazione richiede la sua integrazione: codice per la comunicazione, gestione degli errori, descrizione delle operazioni. Con MCP un host compatibile si collega a qualsiasi server che parla lo stesso protocollo. In pratica ottengo:

• Interoperabilità: lo stesso server può essere usato da host diversi, purché supportino le funzionalità che espone.
• Modularità: aggiungo o tolgo strumenti senza toccare l'assistente.
• Riuso: una funzionalità scritta una volta serve più client.
• Azione concreta: l'assistente non si limita a suggerire, esegue.
• Separazione delle responsabilità: il modello interpreta, l'host coordina, il server opera.

C'è un costo che spesso si dimentica. Ogni server aggiunge al contesto del modello i nomi degli strumenti, le descrizioni e gli schemi dei parametri. Con un modello piccolo e una finestra di contesto limitata, come il mio 7B, collegare decine di server non rende l'assistente più capace: lo confonde e gli mangia il contesto. Meglio pochi strumenti, quelli che servono al lavoro che sto facendo, e verificare che il modello li usi bene.

L'ambiente: OpenCode, Ollama e ArtCraft

Il setup è un Fedora con tre componenti.

OpenCode è l'host. Gestisce la conversazione e mette a disposizione del modello gli strumenti MCP.

Ollama esegue il modello in locale. Uso qwen25coder-7b-32k, un Qwen2.5 Coder da 7 miliardi di parametri con contesto da 32k, esposto tramite l'endpoint compatibile OpenAI di Ollama. Tutto resta sulla mia macchina.

ArtCraft è la parte che dà il titolo all'articolo. È il progetto di Brandon Thomas, uno sviluppatore con quindici anni di esperienza, che ha prima pubblicato una suite open source di alternative ad Adobe e poi, a ottobre, una di alternative a Office. Sono applicazioni scritte in Rust, sviluppate con l'aiuto di Claude Opus, rilasciate con licenza MIT o Apache 2.0 e pensate fin dall'inizio per essere pilotate da agenti AI attraverso CLI e server MCP.

Io ne ho collegate tre:

• PhotoCraft, l'alternativa a Photoshop, per l'elaborazione delle immagini.
• WordCraft, l'alternativa a Word, per creare e modificare documenti.
• GridCraft, l'alternativa a Excel, per fogli di calcolo, formule, intervalli e grafici.

Repository: PhotoCraft, WordCraft, GridCraft.

Quali sono le app di ArtCraft

La suite è più ampia delle tre che ho provato. Dal lato Adobe comprende le alternative a Photoshop, Illustrator, Premiere, Lightroom, Acrobat, After Effects e InDesign. Dal lato Office ci sono WordCraft, GridCraft e DeckCraft (l'alternativa a PowerPoint). In giro si cita anche CADCraft, un'alternativa ad Autodesk.

[Nota per te, Luca: dici che le app sono 12 in totale. Con questo elenco ne ricostruisco 11 e non sono riuscito a verificare i nomi "Craft" di tutte le app Adobe. Prima di pubblicare controlla la lista ufficiale sul sito ArtCraft o nell'organizzazione GitHub storytold e completa questo paragrafo con i nomi esatti.]

Una cosa va detta chiaramente, anche perché lo dicono gli stessi autori: le app Office sono in pre-alpha o in sviluppo iniziale, e le percentuali di compatibilità che girano (per esempio sulle funzioni dei fogli di calcolo o sulle funzionalità di PowerPoint) sono dichiarazioni dei repository, non verifiche indipendenti. Il supporto MCP non significa che siano equivalenti ai prodotti commerciali che li hanno ispirati. Per i miei test mi bastano, per sostituire Office in produzione senza provare i vostri file reali no.

Come ho collegato i server MCP a OpenCode

OpenCode legge la configurazione dei server MCP dal file opencode.json. Un server locale è un comando che OpenCode avvia come processo figlio: gli manda le richieste sullo standard input e legge le risposte dallo standard output. Questo è il trasporto stdio.

La struttura è questa:

{
  "mcp": {
    "nome-server": {
      "type": "local",
      "command": ["/percorso/assoluto/programma", "mcp"],
      "enabled": true,
      "timeout": 30000
    }
  }
}

Il comando è un array, non una stringa da dare in pasto a una shell. Ogni elemento è un argomento a sé, quindi i percorsi con spazi non danno problemi di quoting. Mi è comodo perché la mia directory di lavoro si chiama proprio AI Working, con lo spazio.

PhotoCraft

Sul mio Fedora il comando installato è /usr/bin/photocraft-cli. Gli ho dato una directory esplicita per lettura e scrittura:

{
  "photocraft": {
    "type": "local",
    "command": [
      "/usr/bin/photocraft-cli",
      "mcp",
      "--automation-read-root",
      "/home/luca/AI Working",
      "--automation-write-root",
      "/home/luca/AI Working"
    ],
    "enabled": true,
    "timeout": 30000
  }
}

Con questi due parametri il server headless può leggere e scrivere solo dentro quella cartella. Nel mio caso i due percorsi coincidono, ma si possono separare: una directory di input in sola lettura e una di output dove l'assistente può scrivere.

WordCraft

WordCraft espone il server MCP dalla sua CLI:

/usr/bin/wordcraft-cli mcp

I parametri di controllo accessi sono gli stessi e sono descritti nella documentazione di WordCraft:

{
  "wordcraft": {
    "type": "local",
    "command": [
      "/usr/bin/wordcraft-cli",
      "mcp",
      "--automation-read-root",
      "/home/luca/AI Working",
      "--automation-write-root",
      "/home/luca/AI Working"
    ],
    "enabled": true,
    "timeout": 30000
  }
}

Gli strumenti esposti permettono di creare, aprire e salvare documenti, inserire testo, eseguire comandi di formattazione e ispezionare la struttura del documento.

GridCraft

Qui la storia cambia. Si avvia con:

/usr/bin/gridcraft-cli mcp

e questa è la configurazione che ha funzionato da me:

{
  "gridcraft": {
    "type": "local",
    "command": [
      "/usr/bin/gridcraft-cli",
      "mcp"
    ],
    "enabled": true,
    "timeout": 30000
  }
}

Nella versione 0.7.0 che ho installato, aggiungere --automation-read-root e --automation-write-root faceva fallire l'avvio. Tolti i parametri, il server si è connesso subito.

Due conseguenze. La prima: non dare per scontato che le CLI di applicazioni della stessa famiglia siano identiche. Si controlla sulla versione che si ha davvero installata. La seconda, più importante: il fatto che GridCraft si connetta non dimostra che sia confinato a una directory. Nella configurazione che uso non c'è nessuna restrizione equivalente, quindi non ho un controllo di accesso ai file paragonabile a quello degli altri due. Prima di usarlo su file che contano, questo va risolto o quantomeno tenuto presente.

Verificare la connessione

Salvata la configurazione, ho lanciato:

opencode mcp list

Risultato:

✓ photocraft connected
✓ wordcraft connected
✓ gridcraft connected

3 server(s)

Questo controllo è banale ma serve. Un JSON valido non garantisce che il processo parta, che accetti gli argomenti che gli ho passato o che risponda correttamente al protocollo. GridCraft ne è la prova.

Il server "si blocca"? No, sta aspettando

Provando WordCraft a mano da terminale ho avuto un momento di sconcerto: lanciato il comando MCP, il terminale restava fermo, senza output e senza tornare al prompt.

Non era bloccato. Un server MCP su stdio è un processo persistente: non deve terminare dopo l'avvio, resta in ascolto di richieste sullo standard input. Per essere sicuro ho fatto il lavoro del client a mano, inviando in sequenza una richiesta JSON-RPC initialize, la notifica notifications/initialized e poi tools/list. Il server ha risposto con le informazioni di inizializzazione e con l'elenco degli strumenti.

Morale: un processo in attesa non è un processo bloccato. Per capire se un server MCP funziona non basta guardare il terminale, bisogna vedere se risponde al protocollo.

Cosa si può fare con Craft

La configurazione è la parte noiosa. Il senso viene fuori quando si passa a un compito concreto. Qui descrivo i flussi realizzabili con gli strumenti esposti, e dove non l'ho provato fino in fondo lo dico.

Generare un documento Word

Posso chiedere all'assistente di costruire un documento con titolo, sezioni, paragrafi e una tabella. In pratica il flusso passa per:

1. creare un documento nuovo;
2. inserire il contenuto;
3. applicare gli stili ai titoli;
4. aggiungere la tabella;
5. salvare in DOCX;
6. ispezionare il risultato per controllare la struttura.

WordCraft espone strumenti come new_document, type_text, execute, batch, inspect_document e save_document. Il documento viene costruito con operazioni strutturate, non incollando a mano un blocco di testo in un editor. Un prompt di esempio:

Crea un documento Word con un titolo, un'introduzione, tre sezioni e una tabella riepilogativa. Salvalo nella directory di lavoro e verifica che contenga tutte le sezioni previste.

L'ultimo passo, l'ispezione, è quello che fa la differenza: l'assistente non dà per buono quello che ha scritto, lo rilegge.

Excel e formule

GridCraft espone strumenti per leggere e scrivere intervalli, modificare celle, valutare formule, applicare formattazione e creare grafici. Un esempio di richiesta:

Crea un foglio con le spese dei dodici mesi, calcola il totale annuale e la media mensile, evidenzia il mese con la spesa maggiore e aggiungi un grafico.

Qui non ottengo una tabella di testo da copiare: il server lavora sul foglio vero e restituisce i risultati delle operazioni. Detto questo, le formule vanno sempre verificate. Un foglio che si salva senza errori può contenere riferimenti sbagliati, intervalli troncati o dati incoerenti. Un modello da 7 miliardi di parametri è bravo a produrre qualcosa di plausibile, e plausibile non vuol dire corretto.

Un flusso tra più applicazioni

La parte più interessante è combinare gli strumenti. Ho dei dati in un foglio e voglio un report:

1. leggo e analizzo i dati con GridCraft;
2. calcolo totali, medie e indicatori;
3. genero un documento con WordCraft;
4. inserisco tabelle e conclusioni;
5. se serve, preparo un'immagine o un elemento grafico con PhotoCraft;
6. controllo i file prodotti e li salvo nella directory prevista.

Preciso che questo è un flusso costruibile con gli strumenti disponibili, non il resoconto di una prova end-to-end che ho già fatto in ogni sua fase. Quello che ho verificato è la connessione dei tre server e l'elenco degli strumenti. Il flusso completo è il prossimo test, e ne scriverò.

Limiti e sicurezza: MCP non è una bacchetta magica

La standardizzazione non risolve i problemi di sicurezza, li sposta.

Un server MCP può esporre strumenti in sola lettura, oppure strumenti che modificano documenti, scrivono file ed eseguono operazioni con conseguenze reali. Prima di collegarne uno devo sapere che permessi riceve e cosa può fare. Nel mio caso PhotoCraft e WordCraft accettano directory autorizzate per lettura e scrittura, GridCraft nella versione provata no. Quindi i tre server non sono equivalenti dal punto di vista dei permessi, anche se compaiono nello stesso elenco con la stessa spunta verde.

Le regole che mi sono dato:

• concedere solo gli accessi che servono;
• separare, dove possibile, le directory di input da quelle di output;
• non esporre server locali a client o servizi non fidati senza altri controlli;
• guardare con attenzione le operazioni che modificano o cancellano file;
• controllare sempre i risultati, soprattutto se contengono calcoli o dati importanti;
• tenere attivi solo gli strumenti che servono al lavoro del momento.

C'è anche il rischio che non dipende dal server ma dal modello. Un modello locale piccolo può scegliere lo strumento sbagliato, passare parametri sbagliati o dichiarare completata un'operazione che non ha fatto. Per questo la verifica a valle (rileggere il documento, controllare le formule, aprire il file) non è facoltativa.

Infine la maturità. Come detto, le app Office di ArtCraft sono in fase iniziale. Compatibilità con i formati, copertura delle funzionalità e fedeltà sui file reali vanno valutate sulle proprie esigenze, non sulle percentuali dei README.

MCP definisce come si parla. Non garantisce che il server sia sicuro, che il modello capisca bene la richiesta o che l'operazione riesca.

Conclusioni

MCP non è un modello più intelligente e non rende più intelligente quello che già uso. Il suo valore è un altro: un'interfaccia standard per collegare un assistente a strumenti che leggono dati, eseguono operazioni e producono risultati controllabili.

Nel mio esperimento ho collegato OpenCode, con un modello locale servito da Ollama, a tre server MCP della famiglia ArtCraft. Ho verificato che PhotoCraft, WordCraft e GridCraft si connettono, e ho trovato una differenza concreta nella gestione dei percorsi autorizzati che da sola vale la pena di ricordare.

Il passo successivo non è aggiungere altri server, ma costruire flussi ripetibili: generare un documento, elaborare un foglio, verificare il risultato, coordinare più applicazioni in un'unica procedura. Un assistente che sa spiegare come si lavora è utile. Uno che sceglie gli strumenti giusti, esegue i passaggi e controlla l'esito diventa una parte vera del proprio ambiente di lavoro. MCP è uno dei protocolli che rendono possibile questo passaggio.