MCP Server - Documentation

Overview

The Formbricks MCP server exposes a small v3 Surveys tool surface for AI agents. It runs inside the Formbricks web app at /api/mcp and reuses the same v3 Surveys API authentication, authorization, rate limiting, response handling, and audit logging paths as the REST routes.

OAuth 2.1 is the preferred authentication path for MCP clients. Formbricks API keys remain supported as a backwards-compatible fallback for local development, self-hosters, and clients that do not support MCP OAuth yet.

Looking for step-by-step setup guides for Claude Code, the Claude apps, and Codex? See Connect AI agents (MCP). This handbook covers the technical internals.

Endpoint

Use the streamable HTTP MCP endpoint on the Formbricks app:

https://app.formbricks.com/api/mcp

For local development:

http://localhost:3000/api/mcp

The route supports POST requests, runs with the Next.js Node.js runtime, and sets private no-store response headers. Browser-origin MCP requests must come from the configured Formbricks app origin. OAuth clients discover the protected resource metadata here:

https://app.formbricks.com/.well-known/oauth-protected-resource/api/mcp

The metadata advertises /api/mcp as the protected resource and points clients to the Better Auth issuer under /api/auth.

Authentication

OAuth 2.1

OAuth clients use Authorization Code + PKCE with Dynamic Client Registration. The MCP protected resource is:

https://app.formbricks.com/api/mcp

The authorization server issuer is:

https://app.formbricks.com/api/auth

Discovery endpoints:

Endpoint	Purpose
`/api/auth/.well-known/oauth-authorization-server`	Better Auth authorization metadata
`/api/auth/.well-known/openid-configuration`	OpenID Connect metadata
`/.well-known/oauth-authorization-server/api/auth`	RFC 8414 path-insertion alias
`/.well-known/openid-configuration/api/auth`	RFC 8414 OpenID path-insertion alias
`/.well-known/oauth-protected-resource`	MCP protected resource metadata
`/.well-known/oauth-protected-resource/api/mcp`	MCP resource-specific metadata

Supported scopes:

Scope	Use
`surveys:read`	`list_surveys`, `get_survey`, and read-only validation paths
`surveys:write`	`create_survey`, `patch_survey`, `delete_survey`, and write validations
`openid`	OpenID Connect subject interoperability
`profile`	User profile claims
`email`	User email claim
`offline_access`	Refresh tokens for MCP clients

The authorization server supports all of the above, but the MCP protected-resource metadata (/.well-known/oauth-protected-resource/api/mcp) advertises only surveys:read, surveys:write, and offline_access — the scopes an MCP client needs. Clients derive their Dynamic Client Registration scopes from that list, so offline_access must be advertised there for clients to be issued refresh tokens (openid/profile/email are OIDC scopes the MCP resource does not require). OAuth scopes only gate MCP tool categories. Actual workspace access is still evaluated at tool execution through the existing v3 authorization checks for the signed-in Formbricks user.

API-key fallback

API-key MCP access remains supported. Authenticate with a Formbricks API key in a request header:

Authorization: Bearer fbk_...

or:

x-api-key: fbk_...

Do not pass credentials in the query string. The MCP route rejects query credential names such as api_key, x-api-key, access_token, token, and authorization case-insensitively. API key permissions are enforced through the same workspace access checks as the v3 REST API:

Tool	Minimum Workspace Permission
`list_surveys`	`read`
`get_survey`	`read`
`create_survey`	`write` or `manage`
`validate_survey`	`write` or `manage` when the validation request checks write access
`patch_survey`	`write` or `manage`
`delete_survey`	`write` or `manage`

Store fallback MCP API keys as environment variables or client secrets. Do not commit API keys into MCP client config files.

Local Setup

Start Formbricks and prepare the database:

pnpm db:up
pnpm db:migrate:dev
pnpm --filter @formbricks/web dev

Verify OAuth discovery:

curl -sS http://localhost:3000/.well-known/oauth-protected-resource/api/mcp
curl -sS http://localhost:3000/.well-known/oauth-authorization-server/api/auth

OAuth-capable MCP clients should dynamically register a public client and request resource equal to the MCP URL:

http://localhost:3000/api/mcp

Manual Dynamic Client Registration smoke test:

curl -sS -X POST http://localhost:3000/api/auth/oauth2/register \
  -H "Content-Type: application/json" \
  --data '{
    "client_name": "MCP Inspector",
    "redirect_uris": ["http://127.0.0.1:6274/oauth/callback"],
    "token_endpoint_auth_method": "none",
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "scope": "openid profile email offline_access surveys:read surveys:write"
  }'

This passes scope explicitly, so it does not reproduce a real client’s behavior — real MCP clients register with the scopes from the protected-resource metadata’s scopes_supported (surveys:read surveys:write offline_access). Because the authorization server validates the /authorize request against the client’s registered scopes, a client that registers with a narrower set than it later requests (e.g. it registers surveys-only but requests offline_access) is rejected with invalid_scope. To smoke-test the real path, omit scope and let the client adopt the advertised set, or pass exactly what the metadata advertises.

The consent screen is served at /account/authorize. Users can revoke approved MCP clients from /account/settings/authorized-apps. For API-key fallback, create an API key in the Formbricks app with access to the target workspace. Use the least privileged permission needed by the agent workflow. Verify that the MCP endpoint can list tools:

export FORMBRICKS_MCP_API_KEY="fbk_..."

curl -sS -X POST http://localhost:3000/api/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FORMBRICKS_MCP_API_KEY" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Codex Configuration

OAuth

Add the HTTP MCP server. Include --oauth-resource so the OAuth access token is audience-bound to the MCP resource URL:

codex mcp add formbricks-local \
  --url http://localhost:3000/api/mcp \
  --oauth-resource http://localhost:3000/api/mcp

Authenticate and request the scopes the agent needs:

codex mcp login formbricks-local \
  --scopes openid,profile,email,offline_access,surveys:read,surveys:write

For read-only usage, omit surveys:write:

codex mcp login formbricks-local \
  --scopes openid,profile,email,offline_access,surveys:read

Codex opens the browser to Formbricks, completes Dynamic Client Registration, and stores the OAuth client and tokens in Codex’s credential store. The user approves the requested scopes on the Formbricks consent screen. Equivalent Codex config for the server entry:

[mcp_servers.formbricks-local]
url = "http://localhost:3000/api/mcp"
oauth_resource = "http://localhost:3000/api/mcp"

Verify the registration:

codex mcp list
codex mcp get formbricks-local

Then ask Codex to use the configured server:

Use the formbricks-local MCP server to list surveys for workspace clxx1234567890123456789012.

API-key fallback

Store the API key in the shell environment:

export FORMBRICKS_MCP_API_KEY="fbk_..."

For Codex Desktop on macOS, persist the value in the launch environment and restart Codex Desktop:

launchctl setenv FORMBRICKS_MCP_API_KEY "fbk_..."

codex mcp add formbricks-local-api-key \
  --url http://localhost:3000/api/mcp \
  --bearer-token-env-var FORMBRICKS_MCP_API_KEY

Claude Configuration

Claude Code

OAuth

Add the remote HTTP MCP server:

claude mcp add --transport http formbricks-local http://localhost:3000/api/mcp

Run /mcp and authenticate formbricks-local. Claude Code discovers the MCP protected-resource metadata, registers a public client whose scopes are taken from that metadata’s scopes_supported (surveys:read surveys:write offline_access), and launches the browser-based OAuth flow — there is no scope-entry step. You approve the requested scopes on the Formbricks consent screen. Workspace role determines whether surveys:write tools actually succeed at execution time (see Authentication), regardless of the granted scope. Verify it:

claude mcp list
claude mcp get formbricks-local

For project-shared Claude Code configuration, use .mcp.json without static credentials:

{
  "mcpServers": {
    "formbricks-local": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp"
    }
  }
}

If the installed Claude Code version does not start the OAuth flow for remote HTTP servers, use the API-key fallback below until that client is updated.

API-key fallback

Set the API key:

export FORMBRICKS_MCP_API_KEY="fbk_..."

Add the HTTP MCP server:

claude mcp add --transport http formbricks-local-api-key http://localhost:3000/api/mcp \
  --header "Authorization: Bearer $FORMBRICKS_MCP_API_KEY"

For a project-shared fallback configuration, keep the API key outside git:

{
  "mcpServers": {
    "formbricks-local-api-key": {
      "headers": {
        "Authorization": "Bearer ${FORMBRICKS_MCP_API_KEY}"
      },
      "type": "http",
      "url": "http://localhost:3000/api/mcp"
    }
  }
}

Claude Code will fail to parse this fallback config if FORMBRICKS_MCP_API_KEY is not set.

Claude Desktop

If the installed Claude Desktop build supports remote HTTP MCP server entries, add the same server definition to the Claude Desktop config file and restart Claude Desktop. Prefer the OAuth entry without headers when supported; use the API-key header entry only as a fallback. macOS config path:

~/Library/Application Support/Claude/claude_desktop_config.json

Example config:

{
  "mcpServers": {
    "formbricks-local": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp"
    }
  }
}

Fallback config with an API key:

{
  "mcpServers": {
    "formbricks-local-api-key": {
      "headers": {
        "Authorization": "Bearer ${FORMBRICKS_MCP_API_KEY}"
      },
      "type": "http",
      "url": "http://localhost:3000/api/mcp"
    }
  }
}

Set the API key in the Desktop launch environment before opening Claude Desktop when using the fallback config:

launchctl setenv FORMBRICKS_MCP_API_KEY "fbk_..."

If a Claude Desktop version only supports stdio MCP servers, use Claude Code for the HTTP endpoint or add a local stdio-to-HTTP bridge.

Tool Responses

Tool results include both structuredContent and a text content item containing the same JSON string. Successful results mirror the v3 REST response body and add requestId for correlation. Errors are returned as MCP error tool results with a structured v3 problem payload:

{
  "error": {
    "code": "bad_request",
    "detail": "Invalid survey document",
    "invalid_params": [
      {
        "name": "blocks.0.elements.0.headline",
        "reason": "Required"
      }
    ],
    "requestId": "req_...",
    "status": 400,
    "title": "Bad Request"
  }
}

Available Tools

list_surveys

Lists surveys in one workspace. The tool is read-only and idempotent. Input:

{
  "cursor": "opaque-cursor-from-previous-response",
  "filter": {
    "name": {
      "contains": "feedback"
    },
    "status": {
      "in": ["draft", "inProgress"]
    },
    "type": {
      "in": ["link"]
    }
  },
  "includeTotalCount": true,
  "limit": 20,
  "sortBy": "updatedAt",
  "workspaceId": "clxx1234567890123456789012"
}

Output:

{
  "data": [
    {
      "createdAt": "2026-04-21T10:00:00.000Z",
      "creator": {
        "name": "Ada Lovelace"
      },
      "id": "clsv1234567890123456789012",
      "name": "Product Feedback",
      "responseCount": 0,
      "status": "draft",
      "type": "link",
      "updatedAt": "2026-04-21T11:00:00.000Z",
      "workspaceId": "clxx1234567890123456789012"
    }
  ],
  "meta": {
    "limit": 20,
    "nextCursor": null,
    "totalCount": 1
  },
  "requestId": "req_..."
}

get_survey

Gets one survey by ID. The tool is read-only and idempotent. Input:

{
  "lang": ["en-US"],
  "surveyId": "clsv1234567890123456789012"
}

lang is optional. When supplied, it filters translatable survey fields to the requested language codes or configured aliases.

create_survey

Creates a block-based link survey using the v3 survey document contract. The tool writes data and is not idempotent. Input:

{
  "blocks": [
    {
      "elements": [
        {
          "headline": {
            "de-DE": "Was sollen wir verbessern?",
            "en-US": "What should we improve?"
          },
          "id": "satisfaction",
          "required": true,
          "type": "openText"
        }
      ],
      "name": "Main Block"
    }
  ],
  "defaultLanguage": "en-US",
  "endings": [],
  "hiddenFields": {
    "enabled": false
  },
  "languages": [
    {
      "code": "de-DE",
      "enabled": true
    }
  ],
  "metadata": {
    "cx_operation": "enterprise_onboarding",
    "title": {
      "de-DE": "Produktfeedback",
      "en-US": "Product Feedback"
    }
  },
  "name": "Product Feedback Survey",
  "status": "draft",
  "variables": [],
  "welcomeCard": {
    "enabled": true,
    "headline": {
      "de-DE": "Willkommen",
      "en-US": "Welcome"
    }
  },
  "workspaceId": "clxx1234567890123456789012"
}

Output uses the same survey resource shape as GET /api/v3/surveys/{surveyId} and includes the MCP requestId.

validate_survey

Validates a create or patch payload without writing survey changes. The tool is read-only and idempotent, but create validation still checks workspace write access when workspaceId is present. Create validation input:

{
  "data": {
    "blocks": [
      {
        "elements": [
          {
            "headline": {
              "en-US": "What should we improve?"
            },
            "id": "satisfaction",
            "required": true,
            "type": "openText"
          }
        ],
        "name": "Main Block"
      }
    ],
    "defaultLanguage": "en-US",
    "name": "Product Feedback Survey",
    "workspaceId": "clxx1234567890123456789012"
  },
  "operation": "create"
}

Patch validation input:

{
  "data": {
    "name": "Updated Product Feedback Survey"
  },
  "operation": "patch",
  "surveyId": "clsv1234567890123456789012"
}

Validation failures return 200 with valid: false and structured invalid_params, matching POST /api/v3/surveys/validate.

patch_survey

Updates a survey by ID using the v3 survey patch contract. The tool writes data, can be destructive, and is not idempotent. Omitted top-level fields are preserved. Provided top-level objects and arrays replace that whole subtree, so omitted nested entries inside a provided subtree can be removed. The patch tool does not deep-merge nested objects and does not implement JSON Patch.

For agent workflows, fetch the current survey first, modify only the intended top-level fields, run validate_survey with operation: "patch", and then submit the same patch with patch_survey.

Input:

{
  "data": {
    "metadata": {
      "cx_operation": "enterprise_onboarding",
      "title": {
        "en-US": "Updated Product Feedback"
      }
    },
    "name": "Updated Product Feedback"
  },
  "surveyId": "clsv1234567890123456789012"
}

Output uses the same survey resource shape as GET /api/v3/surveys/{surveyId} and includes the MCP requestId.

delete_survey

Deletes one survey by ID. The tool is destructive, writes data, and is not idempotent. Input:

{
  "surveyId": "clsv1234567890123456789012"
}

The v3 REST delete operation returns 204 No Content. The MCP tool result contains the requestId so callers can correlate the audit trail:

{
  "requestId": "req_..."
}

Relationship To V3 Surveys API

The MCP server does not run custom survey database queries. Each tool calls the shared server-only v3 survey operations used by the REST routes:

MCP Tool	REST Contract
`list_surveys`	`GET /api/v3/surveys`
`get_survey`	`GET /api/v3/surveys/{surveyId}`
`create_survey`	`POST /api/v3/surveys`
`validate_survey`	`POST /api/v3/surveys/validate`
`patch_survey`	`PATCH /api/v3/surveys/{surveyId}`
`delete_survey`	`DELETE /api/v3/surveys/{surveyId}`

When the v3 OpenAPI contract changes, update the MCP schemas and this page together. The hand-maintained v3 OpenAPI spec lives at docs/api-v3-reference/openapi.yml.

Limitations

OAuth is user-delegated only. Machine-to-machine client credentials for MCP are not supported.
OAuth access tokens must be JWTs audience-bound to /api/mcp; opaque MCP access token introspection is not accepted by the MCP route.
API-key authentication remains supported for compatibility and fallback use.
The MCP server exposes only the v3 survey operations listed on this page.
Tool coverage depends on the current v3 Surveys REST endpoint coverage.
create_survey creates link surveys only. In-app survey creation and distribution settings are not part of the current v3 create operation.
patch_survey follows the v3 PATCH contract: top-level partial document updates only, no JSON Patch, and no nested deep merge. Provided top-level objects and arrays replace their whole subtree and can remove omitted nested entries.
validate_survey validates payload shape and references; it does not create languages, survey versions, or surveys.
Query-string credentials are rejected; use headers for API keys.
Large request bodies are rejected before the MCP handler using the same body-size policy as v3 APIs.

Implementation Files

apps/web/app/api/mcp/route.ts
apps/web/modules/mcp/auth.ts
apps/web/modules/mcp/server.ts
apps/web/modules/mcp/tools/surveys.ts
apps/web/modules/mcp/tools/schemas.ts
apps/web/app/api/v3/surveys/lib/operations.ts

​Overview

​Endpoint

​Authentication

​OAuth 2.1

​API-key fallback

​Local Setup

​Codex Configuration

​OAuth

​API-key fallback

​Claude Configuration

​Claude Code

​OAuth

​API-key fallback

​Claude Desktop

​Tool Responses

​Available Tools

​list_surveys

​get_survey

​create_survey

​validate_survey

​patch_survey

​delete_survey

​Relationship To V3 Surveys API

​Limitations

​Implementation Files

Overview

Endpoint

Authentication

OAuth 2.1

API-key fallback

Local Setup

Codex Configuration

OAuth

API-key fallback

Claude Configuration

Claude Code

OAuth

API-key fallback

Claude Desktop

Tool Responses

Available Tools

list_surveys

get_survey

create_survey

validate_survey

patch_survey

delete_survey

Relationship To V3 Surveys API

Limitations

Implementation Files