Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Il tuo primo plugin

Lezione 4 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Due passaggi
  2. Passaggio 1: un plugin personale in cinque minuti
  3. Passaggio 2: il tuo server
  4. Ricarica dopo ogni modifica
  5. Punti chiave

Lezione riscritta il 3 novembre 2026 sulla base delle pagine Quickstart, MCP server and UI quickstart e Connect and test your plugin della documentazione dei plugin OpenAI. Il precedente esempio “app meteo in 30 minuti” si basava su un SDK inesistente. Abbiamo verificato le versioni dei pacchetti npm il 3 novembre 2026: @modelcontextprotocol/ext-apps 2.x si basa sull’SDK MCP v2, mentre gli esempi di OpenAI utilizzano la v1. Fonti: Quickstart · MCP server and UI quickstart · Connect and test.

Due passaggi

Innanzitutto, collegherai un server MCP esistente per osservare l’intero flusso di lavoro di ChatGPT senza scrivere una singola riga di codice. Successivamente, scriverai il tuo server, lo testerai in locale e lo collegherai allo stesso modo.

Passaggio 1: un plugin personale in cinque minuti

OpenAI mette a disposizione un server MCP di esempio pubblico e non autenticato che espone un unico strumento di sola lettura: roll_dice.

  1. Vai su ChatGPT Plugins, seleziona il pulsante +, quindi scegli Add custom MCP server.
  2. Inserisci un nome e imposta l’Server URL su https://tinymcp.dev/api/moldy-aloof-zettabyte/mcp. Seleziona No authentication.
  3. Leggi l’avviso sui rischi, seleziona I understand and want to continue, quindi clicca su Create as a plugin.
  4. Il plugin appare nel tuo elenco di plugin personali: aprilo e installalo usando il pulsante +.
  5. Torna alla schermata home di ChatGPT, passa dalla scheda Chat a Work, avvia una nuova conversazione, digita @ e seleziona il tuo plugin.
  6. Chiedigli di lanciare un dado a venti facce: dovrebbe chiamare roll_dice esattamente una volta con sides impostato su 20 e restituire un valore compreso tra 1 e 20.

Non fermarti al caso ideale. Prova dimensioni del dado diverse, valori non validi e richieste che non dovrebbero attivare alcuno strumento. Questo riflesso guida il resto del corso: quando il modello sceglie lo strumento sbagliato o varia i suoi argomenti, devi affinare la descrizione e lo schema dello strumento. Tieni inoltre presente che le policy del tuo account o del tuo spazio di lavoro regolano l’aggiunta di server MCP personalizzati: in un’organizzazione, questa opzione potrebbe essere limitata.

Passaggio 2: il tuo server

Installa gli SDK ufficiali

Esistono SDK ufficiali del protocollo per TypeScript (@modelcontextprotocol/sdk) e Python (mcp). Questo corso segue gli esempi di OpenAI, scritti in TypeScript utilizzando l’SDK v1. Fissa le tue versioni: a settembre 2026, @modelcontextprotocol/ext-apps 2.x—il pacchetto di interfaccia che aggiungerai nella Lezione 6—si basa sui nuovi pacchetti SDK v2 (@modelcontextprotocol/server…), che sono incompatibili con le importazioni v1.

mkdir notes-plugin && cd notes-plugin
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/sdk@^1.29 @modelcontextprotocol/ext-apps@^1.7 zod

npm pkg set type=module aggiunge "type": "module" a package.json, necessario per le istruzioni import del server.

Scrivi il server

Questo server sta in un unico file, server.js. Mantiene le note in memoria ed espone due strumenti: uno per la lettura e uno per la scrittura, separati come raccomandato nella Lezione 3.

import { createServer } from "node:http";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { z } from "zod";

const notes = []; // esempio di dati in memoria: sostituisci con il tuo storage
const schemaNotes = {
  notes: z.array(z.object({ id: z.string(), text: z.string() })),
};

function creerServeur() {
  const server = new McpServer({ name: "notes-demo", version: "0.1.0" });

  server.registerTool(
    "list_notes",
    {
      title: "List notes",
      description: "Use when the user wants to review notes saved with this plugin.",
      inputSchema: {},
      outputSchema: schemaNotes,
      annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
    },
    async () => ({
      structuredContent: { notes },
      content: [{ type: "text", text: `${notes.length} note(s) saved.` }],
    })
  );

  server.registerTool(
    "add_note",
    {
      title: "Add a note",
      description: "Use when the user asks to save a short note.",
      inputSchema: { text: z.string().min(1).max(500) },
      outputSchema: schemaNotes,
      annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
    },
    async ({ text }) => {
      notes.push({ id: `note-${notes.length + 1}`, text });
      return {
        structuredContent: { notes },
        content: [{ type: "text", text: "Note saved." }],
      };
    }
  );

  return server;
}

const PORT = Number(process.env.PORT ?? 8787);

createServer(async (req, res) => {
  const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
  if (url.pathname !== "/mcp") {
    res.writeHead(404).end("Not Found");
    return;
  }

  // Modalità stateless: nuovo server e trasporto per ogni richiesta
  const server = creerServeur();
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
    enableJsonResponse: true,
  });
  res.on("close", () => {
    transport.close();
    server.close();
  });

  try {
    await server.connect(transport);
    await transport.handleRequest(req, res);
  } catch (error) {
    console.error("MCP Error:", error);
    if (!res.headersSent) res.writeHead(500).end("Internal server error");
  }
}).listen(PORT, () => console.log(`MCP server ready on http://localhost:${PORT}/mcp`));

Tre dettagli sono fondamentali. Ogni strumento dichiara un titolo, una descrizione dell’intento, degli schemi e annotazioni esatte: questo è il suo “profilo” per il modello. Ogni risultato combina structuredContent, riutilizzabile dal modello, e content, un breve messaggio di testo. Infine, qualsiasi indirizzo diverso da /mcp restituisce un 404: l’esempio di OpenAI lo fa per i route di scoperta OAuth che non stai ancora utilizzando, impedendo a ChatGPT di mostrare errori 502 durante i tuoi test non autenticati. Quello stesso esempio aggiunge una risposta per la richiesta CORS preliminare (OPTIONS) e una GET / per le sonde di salute; includile se il tuo hosting le prevede.

Testa in locale con MCP Inspector

node server.js
npx @modelcontextprotocol/inspector@latest

Nell’Inspector, scegli Streamable HTTP, inserisci http://localhost:8787/mcp e connettiti. Verifica che l’inizializzazione abbia successo, che entrambi gli strumenti appaiano con i loro schemi e annotazioni, quindi chiamali con input validi e non validi: una stringa di testo vuota deve essere rifiutata dallo schema.

Esponi il server e collegalo

ChatGPT deve raggiungere il tuo server da Internet. Durante lo sviluppo, un tunnel è sufficiente: la documentazione cita ngrok:

ngrok http 8787

Ottieni un indirizzo HTTPS pubblico. Collegalo come nel Passaggio 1, includendo il percorso /mcp (ad esempio https://<subdomain>.ngrok.app/mcp), installa il plugin risultante, quindi invocalo con @: “Salva una nota: chiama il fornitore lunedì”. ChatGPT visualizza i dati scambiati con lo strumento, permettendoti di verificare input e output.

Un tunnel di sviluppo funziona solo per le prove: la pubblicazione richiede un endpoint HTTPS pubblico e stabile (Lezione 5).

Ricarica dopo ogni modifica

ChatGPT memorizza nella cache i metadati del tuo server. Dopo qualsiasi modifica al nome, alla descrizione, allo schema, all’annotazione, all’autenticazione o alla risorsa di interfaccia: ridistribuisci o riavvia il server, apri la connessione su chatgpt.com/plugins, seleziona Refresh, verifica che i metadati pubblicizzati siano cambiati, quindi apri una nuova conversazione per rieseguire i tuoi test. Saltare questo passaggio significa testare la vecchia versione senza rendersene conto.

Punti chiave

  • Crea un plugin personale tramite Add custom MCP server, quindi invocalo con @ in ChatGPT
  • SDK ufficiali: @modelcontextprotocol/sdk (TypeScript) e mcp (Python); fissa la v1 con ext-apps 1.x per seguire gli esempi di OpenAI
  • Server minimo: McpServer, registerTool, trasporto streamable HTTP su /mcp
  • Usa MCP Inspector per i test locali, un tunnel per le prove con ChatGPT
  • Dopo ogni modifica ai metadati: Refresh, quindi avvia una nuova conversazione