Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Architettura: Strumenti, Risorse e Interfaccia

Lezione 2 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Panoramica
  2. Cosa Espone un Server MCP
  3. Il Flusso della Richiesta
  4. Trasporto e Autorizzazione
  5. L’Interfaccia: Un Livello Opzionale
  6. Skills: Il Livello del Flusso di Lavoro
  7. E il Commercio?
  8. Punti chiave

Lezione riscritta il 3 novembre 2026 sulla base delle pagine MCP server, Plugin architecture e Skills della documentazione dei Plugin OpenAI. La vecchia architettura “actions, widgets, commerce” descriveva un SDK che non esiste più. Fonti: MCP server · Plugin architecture · Skills.

Panoramica

Un plugin è composto da livelli indipendenti. Le Skills forniscono il piano d’azione, il server MCP offre le capacità e l’interfaccia fornisce un modo visivo per interagire quando necessario.

Plugin
├── Skills
└── Server MCP (opzionale)
    ├── Strumenti e risultati strutturati
    └── Risorse di interfaccia (opzionali)

Ogni livello ha un ruolo distinto. La documentazione riassume il confine in questo modo: il server MCP fornisce dati, autenticazione, autorizzazione e azioni; la skill fornisce istruzioni riutilizzabili, esempi e modelli di documenti.

Cosa Espone un Server MCP

Un server MCP può esporre quattro tipi di entità:

  • Strumenti: Funzioni che il modello chiama con input strutturati.
  • Risorse: Dati o contenuti che il client può leggere.
  • Prompt: Modelli di prompt riutilizzabili.
  • Istruzioni: Direttive applicabili all’intero server.

I plugin si basano principalmente sugli strumenti. Ogni strumento ha un nome, una descrizione, uno schema di input e, opzionalmente, uno schema di output. Questi campi permettono al modello di decidere quando chiamare lo strumento e come utilizzarne il risultato.

Il Flusso della Richiesta

Quando un utente effettua una richiesta che corrisponde a uno strumento, si verificano quattro passaggi in sequenza:

  1. Il client rileva gli strumenti esposti dal server MCP.
  2. Il modello seleziona uno strumento e fornisce argomenti conformi al suo schema di input.
  3. Il server valida la richiesta, esegue l’operazione e restituisce un risultato.
  4. Il modello utilizza tale risultato per continuare la conversazione.

Un risultato di uno strumento può contenere tre parti. structuredContent trasporta dati concisi che il modello può ispezionare e riutilizzare nelle chiamate successive. content trasporta testo o altri contenuti MCP che aiutano il modello a formulare una risposta. _meta trasporta dati destinati al client e nascosti al modello: nascosti, ma non protetti. Questo campo non sostituisce l’autorizzazione né l’archiviazione sicura.

Trasporto e Autorizzazione

In produzione, distribuisci un server MCP a un indirizzo HTTPS stabile utilizzando il trasporto streamable HTTP del protocollo, tipicamente su un percorso /mcp. Se gli strumenti leggono dati privati o agiscono per conto di un utente, proteggi il server con il flusso di autorizzazione definito dalla specifica MCP: OAuth, dettagliato nella Lezione 8.

L’Interfaccia: Un Livello Opzionale

Uno strumento deve funzionare senza un’interfaccia: testo conciso e un risultato strutturato sono spesso sufficienti affinché il modello risponda. Un’interfaccia ha senso quando l’utente deve ispezionare, confrontare, modificare, confermare o navigare informazioni strutturate: un confronto di prodotti, un programma modificabile o una mappa. Un semplice controllo di stato generalmente non ne ha bisogno.

Quando presente, l’interfaccia è una risorsa che il server dichiara. ChatGPT la visualizza in un iframe quando lo strumento associato la restituisce. ChatGPT implementa lo standard aperto MCP Apps: l’interfaccia comunica con l’host tramite JSON-RPC utilizzando postMessage. Estensioni specifiche di ChatGPT, accessibili tramite window.openai, integrano lo standard quando questo non copre una necessità specifica. La Lezione 6 tratta questo argomento.

Skills: Il Livello del Flusso di Lavoro

Una skill è una cartella contenente un file SKILL.md: un nome, una descrizione che indica al modello quando considerarla, istruzioni e, se necessario, riferimenti, script o modelli. Il modello vede inizialmente solo il nome e la descrizione; carica le istruzioni complete quando la richiesta corrisponde alla skill o quando l’utente la invoca direttamente. Da qui il consiglio di OpenAI: scrivi la descrizione attorno all’obiettivo dell’utente e alle condizioni di attivazione, e mantieni i dettagli passo-passo nel corpo del file.

E il Commercio?

Vendere tramite un plugin non è un livello separato. È un percorso che l’interfaccia opzionale può supportare, sfruttando le Checkout API documentate da OpenAI. La Lezione 7 spiega come funziona e quali sono i suoi limiti.

Punti chiave

  • Un server MCP espone strumenti, risorse, prompt e istruzioni; i plugin si basano principalmente sugli strumenti
  • Un risultato di uno strumento combina structuredContent, content e _meta (nascosto al modello, ma non sicuro)
  • Produzione: HTTPS stabile, trasporto streamable HTTP, autorizzazione secondo la specifica MCP
  • L’interfaccia è una risorsa opzionale visualizzata da ChatGPT secondo lo standard MCP Apps
  • Le Skills gestiscono il flusso di lavoro; il server gestisce dati, autorizzazione e azioni