Use Surbee from AI apps (MCP)

Connect Claude, ChatGPT, Cursor and other AI apps to your Surbee workspace with the official Surbee MCP server.

Surbee MCP is available on every plan. The Free plan includes 20 calls a week, and Hive, Swarm and Enterprise have unlimited calls. Building or evaluating surveys also uses the same credits as the Surbee app.

Quick setup

Add this server URL to any AI app that supports remote MCP servers, then sign in to Surbee when the app asks:

https://mcp.surbee.dev

Or paste this into your AI app and let it set itself up:

Set up the Surbee MCP server for me. Name: surbee. URL: https://mcp.surbee.dev.
Transport: Streamable HTTP. Auth: OAuth, so open the Surbee sign-in when you connect.
If you cannot do OAuth, ask me for a key from Settings, AI apps, and send it as an
"Authorization: Bearer" header. Then call get_all_surveys to check it works.

The Surbee MCP page has a longer version of this prompt with a copy button.

What is Surbee MCP?

Surbee MCP is Surbee's official Model Context Protocol server. It is a remote server at https://mcp.surbee.dev, so there is nothing to install. Once connected, your assistant can:

  • Find surveys by a loose description and read their questions
  • Build new surveys and AI interviews from a brief, edit them, and publish them
  • Read individual responses with timing, device and quality notes
  • Answer questions about your data: counts, breakdowns, drop-off, themes, key drivers
  • Check response quality with Cipher and explain why a response was flagged

The server implements the MCP Streamable HTTP transport and the MCP authorization specification (OAuth 2.1 with PKCE and dynamic client registration).

Available tools

The server exposes 26 tools in five groups: workspace, building, responses, analysis and Cipher. Your app's tool list always shows exactly what is available. See the tools reference for every tool and its parameters.

Authentication

There are two ways to connect. Both give the app access to your own workspace only.

MethodUse it forHow
Sign in with Surbee (OAuth)Claude, ChatGPT, Claude Code, Cursor, VS Code, Codex, Gemini CLIThe app opens a Surbee page where you approve access. Nothing to copy.
MCP keyApps that cannot sign in, scripts, or headless agentsCreate a key in Settings, then AI apps, and send it as Authorization: Bearer surbee_mcp_...

Keys are shown once

An MCP key is shown in full only when you create it. Keep it out of shared files and repositories. If a key leaks, revoke it in Settings, AI apps, and create a new one.

Supported clients

Surbee MCP works with any app that supports remote MCP servers. These are tested:

Setup

Connect your AI app to Surbee MCP and approve access to your workspace.

Claude Code

claude mcp add --transport http surbee https://mcp.surbee.dev

Then start Claude Code, type /mcp, pick surbee and choose Authenticate. Add --scope user to the first command to use Surbee in every project.

Claude.ai and Claude for desktop

Custom connectors are available on Claude Pro, Max, Team and Enterprise plans.

  1. Open Settings, then Connectors.
  2. Choose Add custom connector.
  3. Name it Surbee and set the URL to https://mcp.surbee.dev.
  4. Choose Connect and approve access on the Surbee page.

On Team and Enterprise plans an owner may need to add the connector for the organisation first.

ChatGPT

Access depends on your plan and your workspace settings.

  1. Open Settings, then Apps and Connectors, and turn on Developer mode under Advanced.
  2. Choose Create, name it Surbee, and set the server URL to https://mcp.surbee.dev.
  3. Pick OAuth for authentication and accept the custom connector warning.
  4. Approve access on the Surbee page.
  5. In a new chat, enable Surbee from the tools menu.

Codex

codex mcp add surbee --url https://mcp.surbee.dev
codex mcp login surbee

Codex opens your browser to approve access.

Cursor

Add Surbee to ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one:

{
  "mcpServers": {
    "surbee": {
      "url": "https://mcp.surbee.dev"
    }
  }
}

Open Cursor Settings, then MCP, and choose Needs login next to Surbee.

VS Code with Copilot

Open the Command Palette, run MCP: Add Server, choose HTTP, enter https://mcp.surbee.dev and name it Surbee. Or add it to .vscode/mcp.json:

{
  "servers": {
    "surbee": {
      "type": "http",
      "url": "https://mcp.surbee.dev"
    }
  }
}

Choose Start above the server and allow the sign-in when VS Code asks.

Windsurf

Create an MCP key in Surbee, then add this to ~/.codeium/windsurf/mcp_config.json. Windsurf uses serverUrl, not url.

{
  "mcpServers": {
    "surbee": {
      "serverUrl": "https://mcp.surbee.dev",
      "headers": { "Authorization": "Bearer YOUR_SURBEE_MCP_KEY" }
    }
  }
}

Gemini CLI

gemini mcp add --transport http surbee https://mcp.surbee.dev

Inside Gemini CLI, run /mcp auth surbee to sign in, and /mcp list to check it is connected.

Cline

Open MCP Servers, then Configure, and add this to cline_mcp_settings.json with a key from Surbee:

{
  "mcpServers": {
    "surbee": {
      "type": "streamableHttp",
      "url": "https://mcp.surbee.dev",
      "headers": { "Authorization": "Bearer YOUR_SURBEE_MCP_KEY" }
    }
  }
}

Goose

Run goose configure, choose Add Extension, then Remote Extension (Streamable HTTP). Use surbee as the name, https://mcp.surbee.dev as the URL, and add the header Authorization: Bearer YOUR_SURBEE_MCP_KEY.

Raycast

Run the Install Server command. Name it Surbee, pick HTTP as the transport, and use https://mcp.surbee.dev as the URL.

OpenCode

Add Surbee to opencode.json or ~/.config/opencode/opencode.json:

{
  "mcp": {
    "surbee": {
      "type": "remote",
      "url": "https://mcp.surbee.dev"
    }
  }
}

Sign-in starts on first use. To start it yourself, run opencode mcp auth surbee.

LM Studio

Open Program, then Install, then Edit mcp.json, and add:

{
  "mcpServers": {
    "surbee": {
      "url": "https://mcp.surbee.dev",
      "headers": { "Authorization": "Bearer YOUR_SURBEE_MCP_KEY" }
    }
  }
}

Other apps

If an app only runs local (stdio) MCP servers, bridge to Surbee with mcp-remote:

{
  "mcpServers": {
    "surbee": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.surbee.dev", "--header", "Authorization: Bearer YOUR_SURBEE_MCP_KEY"]
    }
  }
}

Without the --header arguments, mcp-remote opens the Surbee sign-in in your browser instead.

Setup steps can change as apps update. If something does not match, check your app's own MCP documentation.

Example prompts

Once Surbee is connected, try:

  • "Which of my surveys got the most responses this month?"
  • "Build an AI interview for churned customers about why they left. Keep it under ten minutes."
  • "In my onboarding survey, how did people who rated setup 1 or 2 describe the problem?"
  • "Where do people drop off in the Northside member survey?"
  • "How many responses did Cipher flag in the pricing study, and why?"
  • "Change question 3 in my NPS survey to a 0 to 10 scale and add an 'Other' option to Q5."
  • "Publish the event feedback survey and give me the link and a QR code."

Credits and limits

Every tool call counts toward your plan's MCP allowance:

PlanMCP calls
Free20 a week, counted over the last 7 days
HiveUnlimited
SwarmUnlimited
EnterpriseUnlimited

Some tools also spend credits:

ActionCredits
Reading surveys, responses, analytics and Cipher resultsNone
create_survey, edit_surveyThe same survey credits as building in the app, based on question count
run_evaluationOne evaluation charge

On every plan, calls are also rate limited to protect the service: up to 30 tool calls a minute and 300 a day, and up to 10 builds or evaluations an hour. When you reach a limit or run out of credits, the tool says so, says when you can try again, and links to billing.

Managing connections

Open Settings, then AI apps in Surbee to:

  • See every app you have connected and when it was last used
  • Disconnect an app, which stops it working straight away
  • Create and revoke MCP keys

Access does not expire on its own. Disconnect apps you no longer use.

Security best practices

The MCP ecosystem is changing quickly. These are the current recommendations.

  • Verify the endpoint. The only official Surbee MCP addresses are https://mcp.surbee.dev and https://app.surbee.dev/api/mcp. Check the address in any one-click install.
  • Know what you are granting. A connected app can read everything in your workspace and act as you: build, edit, publish and delete surveys.
  • Respondent text is untrusted. Open answers can contain instructions written to trick an AI. Surbee tells the assistant to treat answers as data, but keep an eye on what your assistant does after reading responses.
  • Keep confirmations on. Publishing and deleting are marked as destructive, so apps that ask before running tools will ask you first. Leave that setting on.
  • Mind your other tools. Surbee only acts inside your workspace, but other servers connected to the same app may send data elsewhere. Review what each one can do.
  • Approve each connection. Surbee asks you to approve every new app on a Surbee page, so a link alone cannot connect an app to your account.

For MCP client developers

Surbee MCP follows the MCP authorization spec, so standard clients need no special handling.

EndpointURL
MCP (Streamable HTTP)https://mcp.surbee.dev
Protected resource metadatahttps://mcp.surbee.dev/.well-known/oauth-protected-resource
Authorization server metadatahttps://mcp.surbee.dev/.well-known/oauth-authorization-server
Dynamic client registrationhttps://mcp.surbee.dev/api/mcp/oauth/register
Authorizationhttps://app.surbee.dev/connect/authorize
Tokenhttps://mcp.surbee.dev/api/mcp/oauth/token
  • Grant type authorization_code with PKCE (S256 only). Clients are public (token_endpoint_auth_method: none).
  • Redirect URIs must be HTTPS, http on localhost or 127.0.0.1, or a custom app scheme.
  • Access tokens do not expire and there are no refresh tokens. A revoked token returns 401.
  • An unauthenticated request returns 401 with a WWW-Authenticate header pointing at the resource metadata.
  • The server is stateless: no Mcp-Session-Id, and responses are plain JSON rather than an SSE stream.

Troubleshooting

  • "Sign in to Surbee to use this server." The app has no valid token. Reconnect it, or check the key has not been revoked in Settings, AI apps.
  • The sign-in page says the link does not work. Start the connection again from the app. The page only accepts requests from apps that registered with Surbee.
  • "Not enough Surbee credits." Building and evaluating need credits. Top up or upgrade in Settings, then Billing.
  • "This account has used the 20 Surbee calls a week that come with the Free plan." The message says when the next call frees up. Wait for older calls to fall out of the 7-day window, or upgrade to Hive for unlimited calls.
  • The app cannot see a survey. Tools only see surveys in the account you signed in with. Use find_surveys with words from the title or a question.