Agent AI (MCP)

Bobuild espone un server Model Context Protocol (MCP) sul Builder così l'agent AI che già esegui sulla tua macchina può ispezionare e modificare la configurazione dell'app — oggetti, pagine, widget, task, endpoint API, template documenti — con le stesse regole del Builder visuale. Opzionalmente, un grant può anche eseguire SQL sui record del tenant (lo stesso schema logico della SQL Console).

Scenari tipici:

• impostare un nuovo portale (oggetti, pagine, form, griglie) da un brief in linguaggio naturale;
• aggiornare in blocco etichette, filtri o display rule su molti widget;
• eseguire un passaggio diagnose sull'intera app dopo modifiche manuali e correggere riferimenti rotti;
• popolare o riparare dati record durante una migrazione (quando il token include data write);
• tenere un'app di sviluppo allineata a una specifica mentre rivedi le differenze nel Builder, poi deploy in produzione.

:::

Il tuo agent, la tua macchina

Non passi a un chatbot Bobuild. Il tuo agent locale o desktop si collega a Bobuild come server MCP remoto via HTTPS. Resti tu a controllare modello e conversazione; Bobuild fornisce tool tipizzati, validazione e audit log.

Client MCP compatibili

Qualsiasi client che parla MCP su Streamable HTTP (POST JSON-RPC) può connettersi. Bobuild è testato con:

Client	Note
Claude	App desktop e Claude Code
Cursor	Agent IDE
Codex	OpenAI Codex (MCP remoto; vedi anche Codex stdio sotto)
GitHub Copilot	Modalità agent VS Code
Windsurf	Cascade
ChatGPT	Connettori personalizzati (developer mode)
Zed	Agent editor
Cline	Estensione VS Code

I client con OAuth (ad esempio Claude Desktop e i connettori ChatGPT) possono accedere senza incollare un token di autenticazione. Gli agent IDE di solito accettano un personal access token come Authorization: Bearer …, oppure supportano il flusso OAuth.

Abilitare l'accesso e connettersi

1. Apri le pagine agent del Builder

Accedi al Builder ed entra nella sezione "AI".

2. Crea un grant

In Agent tokens, oppure:

• OAuth — lascia che il client MCP apra la schermata di consenso Bobuild, scegli app e permessi; il grant compare come token OAuth che puoi modificare o revocare, oppure
• Personal access token — clicca New token, imposta descrizione e scadenza, e per ogni app scegli Structure e Data in modo indipendente:

Permesso	Nessuno	Read	Read and write
Structure	—	Ispeziona la configurazione (blueprint, search, affordances)	Modifica la configurazione (changeset, patch, desired state)
Data	—	SELECT via tool SQL	INSERT / UPDATE / DELETE via tool SQL

Concedi almeno un'app con qualche accesso. Structure write richiede structure read su quell'app; data write richiede data read. Un token non può raggiungere un'app che tu non puoi aprire.

Copia il segreto quando viene mostrato — non viene memorizzato e non può essere mostrato di nuovo.

3. Punta il client all'URL MCP

L'endpoint MCP è:

https://builder.bobuild.com/api/v1/agent/mcp

L'autenticazione è sempre un token Bearer (grant OAuth e token personali si presentano entrambi come Bearer al server).

Verifica un token personale (opzionale):

curl -sS -H "Authorization: Bearer YOUR_TOKEN" \
  "https://builder.bobuild.com/api/v1/agent/whoami"

Il JSON elenca identità, grant del token e app accessibili.

Esempio: Claude Desktop (OAuth)

1. Aggiungi un connettore personalizzato (o voce server MCP, a seconda della versione Claude).
2. Imposta l'URL del server su https://builder.bobuild.com/api/v1/agent/mcp.
3. Completa OAuth quando richiesto; scegli app e permessi structure/data.
4. Gestisci i grant connessi in Agent tokens nel Builder.

Esempio: Cursor (mcp.json)

Molte configurazioni usano un token mintato nel file MCP utente o di progetto:

{
  "mcpServers": {
    "bobuild": {
      "url": "https://builder.bobuild.com/api/v1/agent/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Se il client supporta OAuth discovery per questo URL, può preferire OAuth rispetto a un header Bearer configurato — segui il flusso di accesso del client quando offerto.

Esempio: cosa chiedere all'agent

Dopo che il client elenca i tool Bobuild, inizia con identità e survey in sola lettura:

1. "Chiama whoami e dimmi su quali app posso scrivere."
2. "Apri l'app APP_ID da whoami. Esegui get_blueprint con detail=index, poi descrivi l'albero pagine."
3. "Esegui diagnose su quell'app e riassumi gli errori."

Per una modifica strutturale (richiede structure write):

4. "Pianifica un portale clienti: oggetto Customer, griglia su una pagina staff, form su una pagina figlia. Usa plan_changes e mostrami il piano senza applicare finché non confermo."
5. Dopo la tua approvazione: "Applica con apply_desired_state (o apply_changeset), poi esegui di nuovo diagnose."

Per i record (richiede data read / write):

6. "Chiama get_sql_schema per questa app, poi SELECT da customers con paginazione — non aggiornare finché non confermo."

Gli agent sono istruiti a mostrare un piano compatto e attendere il tuo via libera prima di mutare la configurazione o eseguire SQL di scrittura.

Cosa possono fare gli agent

Area	Esempi
Modellare l'app	Creare oggetti e campi, pagine e widget, task, endpoint API, template documenti — via le stesse operazioni strutturali del Builder
Configurare sul posto	Filtri, colonne, campi form, follow-up, display rule — solo valori che l'editor Builder offrirebbe (get_affordances, patch_config)
Copy e i18n	list_texts / set_texts per stringhe visibili all'utente
Controllo integrità	diagnose — risultati di configurazione sull'intera app con config_path per correzioni
Record (grant opzionale)	get_sql_schema, run_sql_query — nomi logici, SELECT paginato; SQL mutante solo con data write e la tua conferma

Le scritture che il Builder rifiuterebbe sono rifiutate anche qui. I tipi di campo non possono cambiare dopo la creazione; preferisci aggiungere e migrare. I campi password sono write-only in SQL (hash in insert/update, non leggibili).

Catalogo tool

tools/list nomina sempre ogni tool; grant mancanti restituiscono un rifiuto alla chiamata. Chiama whoami per primo — gli altri tool richiedono un app_id dalla risposta.

Tool	Grant	Ruolo
whoami	—	Identità, grant, app accessibili
list_field_types	—	Tipi campo per field.add
list_operations	—	Schema per op strutturali (field.add, page.create, …)
get_blueprint	Structure read	Configurazione completa o scoped
search_config	Structure read	Cerca config memorizzata senza caricare tutta l'app
list_texts	Structure read	Stringhe visibili su un albero pagine
describe_object / describe_page	Structure read	Un oggetto o pagina in dettaglio
get_affordances	Structure read	Impostazioni valide a un config_path (prima delle scritture)
list_fieldrefs	Structure read	Riferimenti campo da un oggetto
diagnose	Structure read	Report salute configurazione
plan_changes	Structure read	Compila layout desiderato senza applicare
apply_desired_state	Structure write	Applica uno stato desiderato compilato
apply_changeset	Structure write	Batch di operazioni e patch in modo atomico
patch_config	Structure write	Modifica su una singola posizione
set_texts	Structure write	Aggiornamenti bulk di stringhe
get_sql_schema	Data read	Schema SQL logico
run_sql_query	Data read/write	SQL sui record (50 righe per pagina per SELECT)

Non esistono tool MCP standalone chiamati field.add o page.create — usa list_operations e apply_changeset (o apply_desired_state per un nuovo layout pagina/oggetto).

Loop tipico read → write:

1. whoami → scegli app_id
2. get_blueprint / search_config / get_affordances
3. Piano (approvazione umana)
4. apply_changeset, apply_desired_state, o patch_config
5. get_blueprint scoped + diagnose

Sicurezza e operazioni

• Preferisci app di staging / sviluppo; usa i Deployment per promuovere la configurazione.
• Revoca i token in Agent tokens quando un laptop o client viene dismesso.
• Le richieste e scritture degli agent sono auditate (log Builder e voci audit per patch, changeset e SQL con source: mcp).
• Vedi Panoramica sicurezza — i grant agent sono sensibili quanto l'accesso Builder per le app elencate.

Correlati

• REST API — endpoint app live per integrazioni (non configurazione Builder)
• SQL Console — SQL interattivo per builder (stessi nomi logici dei tool SQL agent)
• Deployment — portare in produzione configurazione testata