MCP tools

The Mapsurvey MCP server lets an AI agent — Claude, ChatGPT, Claude Code, Cursor or any client of the Model Context Protocol — read, build and publish your surveys from a conversation. It exposes the operations of the REST API as tools, scoped to the account that connected, and runs through the same rules as the editor. For setup, see Use the MCP server.

Connection

Server URL	https://mapsurvey.org/mcp (Streamable HTTP; one request per call, no streams)
Authentication	Sign in through the client (OAuth) — or a personal token made for the MCP server, sent as Authorization: Bearer msk_…
Plan	The workspace that owns a survey must be on Pro; otherwise tools on it answer pro_required
Scope	Only surveys you own or collaborate on, within the permissions the token or the Allow page granted
Limits	600 reads and 60 writes a minute and 5,000 calls a day per token; 300 tool calls per 10 minutes per session

Mapsurvey never sees your conversation with the agent — only the tool calls it decides to make. Each one is logged with the tool name and its outcome, never its arguments.

Call get_me first. It says which workspaces include the API and which tools the connection can use. Tools the connection may not use are not even listed to the agent.

What cannot be undone asks first. delete_survey, publish_survey and publish_unpublished_changes take confirm: true, which an agent should set only after you agreed in the conversation. A survey respondents already answered cannot be deleted from here at all.

Survey content is data, not instructions. Every result wraps what people wrote — titles, option labels, help texts — in a data field next to a fixed note telling the agent so. An agent that reads survey content can still be influenced by it; keep publishing and deleting behind confirmation and review what an agent built before you publish.

Tools

Arguments marked required must be given; the others are optional. Rich-text fields (subtext, subheading, thanks_html) are sanitised on save exactly as in the editor. An unknown argument is refused by name rather than ignored.

get_me

Call this first. Returns the user behind the token, their workspaces with plan and whether the API is included (the MCP server is a Pro feature: tools on a survey of a Free workspace answer pro_required with an upgrade URL), the token’s permissions, and the tools this token can use.

Any permission · read-only

list_surveys

Your surveys across the workspaces whose plan includes the API, newest first. hidden_by_plan counts workspaces of yours on the Free plan, whose surveys are not listed.

Permission surveys:read · role viewer · read-only

Argument	Type		Notes
cursor	string		next_cursor of the previous page.
limit	integer		Default 50.

get_survey

The whole survey in one call: settings, then every section in respondent order with all of its questions (sub-questions carry parent_id) and question groups (a question’s group_id names its group). Ids from here are what the editing tools take.

Permission surveys:read · role viewer · read-only

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys or create_survey).

create_survey

A new empty survey with one section, owned by you. Name the workspace by its slug when you belong to several (get_me lists them). Add sections and questions next; the survey stays unpublished until publish_survey.

Permission surveys:write · role workspace editor

Argument	Type		Notes
name	string	required
workspace	string		Workspace slug; optional when the token is bound to one or you belong to one.
language	string		Default en.
map_start	object (lat, lng, zoom)

update_survey

Change the fields you name: name, languages, redirect_url (“#” for the built-in thanks page), visibility, basemaps (preset keys or “style:” of a workspace map style), branding, the thanks page per language, the map start, and the survey period (opens_at, closes_at, schedule_timezone: before opens_at respondents see an “opens on” page, at closes_at the survey closes by itself). Settings need the owner role; the thanks page the editor role.

Permission surveys:write · role owner

Argument	Type		Notes
name	string
redirect_url	string		“#” for the built-in thanks page, or an absolute http(s) URL.
languages	list of string
visibility	public | private | demo
basemaps	list of string		Preset keys (streets, satellite, topo, paper, paper_b) or “style:” of a workspace map style; a key the workspace does not have is dropped.
default_basemap	string		One of basemaps; else the first enabled key.
show_branding	boolean
thanks_html	map		Thanks page per language; creator HTML, sanitised on save.
map_start	object (lat, lng, zoom)
use_geolocation	boolean
opens_at	date-time		Start of the survey period: ISO 8601 with an offset, or a naive value read in schedule_timezone. Null clears it.
closes_at	date-time		End of the survey period, after the start and in the future. Null clears it. Reopening a survey by hand clears a past end.
schedule_timezone	string		IANA zone (e.g. “Europe/Berlin”) naive period values are read in and times are shown in; “” = UTC.
survey	uuid	required	The survey uuid (from list_surveys or create_survey).

delete_survey

Move a survey to the trash (the owner can restore it in the editor for 30 days). Needs confirm: true after the user agreed. Refused when respondents have already answered: that deletion is done in the editor, where the answers are shown first. Unpublished changes are discarded with discard_unpublished_changes instead.

Permission surveys:delete · role owner · needs confirm: true

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys or create_survey).
confirm	boolean		Set to true only after the user confirmed this action in the conversation. Default False.

publish_survey

Make the survey live for respondents. Needs confirm: true after the user agreed. review: "pending" in the result means content screening is holding it until a human looks; translation_gaps asks you to confirm publishing with missing translations.

Permission surveys:publish · role owner · needs confirm: true

Argument	Type		Notes
acknowledge_translation_gaps	boolean		Default False.
clear_test_data	boolean		Default False.
survey	uuid	required	The survey uuid (from list_surveys or create_survey).
confirm	boolean		Set to true only after the user confirmed this action in the conversation. Default False.

close_survey

Stop collecting answers; the survey stays readable to its collaborators.

Permission surveys:publish · role owner

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys or create_survey).

start_unpublished_changes

On a published or closed survey, structural edits (adding, deleting, reordering, changing a question type) answer draft_required. Call this to get an editable copy – “unpublished changes” – and edit the returned uuid; respondents keep the live survey until publish_unpublished_changes.

Permission surveys:write · role editor

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys or create_survey).

publish_unpublished_changes

Replace the live survey with its unpublished changes as a new version. Needs confirm: true after the user agreed. incompatible_draft means the changes conflict with collected answers; repeat with force: true only if the user accepts that.

Permission surveys:publish · role owner · needs confirm: true

Argument	Type		Notes
acknowledge_translation_gaps	boolean		Default False.
force	boolean		Publish even when the changes conflict with collected answers. Default False.
survey	uuid	required	The survey uuid (from list_surveys or create_survey).
confirm	boolean		Set to true only after the user confirmed this action in the conversation. Default False.

discard_unpublished_changes

Throw the unpublished changes away; the live survey is untouched.

Permission surveys:write · role owner · cannot be undone

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys or create_survey).

create_section

Append a section (a page) to the survey; the other fields set it at once. layout is “map” (the page shows the map, for geo questions), “image” (a picture beside the questions, e.g. a welcome page; the picture is uploaded in the editor, else the survey cover is shown) or “form”. panel_side (left|right) and panel_width (default|third|half) place the questions on a computer screen; content_width (full|column) and content_valign (top|middle) place the content inside that panel; keep_panel_open keeps the questions visible while respondents place on the map (desktop, map sections). On a live survey this is a structural change: start_unpublished_changes first.

Permission surveys:write · role editor

Argument	Type		Notes
title	string
subheading	string
code	string
layout	map | image | form
panel_side	left | right
panel_width	default | third | half
content_width	full | column
content_valign	top | middle
keep_panel_open	boolean
next_label	string
visibility_rule	object (question_code, choice_codes, answered)
audience	everyone | respondents | operators		Who sees it: everyone, respondents only, or operators only (the “Enter a response” form workspace members fill in for someone else). Changing it on a live survey needs unpublished changes.
translations	map
map_start	object (lat, lng, zoom)
use_geolocation	boolean
survey	uuid	required	The survey uuid.

update_section

Change the fields you name. On a live survey wording (title, subheading, next_label, translations) and the layout (layout, panel_side, panel_width, content_width, content_valign, keep_panel_open) are applied in place; the code and the visibility rule are structure (draft_required).

Permission surveys:write · role editor

Argument	Type		Notes
title	string
subheading	string
code	string
layout	map | image | form
panel_side	left | right
panel_width	default | third | half
content_width	full | column
content_valign	top | middle
keep_panel_open	boolean
next_label	string
visibility_rule	object (question_code, choice_codes, answered)
audience	everyone | respondents | operators		Who sees it: everyone, respondents only, or operators only (the “Enter a response” form workspace members fill in for someone else). Changing it on a live survey needs unpublished changes.
translations	map
map_start	object (lat, lng, zoom)
use_geolocation	boolean
survey	uuid	required	The survey uuid.
section_id	integer	required	The section id (from get_survey).

delete_section

Delete a section with its questions. Answers to them go too: the first call answers answers_at_risk with the count; repeat with acknowledge_answer_loss: true only after the user agreed.

Permission surveys:write · role editor · cannot be undone

Argument	Type		Notes
survey	uuid	required	The survey uuid.
section_id	integer	required	The section id (from get_survey).
acknowledge_answer_loss	boolean		Default False.

reorder_sections

The new order of the pages; list every section id of the survey exactly once.

Permission surveys:write · role editor

Argument	Type		Notes
section_ids	list of integer	required
survey	uuid	required	The survey uuid.

add_question

Add a question at the end of a section. input_type picks the kind: text, text_line, number, choice, multichoice (with choices), range, rating, datetime, image, html (a formatted text block), and the map types point, line, polygon, spraycan. With parent_question_id (a geo or Objects question) it becomes a sub-question asked in that question’s pop-up for every placed feature – the only way to attach attributes to what respondents draw. subtext is help text (creator HTML, sanitised on save). On a live survey this is a structural change: start_unpublished_changes first.

Permission surveys:write · role editor

Argument	Type		Notes
name	string
subtext	string
input_type	text | number | choice | multichoice | range | rating | ranking | datetime | point | line | polygon | spraycan | image | text_line | html | photo | audio | document | thumbs | layer_objects | budget	required
required	boolean
choices	list of object (code, name, other, icon, group, color, description, cost)
validation_settings	object (min_value, max_value, outlier_sigma, min_length, area_outlier_factor, max_dots, max_file_mb, max_files, min_features, max_features)
budget	object (mode, total, unit, symbol, step, rule, min_items, show_shares, source, cost_property)		Settings of a budget question.
price	object (amount, per)		A map question’s price under a budget group; null removes it.
color	string
icon_class	string
display_style	string
visibility_rule	object (question_code, choice_codes, answered)
audience	everyone | respondents | operators		Who sees it: everyone, respondents only, or operators only (the “Enter a response” form workspace members fill in for someone else). Changing it on a live survey needs unpublished changes.
layer_id	integer
layer_from_answers	string		For an “Objects on the map” question: the code of a map question whose answers become a shared map (created on first use). Use instead of layer_id.
min_objects	integer
share_with_respondents	boolean
translations	map
survey	uuid	required	The survey uuid.
section_id	integer	required	The section id (from get_survey).
parent_question_id	integer		Make it a sub-question of this geo / Objects question (same section).

update_question

Change the fields you name. On a live survey wording, help text, translations and added options are applied in place; type, layer, visibility rule and removing an answered option are structure (draft_required). validation_settings replaces the whole object.

Permission surveys:write · role editor

Argument	Type		Notes
name	string
subtext	string
input_type	text | number | choice | multichoice | range | rating | ranking | datetime | point | line | polygon | spraycan | image | text_line | html | photo | audio | document | thumbs | layer_objects | budget
required	boolean
choices	list of object (code, name, other, icon, group, color, description, cost)
validation_settings	object (min_value, max_value, outlier_sigma, min_length, area_outlier_factor, max_dots, max_file_mb, max_files, min_features, max_features)
budget	object (mode, total, unit, symbol, step, rule, min_items, show_shares, source, cost_property)		Settings of a budget question.
price	object (amount, per)		A map question’s price under a budget group; null removes it.
color	string
icon_class	string
display_style	string
visibility_rule	object (question_code, choice_codes, answered)
audience	everyone | respondents | operators		Who sees it: everyone, respondents only, or operators only (the “Enter a response” form workspace members fill in for someone else). Changing it on a live survey needs unpublished changes.
layer_id	integer
layer_from_answers	string		For an “Objects on the map” question: the code of a map question whose answers become a shared map (created on first use). Use instead of layer_id.
min_objects	integer
share_with_respondents	boolean
translations	map
survey	uuid	required	The survey uuid.
question_id	integer	required	The question id (from get_survey).

delete_question

Delete a question with its sub-questions. Answers go too: the first call answers answers_at_risk with the count; repeat with acknowledge_answer_loss: true only after the user agreed.

Permission surveys:write · role editor · cannot be undone

Argument	Type		Notes
survey	uuid	required	The survey uuid.
question_id	integer	required	The question id (from get_survey).
acknowledge_answer_loss	boolean		Default False.

reorder_questions

Renumber a section’s top-level questions (or one pop-up’s sub-questions, with parent_id). items are question ids in the new order; a question group is {"g": <group id>, "q": [<ids>]}.

Permission surveys:write · role editor

Argument	Type		Notes
parent_id	integer		Order a pop-up’s sub-questions instead of the section’s top level.
items	list of integer or map	required	Question ids in order; a group is {“g”: , “q”: []}.
survey	uuid	required	The survey uuid.
section_id	integer	required	The section id (from get_survey).

set_choices

Replace the options of a choice / multichoice question. Keep an option’s code to keep its answers; a new option gets a code never used in the survey’s history. name is a string or a {language: text} map.

Permission surveys:write · role editor

Argument	Type		Notes
choices	list of object (code, name, other, icon, group, color, description, cost)	required
survey	uuid	required	The survey uuid.
question_id	integer	required	The question id (from get_survey).

import_survey

Create a whole survey from one document: the survey.json of Mapsurvey’s backup format (version “1.0”, a survey object with name, available_languages, sections with questions). The import runs in the background; the result is a job – poll get_import_job until its status is done or failed. Name the workspace by its slug when you belong to several.

Permission surveys:write · role workspace editor

Argument	Type		Notes
survey_json	map	required	The survey.json document as an object, not a string.
workspace	string		Workspace slug.

get_import_job

One of your import jobs: status (queued, running, done, failed), the survey it made, warnings.

Permission surveys:read · read-only

Argument	Type		Notes
job_id	integer	required	The job id import_survey returned.

get_response_summary

How many responses a survey has and what they say, question by question in section order: option counts with the most frequent “other” write-ins, number statistics, rating means, text and map answer counts. Sub-questions of map questions are nested under their map question; “Objects on the map” questions list each object with its answers. Counts the responses an export contains: no empty, deleted or rejected ones unless include_all. Start a report here, then use list_text_answers and get_answer_geojson for detail.

Permission responses:read · role viewer · read-only

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
version	string		One version (v3), several separated by commas (v10,v11), or omit for every version.
include_all	boolean		Also count deleted and rejected responses. Default False.
completed_only	boolean		Only responses that reached the last section. Default False.

list_responses

Individual responses, newest first, each with its “#N” number, language, validation status and every answer (map answers as GeoJSON geometry with their sub-answers). Prefer get_response_summary for numbers; use this to read particular responses.

Permission responses:read · role viewer · read-only

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
include_empty	boolean		Also responses that answered nothing. Default False.
cursor	string		next_cursor of the previous page.
limit	integer		Default 20.

list_text_answers

The non-blank answers to one text question or text sub-question, newest first, each with the response number. Page through with next_cursor to read every comment.

Permission responses:read · role viewer · read-only

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
question_id	integer	required	A question id from get_survey.
version	string		One version (v3), several separated by commas (v10,v11), or omit for every version.
include_all	boolean		Also count deleted and rejected responses. Default False.
completed_only	boolean		Only responses that reached the last section. Default False.
cursor	string		next_cursor of the previous page.
limit	integer		Default 50.

get_answer_geojson

The points, lines, areas or spray clouds respondents drew for one map question, as a GeoJSON FeatureCollection (WGS 84). Each feature carries the answers to the sub-questions as properties and the response it came from. Stops at limit features and then says truncated: true; for everything, hand the person a link from get_export_link.

Permission responses:read · role viewer · read-only

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
question_id	integer	required	A question id from get_survey.
version	string		One version (v3), several separated by commas (v10,v11), or omit for every version.
include_all	boolean		Also count deleted and rejected responses. Default False.
completed_only	boolean		Only responses that reached the last section. Default False.
limit	integer		Most features to return. Default 200.

get_export_link

A link for the person to download the responses as a file – xlsx (Excel), csv, zip (GeoJSON + CSV), gpkg (GeoPackage), shp (Shapefile) or kml. It works for 15 minutes and checks access again when opened. Give the person the link; do not try to open it yourself.

Permission responses:read · role viewer · read-only

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
format	xlsx | csv | zip | gpkg | shp | kml		Default xlsx.
version	string		One version (v3), several separated by commas (v10,v11), or omit for every version.
include_all	boolean		Also count deleted and rejected responses. Default False.
completed_only	boolean		Only responses that reached the last section. Default False.
files	boolean		Add files respondents uploaded. Default False.

moderate_response

Set a response’s status: approved, on_hold, not_approved (rejected responses leave exports, summaries and public results), or “” to clear it. It can be changed back. Needs the editor role.

Permission responses:moderate · role editor

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
response_id	integer	required	The response id from list_responses.
validation_status	approved | not_approved | on_hold | ``	required

get_share_links

How to send the survey out: its public link, the public results link (if that page is published), the HTML snippet to embed it in a website and the sites allowed to embed it. Only a published survey can be shared (shareable); otherwise reason says why. In testing, editors also get the test link.

Permission surveys:read · role viewer · read-only

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).

get_qr_code

A QR code of the survey link – or of one tracked link – as an image the person can save for a poster or flyer. Only for a published survey.

Permission surveys:read · role viewer · read-only

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
link_id	integer		A tracked link id from list_tracked_links.
size	integer		Pixels per module; 8 gives about 300 px. Default 8.

list_tracked_links

Campaign links – the survey link with UTM parameters, one per place it is posted – with how many responses started and completed through each.

Permission surveys:read · role viewer · read-only

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).

create_tracked_link

A campaign link for one place the survey is posted, e.g. utm_source “newsletter”, utm_medium “email”, utm_campaign “spring-2027”. Responses through it are counted separately. Needs the editor role; at most 200 per survey.

Permission surveys:write · role editor

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
utm_source	string	required
utm_medium	string
utm_campaign	string

delete_tracked_link

Remove a campaign link. Responses that came through it keep their source. Needs the editor role.

Permission surveys:write · role editor

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
link_id	integer	required	A tracked link id from list_tracked_links.

set_embed_hosts

Which websites may show the survey in a frame, e.g. [“example.org”, “*.city.gov”]. An empty list lets any site embed it. Replaces the current list. Needs the editor role.

Permission surveys:write · role editor

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
hosts	list of string	required

list_layers

The survey’s reference layers – context drawn under the answers (bus stops, parks, planned sites) and shared maps of respondents’ marks – with their style and object count.

Permission surveys:read · role viewer · read-only

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).

create_layer

A reference layer from GeoJSON you pass as geojson – a FeatureCollection, a Feature or a geometry in WGS 84 longitude/latitude (not projected metres). At most 5 000 features and 10 MB; multi-part geometries become one object per part; a “name” or “title” property becomes the object title. Omit geojson for an empty layer to fill with create_layer_object. To ask respondents about these objects, add an “Objects on the map” question with this layer_id. Needs the survey owner; at most 10 layers.

Permission surveys:write · role owner

Argument	Type		Notes
name	string
geojson	map		A FeatureCollection, a Feature or a bare geometry in WGS 84 (lng, lat). At most 10 MB and 5 000 features; multi-part geometries become one object per part. Omit for an empty layer.
survey	uuid	required	The survey uuid (from list_surveys).

update_layer

Rename a layer, change its colour (#rrggbb), the property used as label or key, popups, or its style: opacity, weight, fill_opacity, radius, icon, legend, and by – one rule colouring objects by one property (mode “categories” with classes [{value, color}] or “graduated”). Never changes geometry. Needs the survey owner.

Permission surveys:write · role owner

Argument	Type		Notes
name	string
color	string		#rrggbb
label_field	string		A property shown as the object title on the map.
key_field	string
show_popups	boolean
style	map		opacity, weight, fill_opacity, radius, icon, legend, and by — one rule on one property (categories or graduated classes). Normalised on save.
survey	uuid	required	The survey uuid (from list_surveys).
layer_id	integer	required	A layer id from list_layers.

reorder_layers

Set the stacking order of the layers: every layer id of the survey, bottom first. Needs the survey owner.

Permission surveys:write · role owner

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
layer_ids	list of integer	required

delete_layer

Delete a layer and all its objects. Refused while a question uses it. Needs confirm: true after the user agreed, and the survey owner.

Permission surveys:write · role owner · needs confirm: true

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
layer_id	integer	required	A layer id from list_layers.
confirm	boolean		Set to true only after the user confirmed this action in the conversation. Default False.

list_layer_objects

The objects of one layer – key, title, category, description, link, geometry, properties – paged.

Permission surveys:read · role viewer · read-only

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
layer_id	integer	required	A layer id from list_layers.
cursor	string		next_cursor of the previous page.
limit	integer		Default 50.

create_layer_object

One object: a Point, LineString or Polygon geometry in WGS 84, with title, category, description (shown on its card), an http(s) link and properties. Not on a shared map. Needs the survey owner.

Permission surveys:write · role owner

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
layer_id	integer	required	A layer id from list_layers.
geometry	map	required
key	string		Unique in the layer; generated when omitted.
title	string
category	string
description	string		Rich text shown on the object card.
link	string		An http:// or https:// address.
properties	map

update_layer_object

Change an object’s text, link, geometry or properties; the key stays. Needs the survey owner.

Permission surveys:write · role owner

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
layer_id	integer	required	A layer id from list_layers.
key	string	required	An object key from list_layer_objects.
geometry	map
title	string
category	string
description	string		Rich text shown on the object card.
link	string		An http:// or https:// address.
properties	map

delete_layer_object

Remove one object (answers about it stay in the responses). Needs confirm: true and the survey owner.

Permission surveys:write · role owner · needs confirm: true

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
layer_id	integer	required	A layer id from list_layers.
key	string	required	An object key from list_layer_objects.
confirm	boolean		Set to true only after the user confirmed this action in the conversation. Default False.

moderate_layer_object

On a shared map (a layer of respondents’ marks): show a mark to other respondents (“visible”), hold it (“pending”) or hide it (“hidden”). Needs the editor role.

Permission surveys:write · role editor

Argument	Type		Notes
survey	uuid	required	The survey uuid (from list_surveys).
layer_id	integer	required	A layer id from list_layers.
key	string	required	An object key from list_layer_objects.
status	string	required	visible, pending or hidden.

list_groups

The question groups of a section – top level first, then those inside a map question’s pop-up (parent_id) – with title, display style, visibility rule and their question ids in order.

Permission surveys:read · role viewer · read-only

Argument	Type		Notes
survey	uuid	required	The survey uuid.
section_id	integer	required	The section id (from get_survey).

create_group

A question group: a titled run of questions shown together as plain, card (default) or collapsible, with an optional description and one visibility rule for all of them. question_ids (questions of the same list – the section’s top level, or one pop-up with parent_id) move together to where the first of them was. On a published survey this needs unpublished changes (draft_required).

Permission surveys:write · role editor

Argument	Type		Notes
title	string
description	string
display_style	plain | card | collapsible
budget	object (mode, total, unit, symbol, step, rule, min_items, show_shares, source, cost_property)		Makes the group a budget: its map questions carry a price and respondents place marks until the total is spent (total, unit, symbol). Null removes the budget.
visibility_rule	object (question_code, choice_codes, answered)
audience	everyone | respondents | operators		Who sees it: everyone, respondents only, or operators only (the “Enter a response” form workspace members fill in for someone else). Changing it on a live survey needs unpublished changes.
translations	map
question_ids	list of integer		The questions the group holds, in order; they move together to where the first of them was. Questions of the same list only (the section, or the same pop-up).
parent_id	integer		Create the group in this question’s pop-up.
survey	uuid	required	The survey uuid.
section_id	integer	required	The section id (from get_survey).

update_group

Change a group’s title, description, display style or translations – these apply to a live survey at once – or its visibility rule and question_ids, which are structural (draft_required on a published survey). question_ids is the whole membership: questions left out stay in place, ungrouped.

Permission surveys:write · role editor

Argument	Type		Notes
title	string
description	string
display_style	plain | card | collapsible
budget	object (mode, total, unit, symbol, step, rule, min_items, show_shares, source, cost_property)		Makes the group a budget: its map questions carry a price and respondents place marks until the total is spent (total, unit, symbol). Null removes the budget.
visibility_rule	object (question_code, choice_codes, answered)
audience	everyone | respondents | operators		Who sees it: everyone, respondents only, or operators only (the “Enter a response” form workspace members fill in for someone else). Changing it on a live survey needs unpublished changes.
translations	map
question_ids	list of integer		The questions the group holds, in order; they move together to where the first of them was. Questions of the same list only (the section, or the same pop-up).
survey	uuid	required	The survey uuid.
group_id	integer	required	The group id (from get_survey or list_groups).

delete_group

Remove a group. Its questions stay where they are, ungrouped – unless with_questions: true, which deletes them too and needs confirm: true after the user agreed; when they have answers the first call answers answers_at_risk with the count, repeat with acknowledge_answer_loss: true.

Permission surveys:write · role editor · needs confirm: true

Argument	Type		Notes
survey	uuid	required	The survey uuid.
group_id	integer	required	The group id (from get_survey or list_groups).
with_questions	boolean		Default False.
acknowledge_answer_loss	boolean		Default False.
confirm	boolean		Set to true only after the user confirmed this action in the conversation. Default False.

duplicate_question

A copy right after the question, in its group, with “ (copy)” on the name, new codes and its sub-questions.

Permission surveys:write · role editor

Argument	Type		Notes
survey	uuid	required	The survey uuid.
question_id	integer	required	The question id (from get_survey).

duplicate_section

A copy of the section with all its questions and groups, right after it, “ (copy)” on the title.

Permission surveys:write · role editor

Argument	Type		Notes
survey	uuid	required	The survey uuid.
section_id	integer	required	The section id (from get_survey).

copy_question

Append a copy of a question from any survey you can read (source_question_id) to a section of this one, with new codes and its own copy of any image. With parent_id it goes into that map question’s pop-up, without the source’s own sub-questions.

Permission surveys:write · role editor

Argument	Type		Notes
source_question_id	integer	required	A question of any survey you can read.
parent_id	integer		Paste into this question’s pop-up (without the source’s own sub-questions).
survey	uuid	required	The survey uuid.
section_id	integer	required	The section id (from get_survey).

copy_section

Append a copy of a section from any survey you can read (source_section_id), with its questions and groups.

Permission surveys:write · role editor

Argument	Type		Notes
source_section_id	integer	required	A section of any survey you can read.
survey	uuid	required	The survey uuid.

duplicate_survey

A new unpublished survey “ (copy)” in the same workspace with this one’s sections, questions, groups, visibility rules, translations, settings and map layers – for running it again next year or in another district. Responses, versions, campaign links, collaborators and the public results page stay behind. Needs the editor role in the workspace.

Permission surveys:write · role workspace editor

Argument	Type		Notes
survey	uuid	required	The survey uuid.

move_question

Move a question to another section (section_id), into a map question’s pop-up (parent_id) or out of one (parent_id null), at position among the target list’s items (a group counts as one; default: the end). Between sections it keeps its answers and leaves its group. Into or out of a pop-up its answers cannot follow: the first call answers answers_at_risk with the count; repeat with acknowledge_answer_loss: true only after the user agreed. Visibility rules the move breaks are cleared and listed in removed_rules – tell the user.

Permission surveys:write · role editor

Argument	Type		Notes
section_id	integer		Target section of the same survey; default: its own.
parent_id	integer		Move into this question’s pop-up; null moves it to the section’s top level.
position	integer		Place among the target list’s items (a group counts as one); default: the end.
acknowledge_answer_loss	boolean		Default False.
survey	uuid	required	The survey uuid.
question_id	integer	required	The question id (from get_survey).

list_versions

The survey’s versions: the current one first, then the archived ones newest first, each with its publish date and counts of sections, questions and responses. Every publish of unpublished changes makes a new version; responses stay with the version they were given to.

Permission surveys:read · role viewer · read-only

Argument	Type		Notes
survey	uuid	required	The survey uuid.

restore_version

Roll the questionnaire back: unpublished changes holding version version’s sections and questions. Nothing respondents see changes until publish_unpublished_changes, which makes a NEW version – history is never rewritten. Only on a published survey without unpublished changes; needs the survey owner.

Permission surveys:write · role owner

Argument	Type		Notes
survey	uuid	required	The survey uuid.
version	integer	required	A version number from list_versions.

search_icons

Marker icons by meaning, best first – use before setting a question’s icon_class or a choice’s icon instead of guessing a name. Every word of q must match the icon’s name, label or search terms in lang (default: the user’s interface language) or English. set narrows to maki or temaki (map symbols) or fa (Font Awesome).

Permission surveys:read · read-only

Argument	Type		Notes
q	string		What the icon should show, e.g. “bench”, “bus stop”, “скамейка”.
lang	string		ISO 639-1 code of the words in q.
set	maki | temaki | fa
limit	integer		Default 20.

Errors

A refused call comes back as a tool error carrying the same envelope as the REST API: {"error": "<code>", "detail": "<text>", ...}.

Code	Meaning
scope_missing	The connection lacks the permission this tool needs (scope names it).
pro_required	The survey’s workspace is not on Pro (upgrade_url links to its billing page).
forbidden_role	You can see the survey but your role on it is too low (role names the one needed).
not_found	Nothing there — or nothing you may see. The two are deliberately the same answer.
validation	An argument is invalid for this survey; fields lists what and why.
draft_required	A structural change to a live survey: call start_unpublished_changes and edit the returned uuid (draft is it when it already exists).
answers_at_risk	The delete would remove count answers; repeat with acknowledge_answer_loss: true after the user agreed.
delete_blocked	Something else depends on what you are deleting.
translation_gaps	Some languages are missing text; repeat with acknowledge_translation_gaps: true.
incompatible_draft	Unpublished changes conflict with collected answers; repeat with force: true only if the user accepts that.
transition_refused	The survey cannot move to that status from where it is.
conflict	The request conflicts with the current state (e.g. unpublished changes already exist).
confirmation_required	An irreversible tool was called without confirm: true.
has_responses	The survey has count answered responses; delete it in the editor instead.
rate_limited	Too many calls; wait retry_after seconds (limit names the window).
server_error	Our fault. It is logged; retrying a read later is safe.

A malformed request — an unknown tool, or arguments that do not fit the schema — is a protocol error (-32602) naming the fields; a missing or invalid token is HTTP 401; a request from an unexpected browser origin is 403.

Related

• Use the MCP server
• Connect ChatGPT, Claude and other apps
• REST API reference