Vai al contenuto principale
Italiano— Scegli una lingua
Menu

MCP e Connettori: Collegare Servizi Esterni

Lezione 9 di 25 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. MCP e Connettori: Collegare Servizi Esterni
  2. Cos’è l’MCP?
  3. Collegare un Server MCP
  4. Server MCP Remoti tramite SSE
  5. Connettori OpenAI
  6. Combinare MCP e Strumenti Funzione
  7. Filtrare gli Strumenti MCP
  8. Gestire gli Errori MCP
  9. Punti chiave

Aggiornato il 2 novembre 2026 — Agent Builder. Il 3 giugno 2026, OpenAI ha annunciato la chiusura di Agent Builder, prevista per il 30 novembre 2026; ChatKit rimane disponibile. D’ora in poi, OpenAI indirizza gli utenti all’SDK Agents o agli agenti dello spazio di lavoro ChatGPT. Dal 10 settembre 2026, OpenAI offre una beta pubblica delle API Agents che ospita l’orchestrazione degli agenti (vedi ChatGPT nel 2026, Lezione 10).

MCP e Connettori: Collegare Servizi Esterni

Il Model Context Protocol (MCP) è uno standard aperto che permette al tuo agente di connettersi a servizi esterni in modo standardizzato. Invece di riscrivere le integrazioni per ogni servizio, colleghi un server MCP e il tuo agente acquisisce istantaneamente nuovi strumenti. Dove avresti dovuto scrivere trecento righe di codice client per GitHub, ora ti serve una sola dichiarazione di server.

Cos’è l’MCP?

L’MCP è uno standard aperto che definisce come un client—il tuo agente—comunica con un server, ovvero un servizio esterno. Ogni server MCP espone strumenti che il tuo agente può utilizzare. Il protocollo gestisce il trasporto, la serializzazione e la scoperta degli strumenti. Quest’ultima funzionalità è la più preziosa per il lavoro quotidiano: l’agent interroga il server per vedere cosa può fare, così non devi mantenere manualmente un elenco. L’SDK Agents include il supporto nativo per MCP e si connette a qualsiasi server compatibile.

Collegare un Server MCP

L’SDK fornisce la classe MCPServerStdio per i server locali che comunicano tramite stdin/stdout, tipicamente un processo Node avviato con npx.

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

# Server MCP locale (comunica tramite stdin/stdout)
file_server = MCPServerStdio(
    name="File Manager",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "/path/to/folder"],
)

async def main():
    async with file_server:
        agent = Agent(
            name="File Agent",
            instructions="Gestisci i file per l'utente.",
            mcp_servers=[file_server],
        )
        result = await Runner.run(agent, "Elenca i file nella cartella radice.")
        print(result.final_output)

Il blocco async with non è solo decorativo: avvia il processo del server, ne scopre gli strumenti e lo arresta correttamente quando il blocco termina. Un agente creato al di fuori di questo contesto non avrà alcuno strumento a disposizione.

Server MCP Remoti tramite SSE

Per i server ospitati, usa MCPServerSse e il trasporto SSE (Server-Sent Events). La logica rimane la stessa; cambiano solo l’URL e le intestazioni di autenticazione.

from agents.mcp import MCPServerSse

github_server = MCPServerSse(
    name="GitHub",
    url="https://mcp.github.com/sse",
    headers={"Authorization": "Bearer ghp_your_token"},
)

async def main():
    async with github_server:
        agent = Agent(
            name="DevOps Agent",
            instructions="Gestisci i repository GitHub.",
            mcp_servers=[github_server],
        )
        result = await Runner.run(
            agent,
            "Crea una issue nel repo my-project con il titolo 'Critical Bug'"
        )
        print(result.final_output)

Connettori OpenAI

Oltre all’MCP, OpenAI offre connettori gestiti direttamente sulla piattaforma. Si integrano in Agent Builder e rimangono utilizzabili tramite l’SDK senza che tu debba ospitare un server.

from agents import Agent, Runner

# I connettori configurati in Agent Builder sono automaticamente disponibili
agent = Agent(
    name="CRM Agent",
    instructions="""Sei un assistente CRM. Usa i connettori
    per accedere a Salesforce, HubSpot e Google Workspace.""",
    model="gpt-5.6-terra",
    # I connettori sono collegati alla configurazione dell'agente sulla piattaforma
)

L’assenza del parametro mcp_servers ha senso: i connettori sono legati alla configurazione dell’agente sulla piattaforma. Gestiscono per te l’autenticazione OAuth, la paginazione e il rate limiting: tre aree che, se gestite manualmente, richiedono molto tempo.

Combinare MCP e Strumenti Funzione

Non devi scegliere. Un singolo agente può usare un server MCP per l’accesso ai dati e le tue funzioni personali per la logica di business che non vuoi delegare.

from agents import Agent, Runner, function_tool
from agents.mcp import MCPServerStdio

@function_tool
def calculate_invoice(amount_excl_tax: float, vat_rate: float = 20.0) -> str:
    """Calcola l'importo totale IVA inclusa per una fattura."""
    amount_incl_tax = amount_excl_tax * (1 + vat_rate / 100)
    return f"Imponibile: €{amount_excl_tax}, IVA {vat_rate}%: €{amount_excl_tax * vat_rate / 100:.2f}, Totale: €{amount_incl_tax:.2f}"

db_server = MCPServerStdio(
    name="Database",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost/mydb"],
)

async def main():
    async with db_server:
        agent = Agent(
            name="Accounting Agent",
            instructions="""Gestisci la contabilità.
            Usa il database per i dati dei clienti
            e la funzione di calcolo per le fatture.""",
            tools=[calculate_invoice],
            mcp_servers=[db_server],
        )
        result = await Runner.run(
            agent,
            "Recupera gli ordini per il cliente Alice e calcola la fattura totale"
        )
        print(result.final_output)

Il calcolo dell’IVA rimane nel tuo codice, dove è testabile e verificabile; il recupero degli ordini passa attraverso il server MCP PostgreSQL. Questa è la separazione che dovresti cercare di ottenere.

Filtrare gli Strumenti MCP

Un server MCP può esporre decine di strumenti, la maggior parte dei quali non sarà rilevante per il tuo caso d’uso, e ognuno di essi consuma contesto e aumenta il rischio di una chiamata inappropriata. Inizia ispezionando cosa è effettivamente disponibile.

server = MCPServerStdio(
    name="GitHub",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-github"],
)

# Puoi filtrare durante la connessione
async with server:
    tools = await server.list_tools()
    # Ispeziona gli strumenti disponibili
    for tool in tools:
        print(f"- {tool.name}: {tool.description}")

Gestire gli Errori MCP

Un server MCP è un processo o un servizio remoto: potrebbe non avviarsi, perdere la connessione o avere un token scaduto. Prevedi una modalità degradata invece di lasciare che l’eccezione risalga fino all’utente.

from agents.mcp import MCPServerStdio

async def create_agent_with_mcp():
    server = MCPServerStdio(
        name="External Service",
        command="npx",
        args=["-y", "my-mcp-server"],
    )

    try:
        async with server:
            agent = Agent(
                name="My Agent",
                instructions="Usa il servizio esterno.",
                mcp_servers=[server],
            )
            result = await Runner.run(agent, "Esegui il compito.")
            return result.final_output
    except Exception as e:
        # Fallback senza MCP
        fallback_agent = Agent(
            name="My Agent (modalità degradata)",
            instructions="Il servizio esterno non è disponibile. Informa l'utente.",
        )
        result = await Runner.run(fallback_agent, "Il servizio non è disponibile.")
        return result.final_output

L’agente di fallback non finge di funzionare: annuncia l’indisponibilità. Un agente che inventa una risposta quando la sua fonte dati è offline costa molto più di uno che ammette di non poter procedere.

Punti chiave

  • MCP è un protocollo aperto per collegare servizi esterni al tuo agente
  • Usa MCPServerStdio per i server locali e MCPServerSse per quelli remoti
  • I Connettori OpenAI sono integrazioni gestite sulla piattaforma
  • Puoi combinare strumenti funzione e server MCP nello stesso agente
  • Gestisci gli errori di connessione MCP con una modalità degradata