> ## Documentation Index
> Fetch the complete documentation index at: https://formbricks.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up Your MCP Client

> Connect Claude Code, the Claude apps, or Codex to the Formbricks MCP server over OAuth — plus how to manage and revoke access.

These guides connect your MCP client to Formbricks using OAuth (no API keys). They use the Formbricks Cloud URL `https://app.formbricks.com/api/mcp`; if you self-host, swap in your own `https://<your-formbricks-domain>/api/mcp`. For how the flow works and prerequisites, see [Connect AI agents (MCP)](https://formbricks.com/docs/platform/mcp/overview.md).

## Claude Code

Claude Code runs on your machine and performs the OAuth handshake itself.

**1. Add the server**

```bash theme={null}
claude mcp add --transport http formbricks https://app.formbricks.com/api/mcp
```

**2. Authenticate**

In a Claude Code session, run `/mcp`, select **formbricks**, and choose **Authenticate**. Your
browser opens to Formbricks; sign in if needed and **approve** the requested access on the consent
screen. Claude Code registers itself automatically and stores the token — there's no scope to type
in.

**3. Verify**

```bash theme={null}
claude mcp list
claude mcp get formbricks
```

Then ask Claude to use it, e.g. *"Use the formbricks MCP server to list my surveys."*

To share the server definition with a project (no credentials committed), add it to `.mcp.json` at the repo root and authenticate with `/mcp` on first use:

```json theme={null}
{
  "mcpServers": {
    "formbricks": {
      "type": "http",
      "url": "https://app.formbricks.com/api/mcp"
    }
  }
}
```

## Claude apps (custom connectors)

Use this for **claude.ai** and **Claude Desktop**, where Formbricks is added as a custom connector.

**1. Open the connectors settings**

Go to **Settings → Connectors** (**Customize → Connectors**) and click **Add custom connector**.

**2. Add the server URL**

Enter `https://app.formbricks.com/api/mcp` and confirm. Leave the optional OAuth client fields
blank — Formbricks registers the connector automatically.

**3. Approve access**

Claude opens Formbricks in your browser. Sign in and **approve** the requested access. The
connector then shows as connected, and you can enable it per chat from the **+** menu.

> [!WARNING]
>
> **Two things to know about the Claude apps:**
>
> * **Custom connectors depend on your Claude plan.** They're available on Free, Pro, Max, Team, and
>   Enterprise, but the Free plan is limited to a single connector. On **Team/Enterprise**, an
>   **organization owner** must add the connector under **Organization settings → Connectors** first;
>   members then connect to it individually.
> * **The connection runs from Anthropic's servers, not your machine.** A custom connector therefore
>   **cannot reach a `localhost` server** — the MCP URL must be a **public HTTPS** address. Formbricks
>   Cloud works out of the box; if you self-host, expose your instance on a public HTTPS domain (a
>   tunnel such as ngrok/cloudflared works for testing). To connect a local dev server, use **Claude
>   Code** instead — it runs locally.

## ChatGPT (MCP apps)

Use this to add Formbricks to **ChatGPT** as a custom MCP app. Custom MCP apps need ChatGPT
**developer mode**, which is available on Business and Enterprise/Edu plans and has to be enabled by
a workspace admin first — see OpenAI's
[Developer mode and MCP apps in ChatGPT](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt).

**1. Create the app**

In ChatGPT, go to **Settings → Apps → Create**. Enter the MCP URL
`https://app.formbricks.com/api/mcp` and choose **OAuth** as the authentication mechanism.

**2. Approve access**

ChatGPT opens Formbricks in your browser and registers itself. Sign in and **approve** the
requested access; ChatGPT then scans the available tools.

> [!NOTE]
>
> Like the Claude apps, ChatGPT connects from OpenAI's servers, so the MCP URL must be a **public
> HTTPS** address — not `localhost`.

## Codex

**1. Add the server**

Include `--oauth-resource` so the access token is audience-bound to the MCP resource:

```bash theme={null}
codex mcp add formbricks \
  --url https://app.formbricks.com/api/mcp \
  --oauth-resource https://app.formbricks.com/api/mcp
```

**2. Authenticate**

```bash theme={null}
codex mcp login formbricks
```

Codex opens the browser to Formbricks, registers itself, and you **approve** on the consent
screen. For read-only access, restrict the scopes:

```bash theme={null}
codex mcp login formbricks --scopes surveys:read,workflows:read,feedbackRecords:read,responses:read,offline_access
```

Scope groups are independent — request only the ones you need (for example
`feedbackRecords:read,offline_access` for feedback data alone).

**3. Verify**

```bash theme={null}
codex mcp list
codex mcp get formbricks
```

The equivalent `~/.codex/config.toml` entry:

```toml theme={null}
[mcp_servers.formbricks]
url = "https://app.formbricks.com/api/mcp"
oauth_resource = "https://app.formbricks.com/api/mcp"
```

## Manage and revoke access

Every client you authorize appears under **Settings → Account → Authorized Apps**
(`/account/settings/authorized-apps`), showing the client name, granted scopes, and when it was
approved. Click **Revoke** to immediately cut off a client's access; it will need to be re-authorized
to connect again.

Tokens are short-lived by design: an access token lasts **15 minutes** and the client refreshes it
silently in the background for up to **30 days** (the refresh window). After that — or after you
revoke — the client re-runs the sign-in and consent flow. Approving the write scopes
(`surveys:write`, `workflows:write`, `feedbackRecords:write`, `responses:write`) is re-confirmed
periodically for safety.

## Troubleshooting

> [accordion] claude.ai or ChatGPT says it couldn't register / connect
>
> Custom connectors connect from the vendor's cloud, which can't reach `localhost` or a private
> network. Use a **public HTTPS** MCP URL (Formbricks Cloud, or a tunnel to a self-hosted instance),
> or connect a local server with **Claude Code** instead.
>
> If registration fails with `400 invalid_redirect_uri`, the client asked to register a callback
> Formbricks doesn't allow. Formbricks accepts local (`http://localhost`, `127.0.0.1`, `[::1]`)
> callbacks and the exact claude.ai and ChatGPT callbacks. To allow another hosted client, a
> self-hoster can add its exact callback with `MCP_DCR_ALLOWED_REDIRECT_URIS`.

> [accordion] invalid\_client or a stale-registration error after reconnecting
>
> The client cached a registration that no longer exists on the server (e.g. the server data was
> reset). Clear the client's stored credentials for the server and re-authenticate — in Claude Code,
> remove and re-add the server (`claude mcp remove formbricks` then `claude mcp add …`) and run
> `/mcp` again.

> [accordion] invalid\_scope during sign-in
>
> The client requested a scope it isn't registered for. Reconnect from scratch so it re-registers
> with the scopes the server advertises (`surveys:read`, `surveys:write`, `workflows:read`,
> `workflows:write`, `feedbackRecords:read`, `feedbackRecords:write`, `responses:read`,
> `responses:write`, `offline_access`).

> [accordion] Stuck in a consent loop / keeps asking you to sign in
>
> Usually a cookie or stale-session issue. Make sure you're signed in to Formbricks in the same
> browser the client opens, and that third-party-cookie blocking or a private window isn't
> discarding the session. If it persists, revoke the app under **Settings → Account → Authorized
> Apps**, clear the client's stored credentials for the server, and reconnect. Self-hosters: an
> incorrect base URL (see below) also causes repeated redirects.

> [accordion] A tool call fails even though you're connected
>
> Scopes don't override your workspace role. Creating, editing, or deleting surveys or workflows
> requires `write` or `manage` permission on that workspace — ask a workspace owner/manager to grant
> it. `test_workflow` also needs `write`/`manage` even though it's a read-scoped dry-run, because it
> evaluates the live workflow definition. A `:write` tool likewise 403s if your token was only granted
> the matching `:read` scope; reconnect and approve write access.

> [accordion] Self-hosted: the browser can't complete sign-in / redirects fail
>
> OAuth discovery and redirects are built from your configured base URL. Serve Formbricks from a
> correct, public **HTTPS** origin and set `WEBAPP_URL` (and `BETTER_AUTH_URL`) to it. An
> `http://localhost` or mismatched origin breaks the flow for remote clients. See the
> [environment variables](https://formbricks.com/docs/self-hosting/configuration/environment-variables.md) reference.
>
> If the Formbricks container or pod cannot resolve that public origin when it verifies a token, set
> `MCP_OAUTH_JWKS_URL` to the internal `/api/auth/jwks` endpoint. Keep `WEBAPP_URL` and your auth base
> URL public: the internal override is only used for the server-side signing-key fetch. On an instance
> that still configures the auth URL under its older name, that is the one that has to stay public.
> `/api/auth/jwks` is correct only when no custom application subpath is configured. If Formbricks is
> mounted at `/formbricks`, use the complete internal URL, such as
> `http://formbricks:3000/formbricks/api/auth/jwks`.

> [accordion] Self-hosted behind Cloudflare: the client can't connect, but the URL works in your browser
>
> Only sign-in and consent happen in your browser. Discovery, registration, the token exchange and
> every tool call come straight from the client — for claude.ai and ChatGPT, from Anthropic's or
> OpenAI's servers. Cloudflare can treat that traffic as an AI agent or bot and block or challenge it
> while still letting your browser through. The client then gets a Cloudflare page instead of the JSON
> it expects, and reports what looks like an OAuth, registration or MCP error. So a URL that opens
> in your browser, or a consent screen that works, does not rule Cloudflare out.
>
> Check Cloudflare's **Security Events** for blocked or challenged requests to these paths (prefix
> each with your [custom subpath](https://formbricks.com/docs/self-hosting/configuration/custom-subpath.md) if you use one):
>
> * `/.well-known/oauth-protected-resource`, `/.well-known/oauth-authorization-server`,
>   `/.well-known/openid-configuration` and `/api/auth/.well-known/` — discovery
> * `/api/auth/oauth2/` — registration and tokens
> * `/api/mcp` — the MCP server itself
>
> Then let the client through without turning protection off for the whole site:
>
> * **AI bot policies:** under **Security → Settings → Configure AI bot policies**, set **Agent** to
>   **Allow**. Agent covers AI tools acting for a person in real time, which is what an MCP client
>   is. **Training** and **Search** can stay blocked. If you still use the older **Block AI bots**
>   setting, check that too.
> * **Bot Fight Mode** can't be skipped for specific paths, so if it blocks the client, turn it off.
>   **Super Bot Fight Mode** can: add a WAF custom rule with the **Skip** action for the paths above.
> * **WAF custom rules and Cloudflare Access:** make sure no Block, Managed Challenge or Access policy
>   covers the paths above. An MCP client can't solve a challenge or sign in to Access.
>
> Formbricks also fetches its own signing keys from your public `/api/auth/jwks` to verify tokens.
> If Cloudflare challenges that request, sign-in succeeds but every call to `/api/mcp` is rejected
> with `401`, and Formbricks logs `MCP OAuth authentication failed` with `failureSource: "jwks_fetch"`.
> Set `MCP_OAUTH_JWKS_URL` to the internal endpoint so that fetch doesn't go through Cloudflare (see
> the entry above).

***

Need the tool schemas, response shapes, or the API-key fallback? See the
[MCP server technical handbook](https://formbricks.com/docs/development/technical-handbook/mcp-server.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.