Bubble MCP + Claude Code: How to Build, Extend and Debug Bubble Apps with an AI Agent

Our demo build in numbers (October 22, 2026):

• 12 minutes of agent time to go from an empty account to a working app with login, data, workflows and an API integration
• 117 Bubble tools available to the agent in one session
• $7.50 in Claude usage for the whole build; the Bubble MCP itself is free during the beta
• 0 issues in Bubble's issue checker at the end, plus 2 bugs that only a human review caught (both fixed by the agent)

The short answer

Connect Claude Code to Bubble with one command, sign in once in the browser, and then work in stages. Start every stage with a written brief and a short rules file. Begin with a read-only inspection, build in a branch (or a test app), review between stages, and keep keys, sign-ins and deployment in human hands.

claude mcp add --transport http --scope user bubble https://mcp.bubble.io/mcp

Then type /mcp in Claude Code, select bubble, choose Authenticate, and sign in to Bubble in the browser that opens.

The agent is genuinely useful for data models, privacy rules, workflows, backend workflows, API Connector setup and debugging from logs. It is weaker at visual judgement: it can make a layout that passes every check and still looks broken. It cannot deploy, cannot change live data, and cannot merge branches. Those limits are by design.

What the Bubble MCP is (and what it isn't)

MCP, the Model Context Protocol, is an open standard for letting AI agents call tools in other systems. Anthropic introduced it in 2024, and it is now supported by most coding agents. Bubble's MCP server (https://mcp.bubble.io/mcp) exposes the Bubble editor itself as tools. The agent acts as you, with your permissions, on the apps your account can open.

Three facts from Bubble's own pages shape everything else:

• It builds real Bubble apps. Whatever the agent creates is a normal app you can open, inspect and edit in the visual editor. It supports web apps and native mobile apps.
• It is a beta, and free while it lasts. It doesn't use Bubble AI credits, and Bubble adds no rate limits of its own during the beta. Your AI provider's limits and costs still apply.
• It works on development, not production. It writes to the development version and the test database, and it can only read the live database. It cannot deploy.

Official MCP vs community MCP servers vs the API Connector

Search for "Bubble MCP" and you'll find several different things. They solve different problems.

For most serious projects the answer is two of these together: the official MCP at build time, plus the API Connector (to Claude or to your own engine) at run time. We come back to that split in the client case.

Before you start

You need:

• A Bubble account. The MCP is available on every plan, but your plan still limits what the agent can do (see the table below).
• An MCP-capable agent. This guide uses Claude Code. Bubble also documents Codex, the Claude app (Connectors), ChatGPT, VS Code with GitHub Copilot, and Cursor.
• An app to work on. For a first run, create a throwaway app rather than pointing the agent at production.

Check what your plan allows. The agent inherits your plan's limits. On our Free-plan demo app, the agent's get_app_plan_context call reported:

Setup in Claude Code (5 minutes)

1. Add the server (available in all your projects):

claude mcp add --transport http --scope user bubble https://mcp.bubble.io/mcp

For a single project, add it to .mcp.json in the project root instead:

{
  "mcpServers": {
    "bubble": { "type": "http", "url": "https://mcp.bubble.io/mcp" }
  }
}

2. Sign in. Open Claude Code, type /mcp, select bubble, choose Authenticate and approve access in the browser. Check it worked:

claude mcp list

3. Run a harmless first call. Ask: "Using only the Bubble MCP tools, tell me which account is signed in and whether an app called my-test-app exists. Don't change anything."

You can review or revoke any connected agent later from your Bubble account settings.

What the agent can do: the tool map

In our session the agent had 117 Bubble tools. These are the categories that matter, with the tool names you'll see in logs:

Two tools deserve a special mention:

• read_guide. Bubble ships instructions written for agents, and Claude Code called it on its own before building. Encourage it in your brief.
• validate_expression. Most Bubble bugs are expression bugs (wrong type, wrong field). The agent validated expressions before writing them, and that is why the issue checker ended at zero.

The workflow that works: briefs, rules and stages

Telling an agent to "build me a CRM" gets you a CRM you don't understand. What worked for us, on client work and on the demo, was small stages with written briefs and one rules file that every stage starts with.

The rules file

This is the exact file we used. Adapt the first line to your app.

Hard rules for this session:
- Work ONLY on the Bubble app named nh-mcp-demo. Never read, list by name, open or change any other app in this account.
- Before the changes of this stage, create a savepoint named after the stage.
- Development version / test database only. Never deploy and never touch live data.
- No real personal data: sample data is fictional (example.com emails).
- If a tool fails or the plan doesn't allow something, don't work around it silently: stop that item, note the exact error, continue with the rest.
- At the end, reply with: what you built, every error or limitation you hit (exact wording), and the preview link.

The last two rules matter most. "Note the exact error" is how we collected every limitation in this guide. "Reply with what you built" turns each stage into a change log you can review.

One brief per stage

Each brief says what exists already, what to build, and in what order. Here is our Stage 1 brief, word for word:

Stage 1 of the demo. Read RULES.md first and follow it.
Goal: a "Client Request Tracker" app for a small agency.
1. Use read_guide if it helps. Check the name nh-mcp-demo is available, then create the app (web app).
2. Get the app outline and plan context, so you know what this plan allows.
3. Create a savepoint "stage-1-data-model".
4. Option sets: Request Status (New, In progress, Waiting on client, Done) with a text attribute "color"
   (#7B5CFF, #C6FF4A, #FFB547, #3DDC97); Priority (Low, Normal, High).
5. Data types: Client (name, email, website); Request (title, details, status, priority, client,
   due date, assigned to: User).
6. Privacy rule on Request: a user can see and search a Request only if they created it or it is
   assigned to them. Keep Client visible to logged-in users.
Do not build pages yet.

Three agents, three jobs

On real projects we split the work between three agents, each doing what it's best at:

And a fourth party, the human, keeps four jobs: confirming writes, pasting keys and secrets, signing in, and deploying.

Walkthrough: building a Bubble app in 12 minutes

We built the demo in four headless Claude Code runs (claude -p with the stage brief), logging every tool call. Here is what each stage did, what it cost and what went wrong.

(Stages 1–3 total 12 minutes and $7.50. The fix stage came after a visual review.)

Stage 1: data model and privacy

The agent read Bubble's guide, checked the app name, created the app, read the plan context, then built the option sets, data types and privacy rules. It finished with an issue check: zero issues.

The privacy rules came out exactly as specified. Bubble combines rules with "or", so a user can see a Request when either the "Creator" rule or the "Assignee" rule matches, and nobody else can. The agent also flagged something we hadn't asked about: the default User privacy rules would hide other users' names from an "assigned to" picker. It's a good example of an agent reading the model as a whole.

What went wrong:

• The savepoint was refused: App plan does not include version control.
• Every option set write came back with Undo unavailable for WriteOptionSet: not reversible right now, so mistakes in option sets must be deleted by hand.

Stage 2: design system, pages and workflows

The brief asked for color and font tokens applied through styles, a login page, a list page with a status filter, colored status chips, an overdue highlight, a "New request" popup and a detail page with status buttons. The agent:

• created 5 color tokens and an Inter font token, 12 styles, and restyled the defaults
• converted the index page to a column layout
• built the repeating group, filter and popup, and validated every data-source expression before writing it
• added a privacy rule letting logged-in users see each other's name field only, never email
• built the request page, with buttons that appear only when they make sense (for example, Start only when the status is New or Waiting on client)

What went wrong (and why it's fine): Bubble rejected two batches and rolled them back completely:

setNodeProperties: invalid expression for data_source: type_mismatch
"Group F: Data source should be empty but right now it is a Request"

createActionWithDefaults: invalid expression for data_to_send: type_mismatch
"Go to page ...: Data to send should be text but right now it is a Request"

The agent split the steps and redid both. Atomic, validated batches are one of the best things about Bubble's MCP: a half-applied change never lands in your app.

What it couldn't do: the starter theme's hover color and the 14 px phone font size on new text styles weren't reachable through the tools. Fix those in the editor's Styles tab.

Stage 3: sample data, backend workflow, API Connector, tests

This stage shows the MCP at its best.

• Sample data: one demo user, 3 clients and 8 requests (2 overdue, 1 done). That's 12 records out of the Free plan's 200.
• Scheduled backend workflow: flag_overdue takes a Request and sets overdue = yes when it's past due and not done. The "Create request" workflow now schedules it for the new request's due date + 1 day.
• API Connector: a "Public holidays" collection calling https://date.nager.at/api/v3/PublicHolidays/[year]/US, initialized with a real response. The request page warns when a due date falls on a US holiday. The agent noticed that Bubble parsed the date field as a date, not text, and adjusted the comparison to match.
• Testing: 5 test cases written into the app, and a query_logs check that showed no workflow errors.

What went wrong:

• Unrecognized field: Created By. The agent can't set the built-in creator on records, so the sample requests show the editor admin as creator.
• This tool is not yet available to sessions signed in with Bubble, for the user impersonation token. To see the app as the demo user, use Run as in the Data tab.

Stage 4: the bug no check caught

After stage 3, Bubble's issue checker reported zero issues. Then we opened the editor and saw this: the request list was only about a third of the page wide, and inside each card the title column was squeezed so narrow that "Request title" wrapped every four letters.

This is why a visual check belongs in the loop. We described the bug in plain words, as the browser agent would, and Claude Code fixed it in one pass, reporting each property it changed:

Then a second review, a second bug. Clicking through the preview as the demo user, only 4 of the 8 requests showed. The repeating group's "fixed number of rows" had never been saved, so Bubble fell back to its default (on, 4 rows), which the editor doesn't display. We described it, and the agent found and fixed it in 80 seconds ($0.75).

And a feature, filmed live. For the video at the top of this guide, we gave the agent one more brief while recording the app: "add stat cards that filter the list". It read the page, added an option set, a page state, four cards with live counts and the list constraints, and passed the issue checker in 7.5 minutes ($2.87, 43 Bubble MCP calls). To film without signing in, an earlier stage had added a read-only demo mode: fictional records flagged demo are visible to logged-out visitors, and nothing can be changed without logging in.

Recipes

Short, copyable prompts for the jobs where the MCP saves the most time. Prefix each with "Read RULES.md first and follow it."

Explain an existing app (read-only):

"Using only read tools, describe this app: pages, data types with fields, option sets, privacy rules, backend workflows, API Connector calls and installed plugins. Flag anything that looks unsafe (public data, missing privacy rules, admin-only API keys in front-end calls). Change nothing."

Data model + privacy:

"Create data type X with fields …. Add privacy rules so that … . Validate that no other type exposes X's fields. Report the final rules in plain words."

Connect an external API with the API Connector:

"Create an API collection Y (auth: private key in header, leave the key empty, I'll paste it). Add these calls from the attached OpenAPI file: …. Initialize each call with the sample response in the file. Use them as Data/Action as listed."

Give the agent a real sample response for each call. Bubble's API Connector sets a call's fields from its initialization response, so real samples mean no manual field mapping.

Backend workflow + scheduling:

"Create a backend workflow Z with parameter …, which …. Schedule it from workflow W at …. If the plan blocks this, report the exact error."

Debug a failing workflow:

"Query the server logs for the last 2 hours for workflow errors. For each one: which workflow and action, the error message, the likely cause in our expressions, and a proposed fix. Don't apply fixes until I confirm."

Test cases:

"Write test cases for these flows: …. Include setup data, steps and expected result."

Case study: wiring a Bubble app to an AI engine

(A client project, anonymised: we describe the process, not the client.)

The situation: an established Bubble app needed a heavy AI feature: analysing documents and monitoring outside sources every day, with every finding backed by quoted evidence. That kind of work doesn't belong in Bubble workflows. It needs long-running jobs, caching, retries and evaluation.

The architecture: a separate AI engine (our code, our server) does the heavy work behind a documented API. Bubble stays the product the user sees:

• Bubble → engine: the API Connector calls the engine server-to-server with a private key per organisation.
• Engine → Bubble: the engine reports results back through Bubble backend workflows.
• Ownership: Bubble owns users, teams, documents and screens. The engine owns analysis, monitoring and scores.

How the MCP changed the build:

1. Inspect first. Before writing any integration code, the planning agent read the app through the MCP (read-only): data types, statuses, versions and file storage. The mapping, one engine organisation per Bubble team and Bubble's metadata winning over values read from documents, came from that inspection, not from guesswork.
2. A branch for everything. The agent created a dedicated integration branch. Option sets and fields were created there, and the live version was never touched.
3. API Connector from the API spec. Claude Code exported the engine's OpenAPI schema and a compact spec with real sample responses. The Bubble side was then configured from that file, with no hand-typed field names.
4. Humans on the sensitive steps. Each write needed a confirmation, and API keys were pasted by a person.
5. Debugging from logs. A backend workflow failed with HTTP 422 … JSON decode error. The agent queried Bubble's server logs through the MCP and found the cause: a yes/no field was converted to text with the wrong field names, so an unquoted no landed in the JSON body. One fix, and the sync ran.

Lessons we'd pass on:

• Files need a plan. By default, files uploaded to Bubble's storage are public to anyone with the URL. Private files need an admin API key, and that key opens all of the app's data. Decide early whether the engine downloads files with a key or Bubble sends the bytes in the API call.
• One agent should see both ends. The engine and the Bubble side were built by the same Claude Code session, which could test the full round trip itself.
• Use custom code where it pays off. Building the heavy AI part inside Bubble would have needed specialist Bubble developers plus workarounds. As a standalone engine, one senior engineer with Claude Code built it end to end, and Bubble kept doing what it does best.

Limits and gotchas (exact errors)

What it costs

• Bubble MCP: free during the beta, and it doesn't use Bubble AI credits.
• Your AI usage: our four-stage demo used about $8.70 of Claude usage ($7.50 for stages 1–3, $1.20 for the fix). The interface stage was the most expensive, because building pages needs many reads of element properties before each write.
• Your Bubble plan: it decides what the agent can use (branches, savepoints, Data API, record limits). For client work, budget for a plan with branches and savepoints. They are your undo button.

When to use the Bubble MCP, and when to write code

Use the Bubble MCP when:

• you maintain a Bubble app and want it explained, documented or extended faster
• you're wiring Bubble to external services (API Connector and backend workflows are where it saves the most clicks)
• you're hunting a workflow bug and need someone to read the logs
• you want a first version of a feature to refine in the editor

Write code (and connect it to Bubble) when:

• the work is long-running, multi-step or needs evaluation, as AI pipelines do
• you need fine control over performance, testing and hosting
• the logic would need many workarounds inside Bubble workflows

The two aren't rivals. Our best results came from using both: Bubble for the product surface, an engine in code for heavy lifting, and one AI agent building across both.

Work with us

NerdHeadz builds products on Bubble and in custom code, and increasingly both together. If you want an AI feature in an existing Bubble app, help splitting heavy AI work into its own engine, or a team that already works this way with the Bubble MCP, talk to us.

Frequently asked questions