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 e applica 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. Questo copre anche la creazione di un modello e l'avvio di un benchmark (vedi Cosa si propone). - 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.
I segreti di una configurazione (segreto HMAC, token, password) non gli arrivano mai: models.inspect_pipeline e le proposte li restituiscono mascherati. Una proposta che rinvia una configurazione così come l'ha letta conserva il segreto salvato, senza che l'IA l'abbia visto.
I tool esposti
I tool sono raggruppati per famiglia. Il client li scopre da sé al momento della connessione; quelli di un connettore compaiono solo se la tua organizzazione lo utilizza.
| Famiglia | Tool | Ruolo |
|---|---|---|
models | list_models, lookup_model, list_groups, inspect_pipeline, list_contexts, get_pipeline_trace, get_exchange_metadata, automation_health, get_entry_endpoints | Inventario dei modelli, lettura di una pipeline e delle sue esecuzioni, stato delle automazioni bloccate |
pipeline | list_node_kinds, lookup_node_contract, lookup_module, list_all_tools, list_config_options, list_schemas, validate | Contratti dei nodi, opzioni di configurazione, validazione di un grafo prima della proposta |
agents | list_roles, lookup_role, list_missions, lookup_mission | Ruoli e missioni dei tuoi agenti |
benchmarks | list, get, list_check_kinds, list_runs, get_run, run_status | Scenari di valutazione e risultati dei loro run |
knowledge | search | Ricerca nella tua base di conoscenza |
database_query / database_manage | lettura; create_row, update_row, claim_row | I tuoi database no-code (scrittura: scope Completo) |
conversation | open, send, poll, history | Parlare con un modello (vedi sotto) |
proposals | create, describe_kind, apply, reject | Proporre una modifica, leggerne il contratto, risolverla (apply / reject: scope Completo) |
L'URL di ingresso di un modello, pronto da incollare. models.get_entry_endpoints restituisce l'URL pubblico completo di ciascun ricevitore dichiarato sullo Start di un modello (webhook in entrata, callback di una piattaforma di messaggistica…) — così puoi trasmetterlo a un partner senza cercare il percorso nell'interfaccia.
Cosa si propone
Ogni modifica di configurazione passa da proposals.create(kind, payload). Prima di scrivere un payload, il client legge il suo contratto esatto con proposals.describe_kind(kind). I kind disponibili:
| Kind | Effetto una volta accettato |
|---|---|
model_create | Crea un modello (processo) — la sua etichetta, la sua descrizione, il suo gruppo |
model_update | Modifica i metadati di un modello esistente |
pipeline_edit | Modifica il grafo di un modello (aggiunta, modifica, eliminazione di nodi e collegamenti) |
pipeline_publish | Pubblica lo stato corrente di un modello, dopo la validazione pre-pubblicazione |
pipeline_plan | Concatena delle modifiche poi una pubblicazione sullo stesso modello, con una sola accettazione, in modo atomico |
role_update / mission_update | Crea o modifica un ruolo / una missione di agente |
knowledge_update | Crea o aggiorna una scheda di testo della base di conoscenza |
knowledge_document_replace | Sostituisce il file di un documento della base di conoscenza, sul posto: stesso identificativo, stesso link pubblico |
database_schema_edit | Modifica la struttura di un database no-code (database, colonne) |
benchmark_create / benchmark_update / benchmark_delete | Gestisce gli scenari di valutazione |
benchmark_run | Avvia un run di benchmark — proposto, perché un run consuma crediti |
credit_topup | Accredito manuale di un saldo — riservato all'organizzazione che gestisce la piattaforma, e validato dall'organizzazione accreditata |
Creare un processo da capo a fine = più consensi. model_create crea l'istanza; un pipeline_edit collega poi il suo Start (con i suoi ricevitori) e i suoi nodi; un pipeline_publish lo mette in servizio. Creare un'istanza e collegarla restano due decisioni umane distinte.
Creare una chiave MCP
Riservato agli amministratori dell'organizzazione: una chiave porta autorità su tutta l'organizzazione.
- In betool, apri Impostazioni dell'organizzazione → MCP.
- 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.
- 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 dell'organizzazione → MCP → Journal delle chiamate ai tool (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:
- Nell'applicazione, aggiungi il server MCP
https://platform.betool.ai/mcp. - 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.
- 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 dell'organizzazione → 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 dell'organizzazione → MCP (sezione Journal delle chiamate ai tool), rigorosamente circoscritto alla tua organizzazione.
Vedi anche
- API Admin — automatizza betool dai tuoi sistemi.
- Sicurezza e conformità — il modello di governance delle proposte.