MCP tools reference
Every tool the Surbee MCP server exposes, with its parameters and whether it changes your workspace.
Every tool acts on the workspace of the account that connected the app. Survey ids
come from get_all_surveys or find_surveys. Tools marked Changes workspace
write to your account. Tools marked Destructive cannot be undone, and apps that
confirm tool calls will ask you before running them.
Parameters marked with an asterisk are required. For tools that take survey_id,
survey_ids or all_surveys, give one of the three.
Workspace
| Tool | What it does | Parameters |
|---|---|---|
get_all_surveys | Lists every survey with its status, dates and share link. | include_archived |
find_surveys | Finds surveys from a loose description by searching titles, descriptions, questions and options. | query* |
get_survey_details | One survey: whether it is published, its response count, pages, and every question with its id, type, options and required flag. | survey_id* |
Build and edit
| Tool | What it does | Parameters | |
|---|---|---|---|
create_survey | Builds a new survey or AI interview from a brief with Surbee's builder agent and saves it as a draft. Returns the editor link. Takes up to a minute. | title, brief, kind (intelligent or traditional) | Changes workspace, uses credits |
edit_survey | Changes an existing survey with the builder: add, remove or rewrite questions, reorder, restyle, or change an AI interview's voice and tone. | project_id, changes | Changes workspace, uses credits |
update_survey_details | Renames a survey or changes its description. | project_id*, title, description | Changes workspace |
update_question | Changes one question's wording, helper text, required flag or options. | project_id, question_id, label, description, required, options | Changes workspace |
publish_survey | Publishes a survey and returns its public link. | project_id* | Changes workspace |
share_survey | Returns the share link, QR code and embed code for a published survey. | project_id*, format (all, link, qr, embed) | |
delete_questions | Deletes questions from a survey. | project_id, question_ids, summary* | Destructive |
delete_survey | Deletes a survey and all its responses. | project_id, summary | Destructive |
The kind on create_survey defaults to intelligent, an AI interview that asks
its own follow-up questions. Use traditional for fixed question lists, forms,
quizzes and scores tracked over time.
Responses
| Tool | What it does | Parameters |
|---|---|---|
query_responses | Lists individual responses with filters, newest first by default. Returns ids for get_response_details. | survey_id, limit (max 100), offset, flagged_only, min_completion_time_seconds, max_completion_time_seconds, device, order_by (created_at, completion_time, fraud_score), order_direction, date_from, date_to |
get_response_details | One response in full: every answer, time spent per question, device, Cipher quality, flag reasons and your verdict. | response_id* |
get_time_series_data | Response counts over time, for trends. | survey_id, group_by (hour, day, week, month), date_from, date_to, flagged_only |
Analysis
These compute the same numbers as the Insights page. Preview responses are never counted.
| Tool | What it does | Parameters |
|---|---|---|
get_survey_stats | Headline numbers: responses, completion rate, first and last response, quality split. | survey_id, date_from, date_to |
compare_surveys | Puts the headline numbers for several surveys side by side. | survey_id, survey_ids, all_surveys, date_from, date_to |
get_dropoff | Where people stop answering, question by question. | survey_id, survey_ids, all_surveys, date_from, date_to |
analyze_question | The answer breakdown for one question, optionally split by another question. | question*, survey_id, survey_ids, all_surveys, segment_by, trusted_only |
count_respondents | Counts people who match answer conditions, such as rated 4 or more and chose Monthly. | conditions*, match (all, any), quality (trusted, review, flagged, not_flagged), device, survey_id, survey_ids, all_surveys |
find_similar_answers | Finds open answers that mean the same thing as a description. | description*, question, limit, survey_id, survey_ids, all_surveys |
get_themes | Groups open answers into themes with counts and examples. | survey_id* |
find_group_differences | Finds where groups of respondents answer differently. | survey_id* |
get_key_drivers | Finds which answers move an outcome question most. | survey_id* |
Cipher and quality
| Tool | What it does | Parameters | |
|---|---|---|---|
get_cipher_summary | How many responses Cipher trusted, sent for review or flagged, and the most common reasons. | survey_id, survey_ids, all_surveys | |
explain_responses | Explains in plain words why responses were flagged, with the questions involved. | survey_id*, response_id, only_flagged, limit | |
run_evaluation | Has simulated respondents take a survey and reports confusing wording, missing options, bias and broken flow. Takes about a minute. | project_id*, mode (human_like, edge_case, stress_test, all) | Uses credits |
Results
Every tool returns JSON as text. Results that point at a survey include
editor_url, a link to open it in Surbee. When a tool cannot do what was asked, for
example because the survey was not found, the result is marked as an error and says why.