Skip to main content
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.
1

Add the server

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

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:

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

​
Codex

1

Add the server

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

Authenticate

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

Verify

The equivalent ~/.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. 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 surveys:write is re-confirmed periodically for safety.

​
Troubleshooting

Custom connectors connect from Anthropic’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.
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.
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, offline_access).
Scopes don’t override your workspace role. Creating, editing, or deleting surveys requires write or manage permission on that workspace — ask a workspace owner/manager to grant it.
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.
Need the tool schemas, response shapes, or the API-key fallback? See the MCP server technical handbook.