AI agents (MCP)

Bobuild exposes a Model Context Protocol (MCP) server on the Builder so the AI agent you already run on your machine can inspect and change app configuration — objects, pages, widgets, tasks, API endpoints, document templates — with the same rules as the visual Builder. Optionally, a grant can also run SQL against tenant records (the same logical schema as the SQL Console).

Typical scenarios:

scaffold a new portal (objects, pages, forms, grids) from a natural-language brief;
bulk-update labels, filters, or display rules across many widgets;
run an app-wide diagnose pass after manual edits and fix broken references;
seed or repair record data during migration (when the token includes data write);
keep a development app in sync with a spec while you review diffs in the Builder, then deploy to production.

:::

Your agent, your machine

You do not switch to a Bobuild chatbot. Your local or desktop agent connects to Bobuild as a remote MCP server over HTTPS. You stay in control of the model and the conversation; Bobuild supplies typed tools, validation, and audit logging.

Compatible MCP clients

Any client that speaks MCP over Streamable HTTP (POST JSON-RPC) can connect. Bobuild is tested with:

Client	Notes
Claude	Desktop app and Claude Code
Cursor	IDE agent
Codex	OpenAI Codex (remote MCP; see also Codex stdio below)
GitHub Copilot	VS Code agent mode
Windsurf	Cascade
ChatGPT	Custom connectors (developer mode)
Zed	Editor agent
Cline	VS Code extension

OAuth-capable clients (for example Claude Desktop and ChatGPT custom connectors) can sign in without pasting a long secret. IDE agents usually accept a personal access token as Authorization: Bearer …, or complete the same OAuth flow when the client supports it.

Enable access and connect

1. Open the Builder agent pages

2. Create a grant

On Agent tokens, either:

OAuth — let the MCP client open Bobuild’s consent screen, pick apps, and choose permissions; the grant appears as an OAuth token you can edit or revoke later, or
Personal access token — click New token, set a description and expiry, and for each app choose Structure and Data independently:

Permission	None	Read	Read and write
Structure	—	Inspect configuration (blueprint, search, affordances)	Change configuration (changesets, patches, desired state)
Data	—	`SELECT` via SQL tools	`INSERT` / `UPDATE` / `DELETE` via SQL tools

Grant at least one app with some access. Structure write requires structure read on that app; data write requires data read. A token can never reach an app you cannot open yourself.

Copy the secret when shown — it is not stored and cannot be displayed again.

3. Point the client at the MCP URL

The MCP endpoint is:

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

Authentication is always a Bearer token (OAuth grants and personal tokens both present as Bearer to the server).

Verify a personal token (optional):

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

The JSON lists your identity, token grants, and accessible apps.

Example: Claude Desktop (OAuth)

Add a custom connector (or MCP server entry, depending on Claude version).
Set the server URL to https://builder.bobuild.com/api/v1/agent/mcp.
Complete OAuth when prompted; choose apps and structure/data permissions.
Manage connected grants on Agent tokens in the Builder.

Example: Cursor (`mcp.json`)

Many setups use a minted token in the user or project MCP config:

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

If the client supports OAuth discovery for this URL, it may prefer OAuth over a configured Bearer header — follow the client’s sign-in flow when offered.

Example: what to ask the agent

After the client lists Bobuild tools, start with identity and read-only survey:

“Call whoami and tell me which apps I can write.”
“Open app APP_ID from whoami. Run get_blueprint with detail=index, then describe the page tree.”
“Run diagnose on that app and summarize errors.”

For a structural change (requires structure write):

“Plan a customer portal: object Customer, grid on a staff page, form on a child page. Use plan_changes and show me the plan without applying until I confirm.”
After you approve: “Apply with apply_desired_state (or apply_changeset), then run diagnose again.”

For records (requires data read / write):

“Call get_sql_schema for this app, then SELECT from customers with paging — do not update until I confirm.”

Agents are instructed to show a compact plan and wait for your go-ahead before mutating configuration or running write SQL.

What agents can do

Area	Examples
Shape the app	Create objects and fields, pages and widgets, tasks, API endpoints, document templates — via the same structural operations the Builder uses
Configure in place	Filters, columns, form fields, follow-ups, display rules — only values the Builder editor would offer (`get_affordances`, `patch_config`)
Copy and i18n	`list_texts` / `set_texts` for user-visible strings
Health check	`diagnose` — app-wide configuration findings with `config_path` for follow-up fixes
Records (optional grant)	`get_sql_schema`, `run_sql_query` — logical names, paged `SELECT`; mutating SQL only with data write and your confirmation

Writes the Builder would refuse are refused here too. Field types cannot be changed after creation; prefer add-and-migrate. Password fields are write-only in SQL (hashed on insert/update, not readable).

Tool catalogue

tools/list always names every tool; missing grants return a refusal when the tool is called. Call whoami first — other tools need an app_id from its response.

Tool	Grant	Role
`whoami`	—	Identity, grants, accessible apps
`list_field_types`	—	Field types for `field.add`
`list_operations`	—	Schemas for structural ops (`field.add`, `page.create`, …)
`get_blueprint`	Structure read	Full or scoped configuration
`search_config`	Structure read	Search stored config without loading the whole app
`list_texts`	Structure read	User-visible strings on a page tree
`describe_object` / `describe_page`	Structure read	One object or page in detail
`get_affordances`	Structure read	Valid settings at a `config_path` (before writes)
`list_fieldrefs`	Structure read	Field references from an object
`diagnose`	Structure read	Configuration health report
`plan_changes`	Structure read	Compile desired layout without applying
`apply_desired_state`	Structure write	Apply a compiled desired state
`apply_changeset`	Structure write	Batch operations and patches atomically
`patch_config`	Structure write	Single-location tweak
`set_texts`	Structure write	Bulk string updates
`get_sql_schema`	Data read	Logical SQL schema
`run_sql_query`	Data read/write	SQL on records (50 rows per page for `SELECT`)

There are no standalone MCP tools named field.add or page.create — use list_operations and apply_changeset (or apply_desired_state for a new page/object layout).

Typical read → write loop:

whoami → pick app_id
get_blueprint / search_config / get_affordances
Plan (human approval)
apply_changeset, apply_desired_state, or patch_config
Scoped get_blueprint + diagnose

Safety and operations

Prefer staging / development apps; use Deployments to promote configuration.
Revoke tokens on Agent tokens when a laptop or client is retired.
Agent requests and writes are audited (Builder log and audit entries for patches, changesets, and SQL with source: mcp).
See Security overview — agent grants are as sensitive as Builder login for the apps they cover.

REST API — machine-facing live app endpoints (not Builder configuration)
SQL Console — interactive SQL for builders (same logical names as agent SQL tools)
Deployments — move tested configuration to production

Your agent, your machine​

Compatible MCP clients​

Enable access and connect​

1. Open the Builder agent pages​

2. Create a grant​

3. Point the client at the MCP URL​

Example: Claude Desktop (OAuth)​

Example: Cursor (mcp.json)​

Example: what to ask the agent​

What agents can do​

Tool catalogue​

Safety and operations​

Related​