survey

The cyanheads survey MCP server turns LLMs into intelligent interviewers, enabling dynamic, multi-question surveys with skip logic, session resumption, multi-tenant support, and pluggable storage backends. It exposes a suite of tools that manage the full lifecycle of a survey session—from listing available surveys to starting a session, fetching and validating questions, recording responses, monitoring progress, and exporting results. Use the tools to drive conversational interactions with participants while ensuring data is collected in a structured, auditable way. The server returns guidance for LLMs at key steps (e.g., initial guidance for a new session, updated guidance after responses) to keep the conversation aligned with survey goals.

Key capabilities include: survey_list_available to discover surveys, survey_start_session to initialize a session with complete context, survey_get_question to re-evaluate eligibility after participant input, survey_submit_response to record answers and receive next suggested questions, survey_get_progress to monitor completion and score, survey_complete_session to finalize, survey_export_results to export data in CSV or JSON, and survey_resume_session to continue an incomplete session with full context. These tools work together to support complex logic (conditional questions, required vs. optional items) and produce structured data suitable for downstream analytics.

Prerequisites:

• Node.js 18+ or a compatible runtime (or use a compatible package manager if you prefer).
• npm or yarn to install and run packages.

Install steps:

1. Ensure Node.js and npm are installed. You can verify with:

node -v
npm -v

2. Install or invoke the MCP server package. This project is published as an npm package named @cyanheads/survey-mcp-server. You can run it directly via npx (no global install required):

npx -y @cyanheads/survey-mcp-server

3. If you prefer a local installation, you can install as a dev dependency in your project:

npm install --save-dev @cyanheads/survey-mcp-server

Then run the server using your project’s usual script, for example:

node node_modules/@cyanheads/survey-mcp-server/dist/server.js

4. (Optional) Configure storage backends and environment variables as needed per your deployment (see Additional Notes for details).

5. Start the server and verify it responds to the MCP protocol as documented by the package maintainers.

Notes and tips:

• Environment variables: you may need to configure SURVEY_DEFINITIONS_PATH to point to your survey definitions, and storage-related variables if you swap the default backend. Check the docs for required/optional env vars.
• Multi-tenancy: the server supports tenant-aware operation; ensure tenant identifiers are provided when starting sessions if your deployment uses multiple tenants.
• Skip logic and eligibility: questions become available based on prior answers. If a question is not showing as eligible, review the eligibilityReason provided in responses to diagnose conditional logic.
• Data export: use survey_export_results to export CSV or JSON for analytics, filtering by survey ID, status, or date ranges.
• Backups and data retention: plan for backups of survey definitions and back-end storage to prevent data loss.
• Versioning: keep an eye on MCP SDK compatibility with your server version to ensure smooth integration with client tooling.