Set Up Your MCP Client - Documentation

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).

Claude Code

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

Add the server

claude mcp add --transport http formbricks https://app.formbricks.com/api/mcp

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.

Verify

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:

{
  "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.

Open the connectors settings

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

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.

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.

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.

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.

Approve access

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

Like the Claude apps, ChatGPT connects from OpenAI’s servers, so the MCP URL must be a public HTTPS address — not localhost.

Codex

Add the server

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

codex mcp add formbricks \
  --url https://app.formbricks.com/api/mcp \
  --oauth-resource https://app.formbricks.com/api/mcp

Authenticate

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:

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).

Verify

codex mcp list
codex mcp get formbricks

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

[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

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.

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.

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.

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 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.

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 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.

​Claude Code

​Claude apps (custom connectors)

​ChatGPT (MCP apps)

​Codex

​Manage and revoke access

​Troubleshooting

Claude Code

Claude apps (custom connectors)

ChatGPT (MCP apps)

Codex

Manage and revoke access

Troubleshooting