> For the complete documentation index, see [llms.txt](https://docs.flowcp.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowcp.ai/how-to/connect-a-bubble-app.md).

# 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](#step-5-set-up-bubble-oauth).

> **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](/guides/connect-your-api.md#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](/guides/connect-your-api.md#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](/guides/review-and-customize-tools.md).

## 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](/guides/configure-oauth.md).

> **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](/guides/publish-your-mcp-server.md).

## Step 7 — Use the MCP server

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

```json
{
  "mcpServers": {
    "my-app": {
      "url": "https://runtime.flowcp.io/mcp/<server-id>",
      "type": "http"
    }
  }
}
```

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](/guides/chat-test-your-mcp-server.md) and [Integrate with AI clients](/guides/integrate-with-ai-clients.md).

## 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](/support/troubleshooting.md).
* Add or remove Bubble versions (branches) under **Settings → Branches** — see [Managing branches](/guides/manage-branches.md).
* Watch every tool call on the server's **Logs** tab — see [Execution logs](/reference/execution-logs.md).