Survey MCP Server

@cyanheads/survey-mcp-server Transform LLMs into intelligent interviewers. A production-grade MCP server for conducting dynamic, conversational surveys with structured data collection. Features skip logic, session resume, multi-tenancy, and pluggable storage backends.

---

🛠️ Tools Overview

This server provides eight powerful tools for managing the complete survey lifecycle with LLM-driven interactions:

survey_list_available

Discover available surveys loaded from your survey definitions directory.

Key Features:

• Lists all surveys discovered via recursive directory scan of SURVEY_DEFINITIONS_PATH
• Returns survey metadata: ID, title, description, estimated duration, and question count
• Optional tenant filtering for multi-tenant deployments

Example Use Cases:

• "Show me all available surveys"
• "What surveys can participants take?"
• "List surveys for tenant X"

---

survey_start_session

Initialize a new survey session with complete context for LLM-driven conversations.

Key Features:

• Creates new session with unique session ID and participant tracking
• Loads complete survey definition with all questions upfront
• Returns initial suggested questions based on survey settings (configurable min/max, defaults to 3-5) based on eligibility (unconditional questions first, required before optional)
• Each question includes currentlyEligible flag and eligibilityReason for transparency
• Provides guidanceForLLM field with conversational instructions
• Supports session metadata for tracking source, user agent, etc.

Example Use Cases:

• "Start the customer satisfaction survey for participant ABC123"
• "Begin a new session for the Q1 feedback survey"
• "Initialize survey session with metadata: source=web, userAgent=Claude"

---

survey_get_question

Refresh a question's eligibility and details after session state changes.

Key Features:

• Returns current eligibility status based on latest session state
• Provides eligibility reason (e.g., "Conditional logic satisfied", "Always available")
• Indicates if question was already answered
• Useful for checking if conditional questions became available after previous answers

Example Use Cases:

• "Has question q2 become available yet?"
• "Check if the follow-up question is now eligible"
• "Refresh question details after the participant answered the dependency"

---

survey_submit_response

Record participant answers with validation and get dynamic response guidance.

Key Features:

• Validates responses against question constraints (min/max length, patterns, required fields, etc.)
• Calculates and returns score for response (if scoring is enabled on question options)
• Returns validation errors with specific, actionable feedback
• Updates session progress (percentage complete, questions answered, time remaining estimate, current score)
• Returns updatedEligibility array showing newly available conditional questions
• Provides refreshed nextSuggestedQuestions based on new state (count configurable per survey)
• Includes guidanceForLLM with context-aware instructions

Example Use Cases:

• "Submit answer 'very-satisfied' for question q1"
• "Record the participant's email: user@example.com"
• "Save free-form response with validation"

---

survey_get_progress

Check session status and completion eligibility.

Key Features:

• Returns completion status: in-progress, completed, abandoned
• Progress metrics: total questions, answered count, required remaining, percentage complete, current score
• Lists all unanswered required questions (with eligibility status)
• Lists all unanswered optional questions (with eligibility status)
• canComplete boolean indicating if session can be finalized
• completionBlockers array explaining what's preventing completion

Example Use Cases:

• "How much of the survey is complete?"
• "What required questions are still unanswered?"
• "Can we complete the survey now?"

---

survey_complete_session

Finalize a completed session when all required questions have been answered.

Key Features:

• Validates that all required questions (including conditionally required) are answered
• Updates session status to completed and sets completedAt timestamp
• Returns summary with total questions answered, session duration, and final score (if scoring enabled)
• Prevents duplicate completion

Example Use Cases:

• "Complete the survey session"
• "Finalize session sess_abc123"
• "Mark the survey as finished"

---

survey_export_results

Export session data for analysis and reporting.

Key Features:

• Export in CSV or JSON format
• Filter by survey ID, status, date range, and custom criteria
• Returns formatted data with record count and generation timestamp
• CSV format includes one row per session with flattened question responses
• JSON format preserves full session structure

Example Use Cases:

• "Export all completed responses for survey customer-satisfaction-q1-2025 as CSV"
• "Get JSON export of sessions completed in January 2025"
• "Export in-progress sessions for analysis"

---

survey_resume_session

Resume an incomplete session with full context restoration.

Key Features:

• Restores complete survey context and session state
• Returns all previously answered questions with responses
• Provides refreshed nextSuggestedQuestions for remaining questions (count configurable per survey)
• Shows elapsed time since last activity
• Current progress summary (percentage, remaining questions, current score)
• Includes guidanceForLLM with welcome-back messaging suggestions

Example Use Cases:

• "Resume session sess_abc123"
• "Continue the survey where the participant left off"
• "Restore session state for participant to finish later"

✨ Features

This server is built on the mcp-ts-template and inherits its rich feature set:

• Declarative Tools: Define capabilities in single, self-contained files. The framework handles registration, validation, and execution.
• Robust Error Handling: A unified McpError system ensures consistent, structured error responses.
• Pluggable Authentication: Secure your server with zero-fuss support for none, jwt, or oauth modes.
• Abstracted Storage: Swap storage backends (in-memory, filesystem, Supabase, Cloudflare KV/R2) without changing business logic.
• Full-Stack Observability: Deep insights with structured logging (Pino) and optional, auto-instrumented OpenTelemetry for traces and metrics.
• Dependency Injection: Built with tsyringe for a clean, decoupled, and testable architecture.
• Edge-Ready: Write code once and run it seamlessly on your local machine or at the edge on Cloudflare Workers.

Plus, specialized features for Survey Management:

• LLM-Driven Surveys: Tools provide rich context (progress, next suggested questions, validation results, scores) to guide natural conversation flow.
• Hybrid Flow Control: Guided mode with configurable suggested questions (defaults to 3-5) + flexible ordering based on conversation context.
• Scoring System: Support for quizzes and assessments with optional score fields on question options. Automatic score calculation and accumulation per session.
• Advanced Conditional Logic: Support for simple skip logic and complex AND/OR multi-condition branching with eligibility tracking.
• JSON-Based Survey Definitions: Define surveys in simple JSON files with recursive directory scanning.
• Multiple Question Types: free-form, multiple-choice, multiple-select, rating-scale, email, number, boolean, and advanced types like date, datetime, time, and matrix grids.
• Validation Engine: Min/max length, patterns, required fields, custom constraints, and date/time rules with extensible validator map pattern.
• Session Resume: Built-in state management allows participants to pause and continue later.
• Help Text: A helpText field on questions provides LLMs with context and guidance for asking questions naturally.
• Pagination Support: Scalable data retrieval with configurable pagination for session queries and exports.

🚀 Getting Started

MCP Client Settings/Configuration

Add the following to your MCP Client configuration file (e.g., cline_mcp_settings.json).

{

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

Prerequisites

• Bun v1.2.0 or higher.

Installation

1. Clone the repository:

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

1. Navigate into the directory:

cd survey-mcp-server

1. Install dependencies:

bun install

1. Explore example surveys: The survey-definitions/ directory contains example JSON files demonstrating various question types and features. Use these as a starting point for creating your own surveys.

🛠️ Core Capabilities: Survey Tools

This server equips AI agents with specialized tools to conduct dynamic, conversational surve