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 your workspace: list and read surveys, create link surveys, update or delete them, and read or add Unify Feedback records. The agent goes through the same APIs and permission checks 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:

​
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 survey, workflow and feedback-record tools, grouped into scopes you approve on the consent screen. Read tools require the matching :read scope; tools that create, update, or delete require the :write scope: ¹ test_workflow is a dry-run (no changes are saved), so it only needs the workflows:read scope — but because it evaluates the live workflow definition, it requires write or manage permission on the workspace. A read-only member will get a 403 even though the scope matches. ² Changing a record that already exists is held to a higher bar than creating one, because a feedback dataset shared across workspaces has no way to tell whose records are whose. Connected over OAuth (the flow on this page), both tools require you to be an organization owner or manager. Authenticated with an API key instead, they require the dataset to be assigned to a single workspace — a workspace-scoped key cannot be shown to own a record in a shared one — and delete_feedback_record additionally requires manage permission, matching DELETE elsewhere in the API. Creating, reading and searching are unaffected either way. Scope groups are independent — a client can be granted feedback-record access without survey access, or the other way around. list_workspaces is available to any read scope, since every other tool needs a workspace id.
The feedback-record tools work with Unify Feedback data and need the Enterprise Edition (feedbackDirectories), plus a feedback dataset assigned to the workspace. Without the entitlement or a directory, those tools return an authorization or validation error while the survey tools keep working.
delete_feedback_record permanently deletes a record — there is no undo and no trash. Grant feedbackRecords:write only to clients you want to be able to change or delete feedback, and keep read-only agents on feedbackRecords:read. Corrections via update_feedback_record are also irreversible — the previous value is kept only in the audit log.
Feedback records can be filtered by source, question, submission, end user, chosen option, language, date range, and by enrichment output — sentiment, emotions and whether a record has been enriched or translated at all. Any filter accepts several values, which are OR-ed, while different filters are AND-ed, and the listing can be ordered by when feedback was collected or when it was stored. count_feedback_records answers “how many” without fetching the records themselves — so an agent can report totals without pulling anyone’s feedback text into the conversation. The two search tools match by meaning rather than keywords (“checkout is confusing” finds “I couldn’t figure out how to pay”), and find_similar_feedback_records shows how widely one piece of feedback is echoed by others. They rely on the feedback service having an embedding model configured; on self-hosted installs without one they report that they are unavailable. Newly created records become searchable a short while after they arrive, and records without text are never searchable.
Scopes are only a coarse gate. Access is always bounded by your Formbricks workspace role: even if a client holds a :write scope, a call only succeeds if you have write/manage permission on the target workspace — and deleting a feedback record needs manage. 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. Survey tools map to the v3 Surveys API they wrap; feedback-record tools read and write Unify Feedback data.