Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Connect a Bubble app

This how-to walks you all the way from your Bubble app's API settings to a live MCP server that AI clients can call — with every tool running in each end-user's own Bubble OAuth context.

By the end you'll have:

  • A verified Bubble app connected to FlowCP.

  • Its endpoints imported as MCP tools, with the ones you want enabled.

  • Bubble OAuth configured so users authenticate as themselves.

  • A deployed MCP server and the config snippet to use it from Claude, Cursor, or ChatGPT.

Each step below is a summary with a link to the full reference guide if you need more detail.

Before you begin. You need a Bubble app you own and access to its Settings → API page. Everything on the FlowCP side happens in the dashboard — no code required.

Step 1 — Prepare your Bubble app's API settings

FlowCP imports your tools from Bubble's Swagger schema and authenticates users through Bubble's OAuth, so both must be turned on in Bubble first. In the Bubble editor, open Settings → API and:

  1. Enable Enable the Bubble API.

  2. Uncheck Hide Swagger Schema — if it's checked, FlowCP can't read your endpoint list.

  3. Make sure the endpoints you want to expose are Public or accessible to authenticated users.

  4. Enable 3rd Party OAuth / SAML Access, then note the Client ID and generate a Client Secret. You'll paste these into FlowCP in Step 5.

Tip: FlowCP derives Bubble's authorize and token URLs automatically from your app, so you never enter them by hand.

Step 2 — Connect the app in FlowCP

In the FlowCP dashboard, click Connect App in the sidebar (or navigate to /connect) and keep the Bubble provider tab selected (it's the default). On the App details step, fill in:

Field
What to enter

Display name

A label for this app inside FlowCP (e.g. "My SaaS").

Bubble App ID

The subdomain of your Bubble app. If your app is at myapp.bubbleapps.io, enter myapp.

Click Continue to verification. FlowCP reads your app's Bubble metadata (/api/1.1/meta) to detect a custom Live domain if you have one.

For the full field reference, see Connecting a Bubble app.

Step 3 — Verify ownership

Bubble apps require a one-time ownership check before import. On the Verify ownership step, pick a method:

  • Bubble Page — copy the verification token, create a new page in the Bubble editor whose URL slug is exactly that token (the page content doesn't matter), and publish it.

  • Meta Tag — paste the provided <meta name="flowcp-verification" …> tag into Bubble's Settings → SEO / metatags header section and publish.

If your app uses Bubble run-mode protection, enter the optional Username and Password so FlowCP can reach the protected URLs. Then click Check Verification. FlowCP probes both your live and version-test versions; on success you'll see a green App verified card and advance to import.

You can finish or redo this later under Settings → Verify (/apps/<app-id>/settings/verify). See Verifying Bubble app ownership.

Step 4 — Import and enable tools

After verification, FlowCP imports whichever of Bubble's two default branches are reachable, each as its own MCP server:

  • Live → your live Swagger endpoint (custom domain if detected, otherwise https://<app-id>.bubbleapps.io/api/1.1/meta/swagger.json).

  • Main → the development version at https://<app-id>.bubbleapps.io/version-test/api/1.1/meta/swagger.json.

The import checklist settles the Tools and Resources rows with the count imported, then redirects you to the Tools page.

Every tool starts disabled — FlowCP never exposes a tool until you turn it on. On the Tools page:

  1. Toggle the switch on each tool row you want AI clients to call. Changes take effect immediately — no re-deploy needed for enable/disable.

  2. Optionally rename a tool or edit its description to give the AI clearer context.

  3. Check each tool's risk level badge (read, write, destructive). Any enabled destructive tool must have Require confirmation turned on before you can deploy. For Bubble, leave the Required OAuth scope field blank — Bubble's tokens carry no scopes.

For more, see Review and customize tools.

Step 5 — Set up Bubble OAuth

Now connect the Bubble OAuth app you created in Step 1 so every MCP call runs in the end-user's own authorization context.

  1. In the sidebar, open MCP Auth.

  2. Click Add config and choose User OAuth as the auth type.

  3. Enter a Name (e.g. "Production"). For a Bubble app the provider is fixed to Bubble, so there's no provider selector and no authorize/token URLs to enter.

  4. Enter the Client ID and Client Secret from Bubble's Settings → API → 3rd Party OAuth / SAML Access.

  5. Copy the read-only OAuth redirect URI (https://api.flowcp.io/oauth/callback) and paste it into your Bubble OAuth app's allowed redirect URLs.

  6. Click Create config.

The first config you add is assigned to any branch that doesn't have one yet. To point each branch at a specific config, open Settings → Branches and pick the config in that branch's OAuth config dropdown. A branch left on None — not configured fails closed and won't authenticate.

For the complete OAuth reference, see Configure MCP Auth.

Note: If your Bubble app uses a custom Live domain, FlowCP sends users to Bubble OAuth on that domain for the Live server automatically. The redirect URI you register with Bubble doesn't change.

Step 6 — Deploy your server

Each branch (Live and Main) is a separate MCP server you deploy independently. Open the server's Deploy page (or use the Deploy button in the dashboard header with the branch selected).

Deploying requires all of:

  1. At least one tool enabled.

  2. OAuth configured — a config with a Client ID and Secret assigned to the branch.

  3. No unguarded destructive tools — every enabled destructive tool has Require confirmation on.

If anything is missing, the Deploy to Production button is blocked and lists what to fix. When ready, click Deploy to Production. The status changes from Development to Production and the runtime begins accepting connections at https://runtime.flowcp.io/mcp/<server-id>.

You can test before deploying using the always-available Development URL (/mcp/dev/<dev-slug>), reachable only by workspace members. For the full walkthrough, see Deploy your MCP server.

Step 7 — Use the MCP server

Once deployed, the Production URL panel shows a copyable config snippet with a tab for each AI client:

Paste the snippet for your client (Claude Desktop, Cursor, or ChatGPT) into its MCP configuration and restart it. The first time an AI client calls a tool, FlowCP returns an authorization challenge; the user logs in with Bubble, and every subsequent call runs with that user's token. When a token expires, the client re-authorizes automatically.

To try the server without leaving the dashboard, open the Playground to chat with a model that calls your tools for real. See Chat-test in the Playground and Integrate with AI clients.

Troubleshooting and next steps

  • Import can't reach Swagger? Recheck Enable the Bubble API and Hide Swagger Schema in Bubble (Step 1), then retry. See Troubleshooting.

  • Add or remove Bubble versions (branches) under Settings → Branches — see Managing branches.

  • Watch every tool call on the server's Logs tab — see Execution logs.

PreviousCore concepts
NextConnect your API

Last updated