survey_list_availableLABSCO SUMMARY
The model conducts the interview; the server keeps the state.
Each response comes back with the questions that just became eligible and refreshed suggestions, so conditional branches appear at the right moment without the model tracking them itself. Sessions resume with everything restored, which is what lets a long survey survive a dropped conversation.
What it is
A TypeScript server that owns the survey lifecycle. It loads survey definitions from a directory, tracks each session's state, and tells the model which questions are currently eligible and why.
What you get
- Eight tools covering the whole lifecycle
- Surveys discovered from the definitions directory with id, title, description, estimated duration and question count — survey_list_available
- A session started with the full survey loaded up front, initial suggested questions, and conversational guidance for the model — survey_start_session
- A question's eligibility refreshed after the state changes, with the reason attached — survey_get_question
- An answer validated against the question's constraints, scored, and returned with updated progress and newly eligible questions — survey_submit_response
- Completion status, current score, and remaining required and optional questions — survey_get_progress
- A finished session finalised with a score summary, and results exported as CSV or JSON with filters — survey_complete_session, survey_export_results
- An incomplete session resumed with its full context restored — survey_resume_session
- Skip logic, multi-tenant filtering and pluggable storage backends
Requirements
Bun v1.3.0 or higher, or Node.js. SURVEY_DEFINITIONS_PATH points at the directory the server scans recursively for survey definitions.
Setup effort
One command — bunx @cyanheads/survey-mcp-server@latest
USE CASES
01
Collecting structured answers through a conversation
The model asks in its own words while the server validates each response against the question's constraints and records it in a fixed shape.
02
Asking follow-ups only when they apply
Conditional questions become eligible as earlier answers land, and each one carries the reason it is or is not available yet.
03
Picking a half-finished session back up
Resume restores the answered questions and progress, so the participant is not asked the same things twice.
04
Getting the results out
Finalise once the required questions are answered, then export as CSV or JSON filtered by status or date range.
8 tools
Listed in project docs. Your client may show a different list.
survey_start_sessionsurvey_get_questionsurvey_submit_responsesurvey_get_progresssurvey_complete_sessionsurvey_export_resultssurvey_resume_sessionBEFORE YOU INSTALL
What to know first
Tools you get
8 tools named in the project's documentation.
Requires
bunx on PATH
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
bunx @cyanheads/survey-mcp-server@latestMCP Clients
Cline
CLINE · 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"
}
}
}
}
