Server MCP

Il server MCP di Diaform collega il tuo agente IA al feedback che raccogli. Dopo averlo collegato, puoi fare all’agente domande come “Di cosa si sono lamentati i clienti questo mese?” e lui recupera le conversazioni, i riepiloghi e i report.

MCP (Model Context Protocol) è lo standard con cui gli agenti IA si collegano a strumenti esterni. Il server espone gli stessi dati dell’API REST, è in sola lettura e usa la stessa chiave API.

Prima di iniziare#

Ti servono un piano Pro, Business o Enterprise e una chiave API. Proprietari e amministratori creano le chiavi in Impostazioni → Generali → Chiavi API. Vedi Panoramica dell’API.

Impostazione	Valore
URL del server	`https://diaform.io/api/mcp`
Trasporto	Streamable HTTP
Autenticazione	Header `Authorization: Bearer dia_org_live_...`

Una chiave dà all’agente accesso in lettura a tutti i progetti della tua organizzazione. Crea una chiave separata per ogni agente, così puoi revocarne una senza toccare le altre.

Collega il tuo agente#

Scegli il tuo agente:

Esegui questo comando nel terminale:

Shell

claude mcp add --transport http diaform https://diaform.io/api/mcp \
  --header "Authorization: Bearer $DIAFORM_API_KEY"

Poi esegui /mcp in Claude Code per controllare che diaform sia collegato.

Strumenti#

L’agente vede sei strumenti in sola lettura:

Strumento	Cosa fa	Argomenti
`list_projects`	Elenca tutti i progetti con ID, nome e stato	Nessuno
`get_project`	Restituisce un progetto con le sue domande e il numero di conversazioni	`project_id`
`list_conversations`	Elenca le conversazioni di un progetto con rispondente, sentiment e riepilogo IA	`project_id`, e facoltativamente `status`, `sentiment`, `created_after`, `created_before`, `search`, `limit`, `cursor`
`get_conversation`	Restituisce una conversazione con il suo riepilogo e la trascrizione completa	`conversation_id`
`list_reports`	Elenca i report IA di un progetto	`project_id`, e facoltativamente `status`, `limit`, `cursor`
`get_report`	Restituisce un report IA con temi, problemi, casi isolati e citazioni	`report_id`

Ogni strumento restituisce lo stesso JSON del suo endpoint REST. I campi sono descritti in Progetti, Conversazioni e Report. status e sentiment sono array, ad esempio ["completed"].

Gli elenchi restituiscono fino a 100 elementi alla volta. Quando un risultato ha has_more: true, l’agente passa next_cursor come cursor per ottenere la pagina successiva.

Cosa puoi chiedere#

“Elenca i miei progetti Diaform e dimmi quale ha ricevuto più risposte.”
“Leggi le conversazioni completate degli ultimi 30 giorni nel progetto di onboarding e raggruppa le lamentele per tema.”
“Trova le conversazioni che parlano dei prezzi e cita quello che hanno detto le persone.”
“Riassumi l’ultimo report IA e scrivi un aggiornamento su Slack per il team di prodotto.”
“Recupera la trascrizione completa della conversazione più negativa di questa settimana.”

Errori e limiti#

Una chiave mancante o revocata, o un piano senza accesso all’API, fa fallire la connessione con un codice HTTP 401 o 403. Di solito il tuo client lo mostra come un server in errore o non autorizzato.

Quando la chiamata a uno strumento fallisce, ad esempio per un ID sbagliato, l’agente riceve gli stessi error e code dell’API REST e può correggersi. Vedi Errori.

Le richieste MCP contano nello stesso limite dell’API REST: 120 richieste al minuto per ogni chiave.

Dettagli tecnici#

Per creare un tuo client:

Invia messaggi JSON-RPC 2.0 con POST https://diaform.io/api/mcp. Il server risponde a ogni richiesta con una sola risposta JSON, non con un flusso di eventi.
Il server è stateless. Non emette ID di sessione, e GET e DELETE restituiscono 405.
Le versioni del protocollo supportate sono 2025-06-18, 2025-03-26 e 2024-11-05.
Implementa initialize, ping, tools/list e tools/call. Non ha risorse né prompt.

Shell

curl -X POST "https://diaform.io/api/mcp" \
  -H "Authorization: Bearer $DIAFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_conversations",
      "arguments": {
        "project_id": "b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d",
        "status": ["completed"],
        "limit": 10
      }
    }
  }'