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
Authenticate
/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
.mcp.json at the repo root and authenticate with /mcp on first use:
Claude apps (custom connectors)
Use this for claude.ai and Claude Desktop, where Formbricks is added as a custom connector.Open the connectors settings
Add the server URL
https://app.formbricks.com/api/mcp and confirm. Leave the optional OAuth client fields
blank — Formbricks registers the connector automatically.Approve access
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
https://app.formbricks.com/api/mcp and choose OAuth as the authentication mechanism.Approve access
localhost.Codex
Add the server
--oauth-resource so the access token is audience-bound to the MCP resource:Authenticate
feedbackRecords:read,offline_access for feedback data alone).Verify
~/.codex/config.toml entry:
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.
Approving a client again with fewer scopes replaces what it was granted. Every earlier grant that
included a dropped scope stops refreshing, all of its tokens together, even ones the client had
already narrowed to the new scopes (for grants made before Formbricks 5.4, only the tokens that still
carry a dropped scope stop). The client gets invalid_grant and has to re-authorize, which issues
tokens within the new scopes. An access token it already holds keeps working until it expires, at
most 15 minutes later; one obtained with an authorization code issued before the change can start
that 15 minutes up to 10 minutes after it.
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, dashboards:write) is
re-confirmed periodically for safety.
Troubleshooting
claude.ai or ChatGPT says it couldn't register / connect
claude.ai or ChatGPT says it couldn't register / connect
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
invalid_client or a stale-registration error after reconnecting
claude mcp remove formbricks then claude mcp add …) and run
/mcp again.invalid_scope during sign-in
invalid_scope during sign-in
surveys:read, surveys:write, workflows:read,
workflows:write, feedbackRecords:read, feedbackRecords:write, responses:read,
responses:write, dashboards:read, dashboards:write, offline_access).Stuck in a consent loop / keeps asking you to sign in
Stuck in a consent loop / keeps asking you to sign in
A tool call fails even though you're connected
A tool call fails even though you're connected
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.Self-hosted: the browser can't complete sign-in / redirects fail
Self-hosted: the browser can't complete sign-in / redirects fail
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
Self-hosted behind Cloudflare: the client can't connect, but the URL works in your browser
/.well-known/oauth-protected-resource,/.well-known/oauth-authorization-server,/.well-known/openid-configurationand/api/auth/.well-known/— discovery/api/auth/oauth2/— registration and tokens/api/mcp— the MCP server itself
- 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.
/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.
API-key fallback
If your client cannot use OAuth, configure its HTTP headers to sendx-api-key to your instance’s
/api/mcp endpoint. Create a scoped API key for the required tools.
Store it in the client’s secret settings, not a committed configuration file. Tool access still depends
on scopes, workspace permissions and feature availability. Prefer OAuth where your client supports it.