Collegare un assistente IA a Helpdash con MCP

Helpdash espone un server Model Context Protocol (MCP), così un assistente IA può lavorare dentro il tuo spazio di lavoro invece che tu copi e incolli ticket in una finestra di chat. Chiedi "quali ticket violano lo SLA oggi?" oppure "riassumi questo scambio per il passaggio di consegne" e l'assistente interroga Helpdash stesso.

Questo articolo copre che cosa espone il connettore, come collegarne uno e — la parte che merita due letture — che cosa non gli è permesso fare.

Che cosa espone il connettore

Il server include 46 strumenti, quattro istruzioni già pronte e una risorsa che elenca tutti i valori di enumerazione accettati dagli strumenti. Gli strumenti coprono ticket, chat dal vivo, base di conoscenza, risposte predefinite, progetti e colleghi, cruscotto, CSAT, regole di automazione, webhook, impostazioni, registro attività e fatturazione.

Letture e scritture sono sempre strumenti separati. Non esiste uno strumento tuttofare api_request con un parametro method: cercare ticket e modificarne uno sono strumenti diversi con permessi diversi, quindi un assistente con accesso in lettura non può alterare nulla cambiando un argomento.

Le quattro istruzioni sono flussi che vale la pena avere già scritti:

• Smistare un ticket: consiglia priorità, categoria e responsabile. Non cambia nulla.
• Preparare una risposta al cliente: stende il testo usando la tua base di conoscenza e le risposte predefinite. Non può inviare; la risposta torna a te per la revisione.
• Riassumere uno scambio: condensa un ticket lungo o una trascrizione di chat per il turno successivo.
• Report settimanale di assistenza: volume, SLA, CSAT e ciò che richiede attenzione.

Collegare un client

Apri Impostazioni → Connettori IA (MCP) ed emetti un token. Dagli un'etichetta che riconoscerai in seguito, per il primo lascia spenti tutti gli interruttori di scrittura e copia la chiave: viene mostrata esattamente una volta.

Poi registralo. Per Claude Code:

claude mcp add --transport http helpdash https://your-workspace.helpdash.io/mcp \
  --header "Authorization: Bearer hd_mcp_..."

Per qualsiasi client che legge un .mcp.json:

{
  "mcpServers": {
    "helpdash": {
      "type": "http",
      "url": "https://your-workspace.helpdash.io/mcp",
      "headers": { "Authorization": "Bearer hd_mcp_..." }
    }
  }
}

Entrambi i frammenti vengono generati per te, già compilati con l'indirizzo del tuo spazio di lavoro, nella stessa schermata in cui compare il token.

I client che preferiscono l'accesso dal browser possono usare OAuth 2.1 invece di un token statico: il server pubblica i documenti di scoperta standard, supporta PKCE e la registrazione dinamica dei client e mostra una schermata di consenso che elenca esattamente gli ambiti richiesti. Nessun token da copiare e nessuna chiave da conservare su disco.

Che cosa non può fare

Il connettore non è una seconda API più permissiva. Ogni chiamata passa dagli stessi quattro controlli di una richiesta umana.

Agisce come te. Un token è legato all'operatore che lo ha emesso. Eredita esattamente i suoi ruoli e permessi: se tu non puoi aprire un ticket nell'applicazione, non può farlo nemmeno un assistente che porta il tuo token. Ed è legato a un solo spazio di lavoro: non esiste argomento che raggiunga i dati di un altro tenant.

Sola lettura, se non dici altro. Un token nuovo con tutti gli interruttori spenti può cercare, leggere e produrre report, niente di più. L'accesso in scrittura si concede per area — modificare ticket, rispondere in chat dal vivo, modificare la base di conoscenza, gestire progetti, invitare colleghi, cambiare impostazioni, cambiare regole di automazione — e solo per quelle che spunti. La lettura è sempre inclusa, perché un assistente che può scrivere ma non leggere è inutile.

Gli strumenti di scrittura chiedono prima. Ogni strumento che modifica dati è contrassegnato come distruttivo, così un client fatto bene ti chiede conferma prima di ogni chiamata invece di agire in silenzio. Gli strumenti che raggiungono un cliente lo dicono nella loro descrizione: un messaggio di chat dal vivo viene consegnato all'istante e non può essere richiamato, e un commento a un ticket è per impostazione predefinita una nota interna, così nulla arriva al cliente per sbaglio.

I segreti restano sul server. Leggere le tue impostazioni tramite un connettore restituisce le credenziali di integrazione mascherate. Non esiste argomento che le smascheri.

Il testo dei clienti è recintato. Descrizioni dei ticket, commenti e trascrizioni di chat sono scritti da altre persone, e una casella di assistenza è proprio il posto in cui qualcuno proverebbe a piantare istruzioni per un'IA che le legga. Helpdash racchiude quel testo in un blocco esplicito di contenuto non attendibile e dice al modello, nelle istruzioni del server stesso, che nulla al suo interno è un comando.

Tutto viene registrato. Ogni chiamata è registrata con operatore, strumento ed esito, nello stesso registro di controllo del resto dello spazio di lavoro. Se un giorno devi rispondere a "che cosa ha fatto davvero l'assistente martedì?", la traccia c'è.

La revoca è immediata. Eliminare un token nelle Impostazioni ferma già la richiesta successiva dell'assistente. Conserviamo solo un hash SHA-256 della chiave, quindi non possiamo recuperarla per te: se la perdi, ne emetti una nuova.

Restringere ancora un token

Vale la pena conoscere due controlli facoltativi. Un token può avere una data di scadenza, il modo più semplice perché un esperimento breve si ripulisca da solo. E può avere un elenco di IP consentiti, così un token pensato per un server non può essere usato altrove. Entrambi stanno nello stesso modulo di creazione.

Un primo token ragionevole

Emettine uno senza ambiti di scrittura e concedi all'assistente una settimana di sola lettura. Chiedigli di individuare i rischi di SLA, riassumere gli scambi più affollati e preparare risposte che invii tu. Copre quasi tutto il valore senza alcuna esposizione. Quando saprai quale ambito di scrittura vuoi davvero, emetti un secondo token solo con quello: ampliare un token esistente è deliberatamente impossibile.

Ogni affermazione qui sopra descrive un comportamento disponibile oggi; il connettore è disponibile in ogni spazio di lavoro Helpdash.