Skip to main content
Formbricks ships a Model Context Protocol (MCP) server that lets AI assistants — Claude Code, the Claude apps, Codex, and other MCP-capable clients — work with the surveys in your workspace: list and read surveys, create link surveys, and update or delete them. The agent calls the same v3 Surveys API you use in the app, so it always respects your permissions. You connect a client with your own Formbricks login over OAuth 2.1 — there are no API keys to generate, copy, or paste. You approve the connection once on a consent screen, and you can revoke it at any time.
Prefer to use a long-lived token instead (for scripts, CI, or a client that doesn’t support OAuth yet)? Formbricks API keys still work as a fallback — see the MCP server technical handbook.

​
The MCP server URL

Point your client at your Formbricks app’s /api/mcp endpoint:
InstanceMCP server URL
Formbricks Cloudhttps://app.formbricks.com/api/mcp
Self-hostedhttps://<your-formbricks-domain>/api/mcp

​
How the connection works

You don’t need to understand the details to connect, but here’s what happens under the hood when you add the server to a client:
  1. Discovery — the client reads the server’s OAuth metadata to find where to sign in.
  2. Registration — the client registers itself automatically using Dynamic Client Registration (DCR). There’s no client ID or secret for you to manage.
  3. Sign in & consent — your browser opens to Formbricks. You log in (if you aren’t already) and approve the requested access on a consent screen.
  4. Token — the client receives a short-lived access token it sends on every request, plus a refresh token so it can stay connected without asking you to sign in again.
The whole flow uses Authorization Code + PKCE, the standard the MCP authorization spec requires.

​
What the agent can do

The MCP server exposes six survey tools, grouped into two scopes you approve on the consent screen:
ScopeToolsWhat it allows
surveys:readlist_surveys, get_survey, validate_surveyRead surveys and validate survey documents
surveys:writecreate_survey, patch_survey, delete_surveyCreate, update, and delete surveys
Scopes are only a coarse gate. Access is always bounded by your Formbricks workspace role: even if a client holds surveys:write, a call only succeeds if you have write/manage permission on the target workspace. An agent can never do more than you can.

​
Prerequisites

  • A Formbricks account with access to the workspace whose surveys you want to work with. Read-only tasks need read; creating or editing surveys needs write or manage.
  • The MCP server URL for your instance (see the table above).
  • An MCP client that supports remote HTTP servers with OAuth — see the setup guides for Claude Code, the Claude apps, and Codex.
Self-hosting? The OAuth provider is built in and enabled automatically — there’s nothing extra to turn on. It just needs your instance to be served from a correct, public HTTPS base URL (set via WEBAPP_URL / BETTER_AUTH_URL). The discovery metadata and browser redirects are built from that URL, so an http://localhost or misconfigured origin will break the OAuth flow for remote clients. See the self-hosting configuration.

​
Next steps

Set up your MCP client

Copy-paste guides for Claude Code, the Claude apps (custom connectors), and Codex — plus how to manage and revoke access.
For the tool schemas, response formats, discovery endpoints, and the API-key fallback, see the MCP server technical handbook. Each tool maps to the v3 Surveys API it wraps.