Server MCP

Un server MCP (Model Context Protocol) è un endpoint che espone uno o più strumenti che l'AI può scoprire e usare a runtime. Ti permette di evolvere il set di strumenti senza modificare la configurazione dell'agente: aggiungi un tool sul tuo server, l'AI lo vede al prossimo discovery.

Cosa è un server MCP

MCP è un protocollo aperto basato su JSON-RPC 2.0 trasportato su HTTP (Streamable HTTP). Il server espone primitive come tools/list e tools/call. yourang.ai interroga il tuo server all'inizio di ogni chiamata per scoprire gli strumenti, poi li espone all'AI come funzioni invocabili. Ogni invocazione passa per il tuo server, che esegue la logica e risponde.

Come l'AI comunica con il server MCP

1. 1

   Discovery iniziale

   All'avvio della chiamata, yourang.ai invia una richiesta tools/list al tuo server MCP. Il server risponde con la lista degli strumenti (nome, descrizione, schema parametri). Il discovery non porta dati cliente: serve solo a costruire il catalogo strumenti.

2. 2

   Sessione MCP

   Alla prima risposta del server riceviamo un header Mcp-Session-Id. Lo riusiamo per tutte le chiamate successive (tools/list e tools/call) in quella stessa chiamata vocale, così il tuo server può tenere stato se serve.

3. 3

   Esposizione all'agente

   Gli strumenti scoperti sono passati al modello AI come function callable, insieme agli strumenti predefiniti e agli External Tools.

4. 4

   Invocazione (tools/call)

   Quando il modello decide di usare uno strumento MCP, yourang.ai chiama tools/call con nome strumento + argomenti. Insieme agli argomenti, alleghiamo automaticamente un blocco _meta.caller con i metadati cliente noti (vedi sezione sotto).

5. 5

   Risposta all'AI

   Il contenuto testuale della risposta MCP viene estratto dai blocchi content[].text, concatenato e restituito al modello come function output. La conversazione prosegue.

Payload JSON-RPC

Le due richieste che il tuo server riceverà sono semplici e standard. Discovery non passa metadati; l'invocazione sì.

{
 "jsonrpc": "2.0",
 "method": "tools/list",
 "params": {},
 "id": "<uuid>"
}

Metadati cliente passati automaticamente

Quando l'AI invoca uno strumento, yourang.ai arricchisce la richiesta con un blocco _meta.caller contenente il contesto della chiamata corrente. Sono campi standard, popolati con quello che già sappiamo del cliente al momento della chiamata.

call_sid

UUID univoco della chiamata in corso. Utile per correlare i log lato server MCP con la cronologia chiamate in yourang.ai.

agent_id

UUID dell'agente AI che ha invocato lo strumento. Usalo se hai più agenti che condividono lo stesso server MCP e devi differenziare la logica.

organization_id

UUID dell'organizzazione (tenant). Tipicamente il primo filtro che applichi sul tuo server: ogni chiamata appartiene a un singolo tenant.

phone

Numero di telefono del chiamante in formato E.164 (es. +39 333 1234567), quando disponibile.

name

Nome del contatto, se lo abbiamo già in rubrica per quel numero. Assente se il chiamante è sconosciuto.

email

Email del contatto, se presente nella scheda contatto in yourang.ai.

contact_id

UUID del contatto in yourang.ai se il numero ha trovato match in rubrica. Usalo per recuperare ulteriori dati senza dover passare per la ricerca per telefono.

Come configurarne uno

1. 1

   Apri la configurazione dell'agente

   /ai-agents → seleziona l'agente → tab MCP.

2. 2

   Inserisci URL e autenticazione

   URL HTTPS del server MCP, metodo di autenticazione (none, Bearer, API key, custom headers).

3. 3

   Salva e verifica la discovery

   Il pannello mostra il numero di strumenti scoperti l'ultima volta e l'orario. Puoi forzare un nuovo discovery con un click.

4. 4

   Abilita o disabilita strumenti individuali

   Anche se il server espone 30 strumenti, puoi attivare solo i 5 che ti servono per quell'agente.

Autenticazione e headers

Ogni richiesta MCP include sempre Content-Type e Accept standard, più l'header di autenticazione che hai configurato e un Mcp-Session-Id che riusiamo per tutte le chiamate della stessa sessione vocale.

# Sempre presenti
Content-Type: application/json
Accept: application/json, text/event-stream
Mcp-Session-Id: <restituito dal server alla prima risposta>

# Auth (in base alla configurazione)
Authorization: Bearer <token>
# oppure
X-API-Key: <chiave>

None

Server pubblico. Solo per test o tool senza dati sensibili.

Bearer

Header Authorization: Bearer <token> ad ogni richiesta.

API key

Header HTTP a tua scelta (es. X-API-Key).

Custom headers

Combinazioni multiple (es. X-Tenant + X-Signature).

Quando preferire MCP vs External Tool

• Hai molti strumenti correlati. Un server MCP che espone 10 strumenti CRM (lookup, create, update, list, ecc.) è più gestibile di 10 External Tools separati.
• Vuoi evolvere il catalogo strumenti. Aggiungi tool sul tuo server senza dover toccare la configurazione su yourang.ai: il prossimo discovery li trova.
• Devi parlare con un solo endpoint. Un External Tool è più leggero: meno overhead, configurazione diretta.