betool betool

Documentazione

Pilotare betool da Claude (MCP)

Collega Claude, Claude Desktop o qualsiasi applicazione MCP a betool — con una chiave API o tramite OAuth 2.1 — per leggere la tua configurazione e proporre modifiche in linguaggio naturale, governate e con convalida umana.

Pilotare betool da Claude (server MCP)

betool espone un server MCP (Model Context Protocol): un client MCP esterno — Claude Code, Claude Desktop o qualsiasi applicazione compatibile — può leggere la configurazione della tua organizzazione e proporre modifiche in linguaggio naturale (creare/modificare una pipeline, un ruolo, una missione, una valutazione…). È come un assistente che configura betool insieme a te, in modo completamente governato.

Due modi per collegarsi, allo stesso endpoint https://platform.betool.ai/mcp:

  • una chiave API MCP nell'header Authorization — il più semplice per Claude Code;
  • OAuth 2.1 + PKCE — per le applicazioni di terze parti, senza gestire alcun segreto.

Nulla viene applicato senza un consenso esplicito. Ogni modifica passa attraverso una proposta. Con lo scope Lettura + proposte, la approvi con un pulsante Accetta all'interno di betool. Con lo scope Completo, l'applicazione può risolvere le proprie proposte dopo il tuo consenso nella sua stessa conversazione — l'equivalente macchina di quel pulsante, riservato a questo scope e tracciato come tutto il resto. Scegli Lettura + proposte se vuoi che la convalida avvenga in betool, e in nessun altro luogo.

Cosa può fare Claude

  • Leggere: inventario dei modelli, grafo e nodi di una pipeline, contratti di configurazione dei nodi, ruoli/missioni, tool disponibili, base di conoscenza.
  • Leggere i tuoi dati: i database no-code della tua organizzazione — database, tabelle, colonne e righe. Il client li scopre da sé; una chiave non può essere limitata a un sottoinsieme di database.
  • Proporre: tramite il tool proposals.create, una proposta di modifica in stato pending — la accetti o la rifiuti nell'interfaccia.
  • Scrivere dati (scope Completo): creare, aggiornare o prenotare una riga in uno dei tuoi database, dopo il tuo consenso esplicito nella conversazione. A differenza della configurazione, una scrittura di dati non è versionata — non si può ripristinare.
  • Parlare con i tuoi modelli (scope Completo): tenere una conversazione a più turni con un modello che hai esplicitamente aperto agli agenti esterni — vedi sotto.

Claude scopre il contratto esatto di ciascun nodo (campi, valori consentiti) prima di proporre: nessuna supposizione, nessuna configurazione non valida.

Creare una chiave MCP

Riservato agli amministratori dell'organizzazione: una chiave porta autorità su tutta l'organizzazione.

  1. In betool, apri Impostazioni → MCP.
  2. Assegna un nome alla chiave e scegline lo scope:
    • Sola lettura — legge la configurazione e i dati dei tuoi database, rilegge le conversazioni aperte da questo canale, non propone nulla;
    • Lettura + proposte (consigliato) — legge e invia proposte, che approvi in betool;
    • Completo — può anche risolvere le proprie proposte, scrivere nei tuoi database e conversare con i tuoi modelli, dopo il tuo consenso nella conversazione del client.
  3. La chiave in chiaro viene mostrata una sola volta — copiala immediatamente (non potrà mai più essere letta). Puoi revocare una chiave in qualsiasi momento.

Gli stessi tre scope esistono per OAuth; lì li scegli nella schermata di consenso.

Collegare Claude Code

Aggiungi il server MCP di betool a Claude Code (la chiave va nell'header Authorization):

claude mcp add betool \
  --transport http \
  --header "Authorization: Bearer <your-mcp-key>" \
  https://platform.betool.ai/mcp

Poi chiedi a Claude, in linguaggio naturale: "ispeziona la mia pipeline X e proponi un passo che riassuma il ticket prima dell'invio". Claude legge la configurazione, compone una proposta e tu la convalidi in betool.

Non incollare mai segreti in chiaro nella chat. La portata di Claude è delimitata dallo scope della chiave, e ogni chiamata di tool viene registrata in Impostazioni → MCP → log (RGPD art. 15).

Parlare con i tuoi modelli

Leggere e proporre serve a configurare betool. Una IA esterna può anche usarlo: tenere una vera conversazione con uno dei tuoi modelli, turno dopo turno, come farebbe qualsiasi visitatore sulla tua chat. Utile per far mettere alla prova un assistente da un'altra IA, per mettere betool dietro a un agente partner, o per far interrogare uno dei tuoi processi in linguaggio naturale da uno strumento interno.

Quattro tool: conversation.open apre o ritrova una conversazione, conversation.send invia un turno e restituisce la risposta, conversation.poll recupera una risposta che ha richiesto tempo, conversation.history rilegge lo storico. Quella conversazione è un contesto betool come gli altri: compare tra le tue conversazioni, il modello vede i turni precedenti e tu rileggi tutto nell'interfaccia.

Autorizza il modello, mai la chiave. Devi dichiarare il ricevitore Agente esterno sul nodo Start del modello: senza questa dichiarazione la chiamata viene rifiutata, anche con una chiave di scope Completo. I modelli creati da questa messa a disposizione lo dichiarano per impostazione predefinita (la strada normale è la strada facile); i più vecchi devono aggiungerlo, e a qualsiasi modello si può togliere. Decide dunque il modello, mai la chiave — e il ricevitore deve essere presente nella versione pubblicata, quella che gira. E poiché un turno può innescare effetti reali — una email che parte, una scheda creata —, consuma i crediti dell'organizzazione ed è tracciato come ogni chiamata di tool.

Una risposta non va mai perduta: se il modello lavora più a lungo dell'attesa concessa, la chiamata restituisce un ticket e il turno prosegue lato server — sopravvive anche a un rilascio. L'applicazione recupera poi la risposta con conversation.poll. Rinviare il messaggio non accelera nulla — e mentre il turno è in corso, l'invio viene rifiutato.

Infine, questo canale legge solo le proprie conversazioni. Un identificatore proveniente da un altro ingresso — chat pubblica, telefono, email — non è leggibile qui: gli scambi dei tuoi clienti non diventano consultabili solo perché un'applicazione MCP è collegata.

Un modello già esistente funziona senza modifiche. Questo canale pone le stesse chiavi di una chat: il messaggio arriva in user_message e l'evento è un normale on_message — quindi i tuoi filtri e le selezioni dei tuoi agenti continuano a funzionare. Se il modello di destinazione è stato scritto per un altro ingresso (legge telegram.text, un obiettivo, una variabile di pagina…), l'applicazione può fornire quelle chiavi tramite variables: entrano nel flusso dove le avrebbe messe l'altro ingresso. Ciò che non può falsificare è l'identità del turno — chi ha parlato e attraverso quale canale: quelle chiavi le pone il server, e ogni tentativo viene rifiutato e segnalato nella risposta.

Se il modello resta muto, guarda il suo routing. Un modello che serve più canali di solito ramifica sull'ingresso (filter input.entry_kind == chat_widget…): un turno che arriva con l'ingresso « agente esterno » non corrisponde ad alcun ramo e nulla risponde — senza che venga sollevato alcun errore. Passa as_entry_kind per essere instradato come quel canale. Cambia solo la chiave di routing: il descrittore di canale e il registro di audit continuano a dire che il turno viene da una IA esterna, e valgono le capacità reali del canale.

Una conversazione gestisce un turno alla volta. Finché il turno precedente non ha restituito la sua risposta, il successivo viene rifiutato indicando il turno da rileggere. Non è un limite arbitrario: una risposta è legata alla sua domanda dalla posizione nella conversazione, quindi due turni in volo renderebbero ambigua l'attribuzione — meglio un rifiuto chiaro che una risposta plausibile e falsa.

Collegare un'applicazione di terze parti (OAuth 2.1)

Una chiave nell'header va bene per Claude Code. Gli altri client — Claude Desktop, ChatGPT, un editor, la tua applicazione — si collegano tramite OAuth 2.1 + PKCE, senza che nessuno maneggi un segreto. Non c'è nulla da preparare: nessun client da dichiarare, nessun identificativo da chiederci.

Per l'utente il percorso sono tre schermate:

  1. Nell'applicazione, aggiungi il server MCP https://platform.betool.ai/mcp.
  2. Il browser apre una schermata di consenso di betool: indica l'applicazione che chiede l'accesso, l'organizzazione interessata e dove avverrà il ritorno. Verifica queste tre informazioni — soprattutto se appartieni a più organizzazioni.
  3. Scegli lo scope che concedi, poi Autorizza. L'applicazione non riceve mai più di quanto selezioni, anche se aveva chiesto di più.

Solo un amministratore dell'organizzazione può autorizzare un'applicazione. Collegarne una crea un'autorità durevole su tutta l'organizzazione — esattamente ciò che è una chiave MCP. Un membro con diritti limitati non può quindi aggirare le proprie restrizioni per questa via.

Per gli integratori la scoperta è del tutto automatica e conforme agli standard: una chiamata non autenticata a /mcp restituisce un 401 con l'header WWW-Authenticate e l'indirizzo dei nostri metadati (RFC 9728), che a loro volta indicano autorizzazione, scambio dei token, registrazione dinamica del client (RFC 7591) e revoca (RFC 7009). PKCE S256 è obbligatorio, i token di accesso durano un'ora e il token di refresh ruota a ogni utilizzo.

# Ciò che un client fa da solo — utile per verificare da terminale.
curl -i -X POST https://platform.betool.ai/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'
# -> 401 + WWW-Authenticate: Bearer ... resource_metadata="..."

curl -s https://platform.betool.ai/.well-known/oauth-authorization-server

Un token è valido solo per betool: riutilizzato altrove, viene rifiutato (RFC 8707). E se un token di refresh già consumato viene presentato una seconda volta — il segnale di un token rubato — tutta la sessione viene revocata e l'utente deve autorizzare di nuovo.

Applicazioni collegate: vedere e scollegare

In Impostazioni → MCP, la sezione Applicazioni collegate elenca ciò che è collegato alla tua organizzazione: nome dell'applicazione, scope concesso, chi l'ha autorizzata e la data dell'ultimo utilizzo. Un pulsante Scollega interrompe l'accesso immediatamente — tutti i token di quell'applicazione, solo per la tua organizzazione.

La stessa applicazione può essere collegata da più organizzazioni: scollegarla da te non riguarda nessun altro. Un'applicazione può anche scollegarsi da sé.

Scope e isolamento

  • Per impostazione predefinita una chiave opera solo sulla tua organizzazione — l'organizzazione di destinazione è forzata lato server; non passi mai un id di organizzazione come argomento.
  • Le chiavi vendor (organizzazione di backoffice) possono agire su un'altra organizzazione, con il consenso esplicito di quest'ultima e con audit completo — utile per uno scenario d'uso vendor multi-tenant.

Registro di audit

Ogni chiamata di tool (esterna via MCP e interna) scrive una riga di audit: chi, quale tool, quale canale, quale scope, esito, latenza. Disponibile in Impostazioni → MCP, rigorosamente circoscritto alla tua organizzazione.

Prossimamente

  • Controllo granulare, tool per tool, della superficie esposta via MCP.
  • Flusso server→client (SSE) per le notifiche del server.

Vedi anche