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.devOr 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.
Tools reference
Every tool, its parameters, and which ones change your workspace.
Example prompts
Things to ask once Surbee is connected.
Authentication
There are two ways to connect. Both give the app access to your own workspace only.
| Method | Use it for | How |
|---|---|---|
| Sign in with Surbee (OAuth) | Claude, ChatGPT, Claude Code, Cursor, VS Code, Codex, Gemini CLI | The app opens a Surbee page where you approve access. Nothing to copy. |
| MCP key | Apps that cannot sign in, scripts, or headless agents | Create 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:
- Claude Code
- Claude.ai and Claude for desktop
- ChatGPT
- Codex
- Cursor
- VS Code with Copilot
- Windsurf
- Gemini CLI
- Cline
- Goose
- Raycast
- OpenCode
- LM Studio
- Anything else
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.devThen 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.
- Open Settings, then Connectors.
- Choose Add custom connector.
- Name it
Surbeeand set the URL tohttps://mcp.surbee.dev. - 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.
- Open Settings, then Apps and Connectors, and turn on Developer mode under Advanced.
- Choose Create, name it
Surbee, and set the server URL tohttps://mcp.surbee.dev. - Pick OAuth for authentication and accept the custom connector warning.
- Approve access on the Surbee page.
- In a new chat, enable Surbee from the tools menu.
Codex
codex mcp add surbee --url https://mcp.surbee.dev
codex mcp login surbeeCodex 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.devInside 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:
| Plan | MCP calls |
|---|---|
| Free | 20 a week, counted over the last 7 days |
| Hive | Unlimited |
| Swarm | Unlimited |
| Enterprise | Unlimited |
Some tools also spend credits:
| Action | Credits |
|---|---|
| Reading surveys, responses, analytics and Cipher results | None |
create_survey, edit_survey | The same survey credits as building in the app, based on question count |
run_evaluation | One 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.devandhttps://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.
| Endpoint | URL |
|---|---|
| MCP (Streamable HTTP) | https://mcp.surbee.dev |
| Protected resource metadata | https://mcp.surbee.dev/.well-known/oauth-protected-resource |
| Authorization server metadata | https://mcp.surbee.dev/.well-known/oauth-authorization-server |
| Dynamic client registration | https://mcp.surbee.dev/api/mcp/oauth/register |
| Authorization | https://app.surbee.dev/connect/authorize |
| Token | https://mcp.surbee.dev/api/mcp/oauth/token |
- Grant type
authorization_codewith PKCE (S256only). Clients are public (token_endpoint_auth_method: none). - Redirect URIs must be HTTPS,
httpon localhost or127.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
401with aWWW-Authenticateheader 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_surveyswith words from the title or a question.