🇮🇹 IT

🔧 MCP Tool

Definisce uno strumento esterno che un nodo Agent può chiamare durante il suo ciclo di ragionamento, usando il Model Context Protocol (MCP). Collega uno o più nodi MCP Tool alla porta tool_in di un Agent. L'agente decide autonomamente quando e se invocare ogni strumento.

Categoria: AI & Agenti · Identificatore tipo: mcp_tool · Solo modalità grafo

Panoramica

Il Model Context Protocol (MCP) è uno standard che permette ai modelli AI di chiamare strumenti esterni — programmi, API o servizi — come parte del loro ragionamento. Quando un agente ha strumenti disponibili, può decidere durante la risposta di chiamarne uno, ricevere il risultato e incorporarlo nella risposta finale. Questo permette agli agenti di effettuare ricerche, eseguire calcoli, interrogare database o interagire con qualsiasi sistema esterno.

In Flusso, ogni nodo MCP Tool definisce uno strumento. Il nodo specifica il nome dello strumento, una descrizione che il modello usa per decidere quando chiamarlo, e come Flusso deve connettersi allo strumento — sia lanciando un sottoprocesso locale (trasporto stdio) sia connettendosi a un server HTTP JSON-RPC (trasporto SSE).

Puoi collegare più nodi MCP Tool a un singolo Agent. L'agente riceve l'elenco completo degli strumenti disponibili e seleziona quello appropriato in base alla richiesta dell'utente.

Scrivere buone descrizioni è fondamentale. Il modello usa la descrizione per decidere se un dato strumento è pertinente. Scrivi descrizioni che indichino chiaramente cosa fa lo strumento, quali input si aspetta e quando dovrebbe essere usato. Descrizioni vaghe portano l'agente a ignorare lo strumento o a chiamarlo nel momento sbagliato.

Configurazione

Campo	Stato	Descrizione
Nome	Obbligatorio	Il nome dello strumento visibile all'agente. Usa un nome breve, descrittivo, in minuscolo con underscore — ad esempio `search_web`, `get_weather`, `query_database`. Il modello fa riferimento a questo nome quando decide di chiamare lo strumento.
Descrizione	Obbligatorio	Una spiegazione in linguaggio naturale di cosa fa lo strumento. Il modello la legge per decidere quando e se invocare lo strumento. Sii specifico: descrivi lo scopo dello strumento, quali argomenti accetta e cosa restituisce.
Trasporto	Obbligatorio	`stdio` — Flusso lancia un sottoprocesso locale sul server e comunica tramite stdin/stdout. `SSE` — Flusso si connette a un endpoint HTTP che implementa JSON-RPC su Server-Sent Events.
Comando	Condizionale (stdio)	L'eseguibile da lanciare per il sottoprocesso dello strumento. Ad esempio `python`, `node`, o il percorso completo di un binario. Usato solo quando il Trasporto è `stdio`.
Argomenti	Condizionale (stdio)	Argomenti separati da spazi passati al comando. Ad esempio, se Comando è `python` e Argomenti è `tools/my_tool.py`, Flusso eseguirà `python tools/my_tool.py`. Usato solo quando il Trasporto è `stdio`.
Ambiente	Opzionale (stdio)	Variabili d'ambiente chiave-valore da passare al sottoprocesso. Usalo per fornire chiavi API, percorsi di configurazione o altre impostazioni necessarie allo script dello strumento. Inserite come coppie `CHIAVE=valore`, una per riga.
URL	Condizionale (SSE)	L'URL completo dell'endpoint HTTP per il server MCP, ad esempio `https://my-tools-server.example.com/mcp`. Usato solo quando il Trasporto è `SSE`.
Header	Opzionale (SSE)	Header HTTP personalizzati da inviare con ogni richiesta al server MCP. Comunemente usati per passare una chiave API per l'autenticazione, ad esempio `Authorization: Bearer my-secret-key`. Inseriti come coppie chiave-valore.

stdio vs Trasporto SSE

	stdio	SSE (HTTP)
Come funziona	Flusso avvia un sottoprocesso sul server e comunica tramite standard input/output.	Flusso effettua richieste HTTP POST a un server JSON-RPC remoto.
Ideale per	Script locali, strumenti Python o Node.js sotto il tuo controllo, strumenti che necessitano accesso diretto al server.	Strumenti remoti, server MCP di terze parti, servizi cloud, strumenti che devono scalare indipendentemente.
Sicurezza	Il sottoprocesso viene eseguito con i permessi del server Flusso. Verifica attentamente i tuoi script.	La comunicazione avviene tramite HTTP(S). Usa HTTPS e autentica con gli header.
Latenza	Bassa (processo locale).	Dipende dal round-trip di rete verso il server remoto.

Dati di Output

Nessun output diretto. Il nodo MCP Tool di per sé non produce campi di output. Quando un agente chiama uno strumento, il valore restituito dallo strumento viene iniettato automaticamente nel contesto dell'agente. La risposta finale dell'agente (dopo eventuali chiamate a strumenti) è disponibile come di consueto in agent.output.text e agent.output.tool_calls.

Esempio di Utilizzo

Collegare uno strumento di ricerca web a un agente

Questo esempio configura un MCP Tool che esegue uno script Python per effettuare una ricerca web, e lo collega a un agente che risponde a domande su eventi di attualità.

Aggiungi un nodo MCP Tool dalla barra laterale AI & Agenti. Imposta Nome su search_web.
Scrivi una descrizione chiara:
Search the web for up-to-date information about a topic. Use this tool when the user asks about recent events, current data, or anything that may have changed after the model's training cutoff. Input: a search query string. Returns: a list of results with titles, URLs, and snippets.
Imposta Trasporto su stdio. Imposta Comando su python e Argomenti su tools/web_search.py. Aggiungi la chiave API in Ambiente: SEARCH_API_KEY=your-key-here.
Disegna un collegamento dal nodo MCP Tool alla porta tool_in (T) sul tuo nodo Agent.
Esegui il workflow. Quando il prompt dell'agente chiede informazioni su eventi di attualità, chiamerà automaticamente search_web, incorporerà i risultati e restituirà una risposta fondata.

Suggerimenti e Note

Più strumenti per agente. Puoi collegare quanti nodi MCP Tool desideri a un singolo agente. Non c'è un limite rigido, ma tieni presente che un gran numero di strumenti aumenta il contesto consumato dalle descrizioni degli strumenti. Mantieni le descrizioni concise.
Sicurezza con stdio. Quando usi il trasporto stdio, il sottoprocesso viene eseguito direttamente sul server Flusso con gli stessi permessi dell'applicazione. Esegui solo script che hai scritto o verificato completamente. Non passare valori forniti dall'utente direttamente nel comando o negli argomenti senza sanificazione.
L'agente controlla l'invocazione degli strumenti. Non puoi forzare l'agente a chiamare uno strumento specifico. Il modello decide in base al prompt dell'utente e alla descrizione dello strumento. Se un agente non sta chiamando uno strumento che ti aspetti, rivedi e migliora la descrizione.
I risultati degli strumenti sono visibili nel log dell'esecuzione. Ogni chiamata a strumento e il suo risultato vengono registrati nella vista dettaglio dell'esecuzione del workflow. Puoi ispezionare esattamente cosa l'agente ha inviato allo strumento e cosa è tornato.

Nodi Correlati

Agent — il nodo che chiama gli strumenti a runtime.
Model Config — specifica il modello AI per l'agente in modalità grafo.
Memory — collega la memoria persistente a un agente in modalità grafo.