MCP Server

Model Context Protocol (MCP) is a standard that lets AI models (Claude, Cursor, Copilot, etc.) connect to SurveyNinja and work with your data directly — read surveys, responses, analytics, and perform actions without manual copying.

Contents

Connection
Resources
Tools
Technical details
Typical scenarios

1. Connection

Getting an API key

Log in to your SurveyNinja account.
Go to Settings → API / MCP.
Click "Create API key" and copy it — the key is shown only once.

Endpoint

POST https://mcp.surveyninja.io/mcp/v1

Authentication

Pass the API key in the Authorization header:

Authorization: Bearer 42|xK7mP9nQ2wL5eH8jR3vU6tY0iD4aF1bG

Configuration for Claude Desktop

File claude_desktop_config.json

{ "mcpServers": { "surveyninja": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-fetch"], "env": { "MCP_URL": "https://mcp.surveyninja.io/mcp/v1", "MCP_AUTH_HEADER": "Authorization", "MCP_AUTH_VALUE": "Bearer <your_api_key>" } } } }

Configuration for Cursor / VS Code

{ "mcp.servers": { "surveyninja": { "url": "https://mcp.surveyninja.io/mcp/v1", "headers": { "Authorization": "Bearer <your_api_key>" } } } }

Rate limits

180 requests per minute per user (tools/call, resources/read, etc.)
Export links are valid for 1 hour

2. Resources

Resources are read-only. To use them, send a resources/read request with the corresponding URI.

URI	Description
User and workspaces
user://me	Basic information about the current user
workspace://list	List of all user workspaces
Folders and surveys
folder://list	List of all user folders
quiz://list	List of all available surveys
Survey structure and configuration
quiz://{'{id}'}/structure	Full survey widget structure
quiz://{'{id}'}/texts	Custom UI labels
quiz://{'{id}'}/variables	Hidden variables (extra fields)
quiz://{'{id}'}/hidden_options	Service survey configuration options
quiz://{'{id}'}/widgets_hidden	Hidden widget metadata
Responses and analytics
quiz://{'{id}'}/answers	Paginated list of respondent answers
quiz://{'{id}'}/summary	Summary analytics (funnel, devices, geo)
quiz://{'{id}'}/report	Detailed widget report (with filters)
quiz://{'{id}'}/report_filters	Saved user filters
quiz://{'{id}'}/report/{'{uuid}'}/inputs	Text responses for input widgets
quiz://{'{id}'}/report/{'{uuid}'}/files	Files uploaded by respondents
Themes and promo codes
theme://list	List of workspace themes
theme://{'{id}'}/details	Detailed theme settings
promocode://list	Promo code group lists
promocode://{'{id}'}/codes	Codes in a specific promo code list

3. Tools

Tools are actions executed on the SurveyNinja side upon request from an AI model via the tools/call method.

Tool response format

Each tool returns an object with content fields (array of text blocks) and isError (false — success, true — error). On success, additional data fields are added.

Survey management

Tool	Description	Required parameters
create_quiz	Creates a new survey	`folder_id`
rename_quiz	Renames a survey	`quiz_id`, `name`
duplicate_quiz	Duplicates a survey	`quiz_id`
archive_quiz	Archives / unarchives	`quiz_id`, `archive`
delete_quiz	Deletes a survey (soft delete)	`quiz_id`
publish_quiz	Publishes the current version	`quiz_id`
move_quiz	Moves survey to another folder	`quiz_id`, `folder_id`
make_quiz_template	Creates a template from a survey	`quiz_id`
create_folder	Creates a survey folder	`workspace_id`, `name`

Survey content and structure

Tool	Description	Required parameters
update_quiz_widgets	Saves widget structure	`quiz_id`, `ids`, `entities`
update_quiz_texts	Updates button and element texts (paid plan)	`quiz_id`, `texts`
update_quiz_settings	Updates survey settings (language, limits, theme, scripts, etc.)	`quiz_id`
update_quiz_logic	Saves transition logic and scoring	`quiz_id`
update_quiz_note	Adds/updates an internal note	`quiz_id`, `notes`
upload_quiz_media	Upload media for the multimedia block (paid plan)	`quiz_id`, `type`
upload_quiz_widget_image	Upload image for a widget with media options	`quiz_id`

Design themes

Tool	Description	Required parameters
apply_quiz_theme	Applies a theme to a survey	`quiz_id`, `theme_id`
create_theme	Creates a theme and applies it to a survey (paid plan)	`workspace_id`, `quiz_id`
update_theme	Updates an existing theme	`workspace_id`, `theme_id`

Survey variables

Tool	Description	Required parameters
create_quiz_variable	Creates a hidden variable (extra field)	`quiz_id`, `name`
update_quiz_variable	Renames a variable	`quiz_id`, `field_id`, `name`
delete_quiz_variable	Deletes a variable	`quiz_id`, `field_id`

Hidden options

Tool	Description	Required parameters
create_hidden_option	Creates a survey service option	`quiz_id`, `name`, `value`
update_hidden_option	Updates a survey option	`quiz_id`, `opt_id`, `name`, `value`
delete_hidden_option	Deletes a survey option	`quiz_id`, `opt_id`
create_widget_hidden_option	Creates an option for a specific widget	`quiz_id`, `widget_uuid`, `name`, `value`
update_widget_hidden_option	Updates a widget option	`quiz_id`, `opt_id`, `name`, `value`
delete_widget_hidden_option	Deletes a widget option	`quiz_id`, `opt_id`

Responses, analytics and public links

Tool	Description	Required parameters
toggle_answer_visibility	Hides/shows a response	`quiz_id`, `answer_id`, `is_hide`
tag_answer	Adds/syncs response tags	`quiz_id`, `answer_id`, `tags`
generate_filtered_report	Generates a report with filters → report_uuid	`quiz_id`
share_summary_link	Public link to summary	`quiz_id`
share_report_link	Public link to report	`quiz_id`
share_answers_link	Public link to answer list	`quiz_id`

Export

All tools accept quiz_id (required). Download link is valid for 1 hour.

Tool	Description
export_answers_csv	Export answers to CSV
export_answers_xlsx	Export answers to XLSX
export_answers_word	Export answers to Word
export_summary_pdf	Export summary to PDF
export_filtered_report_pdf	Export filtered report to PDF
export_filtered_report_word	Export filtered report to Word

Promo codes (paid plan)

Tool	Description	Required parameters
create_promocode_group	Creates a promo code list	`quiz_id`, `name`, `codes`
add_promocodes	Adds codes to an existing list	`quiz_id`, `list_id`, `codes`

4. Technical details

Protocol version

2025-06-18

Transport

HTTP POST (JSON-RPC 2.0)

Connection method

POST /mcp/v1

Standard JSON-RPC methods

Method	Description
initialize	Session initialization, fetching server capabilities
tools/list	List all available tools
tools/call	Call a tool with parameters
resources/list	List all available resources
resources/read	Read resource content by URI
prompts/list	List prompt templates
prompts/get	Get a specific prompt template

Request example

POST https://mcp.surveyninja.io/mcp/v1 Authorization: Bearer 42|xK7mP9nQ2wL5eH8jR3vU6tY0iD4aF1bG Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "rename_quiz", "arguments": { "quiz_id": 123, "name": "New survey name" } } }

Error response format

{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "Invalid params: quiz_id is required" } }

5. Typical scenarios

1. Get list of surveys and structure of a specific one

1. resources/read: quiz://list → get list of surveys with IDs

2. resources/read: quiz://{'{id}'}/structure → get widget structure

2. Working with responses

1. resources/read: quiz://{'{id}'}/answers → get responses (with answer_id)

2. tools/call: tag_answer (add tags) or toggle_answer_visibility (hide/show)

3. Export with filtering

1. tools/call: generate_filtered_report (quiz_id, dateFrom/dateTo d.m.Y format, filters) → report_uuid

⚠ Date format here is d.m.Y (01.01.2024), while the quiz://report resource uses Y-m-d

2. resources/read: quiz://{'{id}'}/report/{'{uuid}'}/files or /inputs

3. tools/call: export_filtered_report_pdf (quiz_id) → PDF link

⚠ export_filtered_report_pdf and _word accept only quiz_id; report_uuid should not be passed

4. Adding promo codes

1. tools/call: create_promocode_group → create a list with initial codes → get list_id

2. tools/call: add_promocodes → add more codes to the list

3. resources/read: promocode://{'{list_id}'}/codes → verify added codes

5. Apply a theme and immediately get the survey structure

1. resources/read: theme://list → get list of themes with IDs

2. tools/call: apply_quiz_theme (quiz_id, theme_id)

→ the response already includes a quiz field with the structure — no extra resources/read needed

Full MCP documentation in markdown format for working with AI:

/static/mcp_user_guide.md — complete reference for resources and tools.

AI LLM format