Strumenti esterni (MCP)

MCP (Model Context Protocol) è uno standard aperto per dare a un'AI un insieme di azioni che può eseguire. Un programma che lo parla, un server MCP, pubblica le sue azioni come strumenti (tools) a un unico indirizzo web: controllare la disponibilità, cercare un ordine, leggere una riga da una tabella. Collega qui quell'indirizzo e quegli strumenti diventano cose che il tuo assistente di supporto può chiamare mentre risponde a un cliente.

Pommy si trova su entrambi i lati di questo standard, ed è bene chiarirlo prima di proseguire. Questa pagina riguarda il lato in cui Pommy è il client: il tuo assistente di supporto usa il server di qualcun altro. L'altro lato, in cui il tuo agente di programmazione usa Pommy come server, è Coding Agents, e i due non hanno nulla in comune se non il nome.

Prima di iniziare#

• Un server MCP funzionante e raggiungibile da internet, al suo indirizzo endpoint completo, ad esempio https://tools.example.com/mcp, percorso incluso.
• Streamable HTTP. È il trasporto che Pommy usa: invia una richiesta al tuo indirizzo e legge la risposta. Un server costruito con il vecchio stile SSE a due endpoint non si collega, qualunque opzione tu scelga nel menu a tendina.
• Tutto ciò che serve al tuo server per fidarsi del chiamante: in pratica un token che invii in un header.
• Spazio nel tuo piano. Il numero di server MCP per progetto è un limite del piano, e il piano Free non ne include nessuno. Oltre il limite, l'aggiunta fallisce con un messaggio che indica il limite.

Aggiungere un server#

1. Apri API Connections

   API Connections nel menu a sinistra, poi Add MCP Server (aggiungi server MCP).

2. Dagli un nome e incolla l'indirizzo

   Il nome serve solo a te: "API ordini" basta. Il Server URL è l'endpoint indicato nella documentazione del tuo server, percorso compreso. Lascia Transport su Streamable HTTP.

3. Aggiungi gli header necessari

   Custom Headers accetta un numero qualsiasi di coppie nome/valore, e Pommy le invia con ogni singola richiesta: il caso tipico è un header Authorization con un bearer token. Non c'è un campo separato per il token: ci si autentica con un header. I valori sono mascherati e l'icona a forma di occhio li mostra.

4. Add and Discover Tools (aggiungi e scopri gli strumenti)

   Pommy si collega subito e chiede al server cosa sa fare. Apri la nuova riga e vedrai gli strumenti trovati, ciascuno con la descrizione fornita dal tuo server. Un elenco vuoto significa che il server non è raggiungibile oppure non espone strumenti.

5. Assegnalo a un assistente

   Un nuovo server non è ancora collegato a nessun assistente, quindi per i tuoi clienti non è cambiato nulla. Questo passaggio lo fa la sezione successiva.

Attivare gli strumenti per un assistente#

Gli strumenti si attivano per server e per assistente. Apri AI Agent, modifica l'assistente e vai al passo MCP Tools: elenca i server del progetto con un indicatore di stato e il numero di strumenti. Seleziona quelli che questo assistente può usare e salva.

Selezionare un server dà all'assistente tutti i suoi strumenti: non c'è un interruttore per singolo strumento. Se un assistente deve raggiungere solo alcuni strumenti, esponili su un secondo server e collega quello.

Perché uno strumento arrivi in una conversazione devono essere attivi due interruttori: l'interruttore Active del server in API Connections (il pulsante di pausa sulla sua riga) e la selezione in quel passo. Mettere in pausa un server toglie i suoi strumenti a tutti gli assistenti in un colpo solo e conserva le assegnazioni per quando lo riattivi.

Cosa viene detto all'assistente#

Per ogni strumento l'assistente riceve il nome, la descrizione e l'elenco dei parametri esattamente come li riporta il tuo server: Pommy non aggiunge spiegazioni proprie. Quindi la descrizione sul tuo server è l'unica istruzione che l'assistente riceve su quando usare lo strumento. Scrivila come una frase sulla situazione ("Restituisce lo stato attuale di un ordine dato il numero d'ordine"), non come riferimento API.

Il risultato va all'assistente, non al cliente: l'assistente lo legge e scrive la risposta con parole sue. Il tuo team vede la chiamata, il risultato e quanto tempo ha richiesto nell'Agent console mentre la conversazione è in corso.

I nomi devono essere univoci. Uno strumento che si chiama come uno di quelli di Pommy, come search_knowledge_base, book_calendar_appointment, transfer_to_human e gli altri, viene scartato senza avviso, e due server collegati che espongono lo stesso nome di strumento sono indistinguibili per l'assistente. Nel dubbio, aggiungi un prefisso ai tuoi.

Tenerlo sotto controllo#

L'elenco di API Connections dedica una riga a ogni server: nome con indicatore di stato, indirizzo, trasporto e numero di strumenti, stato di salute e data dell'ultimo controllo. Facendo clic sulla riga la apri: header (modificabili), assistenti che lo usano, elenco completo degli strumenti trovati e quattro azioni.

• Refresh Tools (aggiorna strumenti): chiede di nuovo al server cosa sa fare e sostituisce l'elenco salvato. È l'unica cosa che lo aggiorna: non c'è una nuova scansione programmata, quindi uno strumento che aggiungi dal tuo lato resta invisibile a Pommy finché non premi questo pulsante.
• Health Check (controllo di stato): una rapida verifica del tipo "stai rispondendo?". Non dice nulla sul funzionamento del singolo strumento.
• Pause (pausa): toglie gli strumenti del server da tutte le conversazioni senza eliminare nulla.
• Delete (elimina): rimuove il server e libera il posto nel tuo piano.

Healthy significa che l'ultimo controllo ha raggiunto il server e ha trovato strumenti. Unhealthy significa che la risposta era vuota o il controllo è fallito. Unknown significa che non è ancora stato controllato nulla. Lo stato non è mai più dettagliato di così: quando qualcosa non va, il motivo è dal lato del tuo server, nei suoi log.

Quando qualcosa non funziona#