Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Il server MCP: strumenti, risultati e distribuzione

Lezione 5 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Il server, la sua identità e le sue istruzioni
  2. Uno strumento per azione
  3. Risultati utili senza interfaccia
  4. Annotazioni ed elicitation
  5. Account multipli e conoscenza aziendale
  6. Distribuzione dell’endpoint
  7. Evolvere senza rompere
  8. Promemoria sulla sicurezza
  9. Punti chiave

Lezione riscritta il 3 novembre 2026 sulla base della pagina Build an MCP server della documentazione dei plugin OpenAI e del codice dell’MCP TypeScript SDK (1.32.2). La lezione precedente descriveva le “azioni” (defineAction, ActionError) provenienti da un SDK inesistente; questo ruolo spetta ora agli strumenti MCP. Fonti: Build an MCP server · MCP TypeScript SDK.

Il server, la sua identità e le sue istruzioni

Crea un server MCP con un nome e una versione stabili. Durante l’inizializzazione, può restituire anche un campo instructions che ChatGPT e Codex leggono insieme ai metadati degli strumenti. Riserva questo campo alle linee guida valide per tutti gli strumenti, come un ordine di chiamata obbligatorio o un limite di velocità condiviso, e mantieni il contenuto principale entro i primi 512 caratteri. Non copiare e incollare qui le descrizioni degli strumenti e non cercare di modificare la personalità del modello.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer(
  { name: "acme-projects", version: "1.0.0" },
  {
    instructions:
      "Before modifying a project, call get_project to confirm its ID and status.",
  }
);

Uno strumento per azione

Crea uno strumento per ogni azione distinta: list_projects, get_project, update_project, invece di un unico strumento generico con numerose modalità. Ogni strumento combina un nome orientato all’azione, un titolo leggibile, una descrizione che spiega quando usarlo, uno schema di input esplicito, uno schema di output se restituisce dati strutturati, annotazioni precise e un gestore che autorizza la richiesta prima di agire. Il modello si basa su questi metadati per decidere se e come chiamare lo strumento: trattalo come parte dell’esperienza utente.

import { z } from "zod";

const project = z.object({ id: z.string(), name: z.string(), status: z.enum(["active", "archived"]) });

server.registerTool(
  "get_project",
  {
    title: "View a project",
    description:
      "Use when the user wants details about a specific project in their Acme workspace. " +
      "Requires the ID returned by list_projects.",
    inputSchema: { id: z.string().min(1) },
    outputSchema: { project: project },
    annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
  },
  async ({ id }, extra) => {
    const user = await authenticate(extra); // Your access control (Lesson 8)
    const found = await loadProject(user, id); // Your data access
    if (!found) {
      return {
        isError: true,
        content: [{ type: "text", text: `No project ${id} is accessible with this account.` }],
      };
    }
    return {
      structuredContent: { project: found },
      content: [{ type: "text", text: `Project "${found.name}" (${found.status}).` }],
    };
  }
);

authenticate e loadProject sono le tue funzioni. Il punto critico è il loro posizionamento: l’autorizzazione avviene sul server, con ogni richiesta. Non fare mai affidamento sul modello per decidere se un utente ha il permesso di accedere ai dati.

Risultati utili senza interfaccia

Un risultato di uno strumento può contenere tre elementi:

  • structuredContent: dati concisi che il modello può ispezionare e riutilizzare nelle chiamate successive;
  • content: testo o altri contenuti MCP che lo aiutano a rispondere;
  • _meta: dati destinati al client, nascosti al modello.

Restituisci informazioni sufficienti affinché il modello porti a termine il lavoro senza una componente visiva, utilizzando ID stabili che gli strumenti successivi possano riutilizzare. Due comportamenti dell’SDK meritano attenzione. Uno strumento che dichiara un outputSchema deve restituire un structuredContent conforme in tutti i risultati positivi; altrimenti, l’SDK genera un errore di validazione. Un errore di business, come un progetto mancante o un’azione negata, viene segnalato da un risultato con isError: true accompagnato da testo esplicativo che il modello può inoltrare all’utente; questo tipo di risultato bypassa la validazione dello schema di output.

Non includere mai segreti, token di accesso o dati personali non necessari in un risultato e non trattare _meta come un nascondiglio sicuro: questo campo è nascosto al modello, ma non è protetto.

Annotazioni ed elicitation

Le annotazioni devono riflettere il comportamento reale dello strumento: imposta readOnlyHint su true solo se non può modificare nulla, destructiveHint su true se può causare un effetto irreversibile o difficile da annullare, e openWorldHint su true se tocca internet pubblico o entità esterne aperte. Aiutano ChatGPT e Codex a scegliere il comportamento di conferma corretto; non sostituiscono la logica di autorizzazione, validazione o conferma sul tuo server.

Quando il server necessita di informazioni strutturate mancanti nella chiamata, come una data o una scelta tra due opzioni, può richiederle tramite elicitation, un meccanismo del protocollo MCP. Limita questo a ciò che l’utente può ragionevolmente fornire; non usarlo mai per raccogliere segreti o bypassare l’autenticazione normale.

Account multipli e conoscenza aziendale

Due compatibilità opzionali migliorano l’integrazione. Per aiutare gli utenti che collegano più account, esponi uno strumento di profilo autenticato, di sola lettura e contrassegnato con _meta["openai/profile"]: true. OpenAI lo usa per identificare gli account collegati e aiutare gli utenti a distinguerli. Il profilo deriva dalle credenziali validate della richiesta e ogni chiamata rimane limitata a quelle credenziali.

La funzionalità company knowledge di ChatGPT può utilizzare gli strumenti di sola lettura del tuo server. Per rendere un plugin idoneo come fonte, implementa gli schemi di input standard per gli strumenti search e fetch, contrassegna gli altri strumenti di sola lettura con readOnlyHint: true e restituisci URL assoluti, apribili dall’utente, per le fonti che il modello deve citare.

Distribuzione dell’endpoint

La sottomissione pubblica richiede un server a un indirizzo HTTPS stabile e pubblicamente raggiungibile. Questo endpoint deve supportare il trasporto streamable HTTP, rispondere a un URL stabile (tipicamente terminante in /mcp), soddisfare i requisiti di latenza e disponibilità dei tuoi flussi di lavoro, raggiungere i tuoi servizi e dati, preservare i confini di autenticazione e autorizzazione e produrre log e metriche per l’inizializzazione e i fallimenti delle chiamate agli strumenti.

Il Secure MCP Tunnel di OpenAI ti consente di collegare un server privato a ChatGPT, ma non soddisfa i requisiti per la sottomissione pubblica, così come non lo fanno un tunnel temporaneo o un indirizzo locale. Se il server deve rimanere privato, posiziona davanti ad esso un proxy HTTPS pubblico: mTLS gestito da OpenAI autentica ChatGPT come client, OAuth 2.1 autentica i tuoi utenti e può essere aggiunta una whitelist di IP, inclusi gli intervalli pubblicati da OpenAI per i connettori ChatGPT, aggiornati automaticamente, ma questa non sostituisce mai l’autenticazione.

Prima di andare online: inietta le credenziali tramite il gestore dei segreti del tuo host, configura il server di autorizzazione e i redirect, imposta timeout e limiti di velocità per gli strumenti costosi o visibili esternamente, rimuovi le risposte di debug e i dati personali non necessari e verifica che i log non contengano token o risultati sensibili. Dopo la distribuzione, esegui nuovamente MCP Inspector sull’indirizzo di produzione.

Evolvere senza rompere

Mantieni i nomi degli strumenti pubblicati e gli schemi retrocompatibili: aggiungi campi o strumenti, ma non rompere i contratti esistenti. Se i metadati cambiano, aggiorna la connessione ed esegui nuovamente la tua suite di valutazione prima di inviare. Per un’interfaccia, cambia l’ID della risorsa quando HTML, JavaScript o CSS evolvono in modo tale da poter rompere un componente memorizzato nella cache.

Promemoria sulla sicurezza

  • Tutto l’input degli strumenti non è attendibile: validalo e applica l’autorizzazione sul server
  • Richiedi conferma per scritture ad alto impatto
  • Mantieni segreti e dati sensibili fuori dai metadati e dai risultati
  • Registra abbastanza dati per indagare, ma escludi credenziali e dati personali non necessari
  • Applica limiti di velocità alle azioni costose o visibili esternamente

Punti chiave

  • Un server nominato e versionato con brevi instructions trasversali
  • Uno strumento per azione, con titolo, descrizione dell’intento, schemi, annotazioni e autorizzazione nel gestore
  • structuredContent conforme allo schema di output, isError: true per gli errori di business, nulla di segreto in _meta
  • Pubblicazione: HTTPS stabile e pubblico tramite streamable HTTP; il Secure MCP Tunnel non è sufficiente
  • Contratti retrocompatibili e ID risorsa versionati