You can run, configure, and use the @cyanheads/survey-mcp-server to run production-grade, LLM-driven surveys with structured data collection. It supports skip logic, session resumption, multi-tenancy, and pluggable storage backends, enabling dynamic interview flows and reliable data capture across environments.

How to use

Learn how to operate the survey MCP server from an MCP client. You will start a new survey session, ask and submit responses, check progress, resume incomplete sessions, and export results. The server provides rich context to the client, including current eligibility, suggested next questions, validation feedback, scoring, and progress updates to drive natural, projective conversations.

How to install

Prerequisites include having Bun installed. You will run the server locally in development mode or deploy to Cloudflare Workers. Use the provided commands to clone the repository, install dependencies, and start the server.

## Prerequisite: Bun v1.2.0+ is required

# Install Bun (if not already installed)
# Follow Bun's official guide to install Bun

# Recommended local commands from the setup flow

## Clone the repository

git clone https://github.com/cyanheads/survey-mcp-server.git

## Enter the project

cd survey-mcp-server

## Install dependencies

bun install

## Explore survey definitions (example)

survey-definitions/ contains example JSON definitions

## Run in local HTTP transport (production-style start)

bun rebuild

bun start:http

## Run in local STDIO transport (development-style start)

bun start:stdio

## Cloudflare Workers deployment (optional)

bun build:worker

bun deploy:dev

bun deploy:prod

Note: You may choose to run via HTTP or STDIO depending on your deployment target. The HTTP variant exposes an HTTP server, while the STDIO variant runs as a local process suitable for embedding or testing.

Configuration and startup

Configure the MCP client to connect to the server by using the server's transport and start command. The following settings illustrate a typical local development setup for a Bun-based MCP server. You can adjust the survey definitions path and responses path as needed.

{
  "mcpServers": {
    "survey-mcp": {
      "command": "bunx",
      "args": ["@cyanheads/survey-mcp-server@latest"],
      "env": {
        "MCP_LOG_LEVEL": "info",
        "SURVEY_DEFINITIONS_PATH": "./survey-definitions",
        "SURVEY_RESPONSES_PATH": "./survey-responses"
      }
    }
  }
}

Additional features and usage notes

The server ships with eight tools that manage the complete survey lifecycle. These tools are designed to be invoked by an AI agent or client to navigate surveys, manage sessions, validate responses, compute scores, and export results.

Key usage patterns include starting a session, querying for the next eligible questions, submitting responses with validation, checking progress, resuming incomplete sessions, and exporting results. Use the tools to drive a conversational interview while ensuring data integrity and tracking progress across tenants when needed.

Available tools

survey_list_available

Discover available surveys by recursively scanning the survey definitions path and returning survey metadata such as ID, title, description, duration, and question count. Supports optional tenant filtering.

survey_start_session

Initialize a new survey session with a unique session ID, load the complete survey definition, and return initial suggested questions based on eligibility. Includes guidance for LLMs and session metadata.

survey_get_question

Refresh a specific question's eligibility and details after changes in session state, including eligibility reasons and whether the question has already been answered.

survey_submit_response

Record a participant's answer with validation, compute the score if enabled, update progress, and provide refreshed suggested questions and guidance for the LLM.

survey_get_progress

Return the current session progress, including completed/remaining questions, score, and blockers to completion.

survey_complete_session

Finalize a completed session, validate required questions, mark completion, and return a final summary with score and duration.

survey_export_results

Export session data in CSV or JSON, with filters for survey, status, and date ranges.

survey_resume_session

Resume an incomplete session by restoring full context and providing updated next suggested questions and welcome-back guidance.