MCP Server

Control Chorus Research from any AI coding agent via the Model Context Protocol (MCP).

The Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and data sources. The Chorus Research MCP server gives your AI agent direct access to survey creation, launch, and response collection — no HTTP calls or SDK wrappers needed.

The server exposes:

• 10 tools — Audiences, pricing, surveys, launch, and response export
• 2 resources — Audience catalog and pricing configuration
• 2 prompts — Survey design guide and pre-launch checklist

Installation

No manual installation is needed — MCP clients launch the server automatically using npx.

npx @chorus-research/mcp

npm install -g @chorus-research/mcp
chorus-research-mcp

Configuration

The server requires a CHORUS_API_KEY environment variable. You can obtain a key from the API Keys section in the Chorus Research app.

Environment Variables

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "chorus-research": {
      "command": "npx",
      "args": [
        "-y",
        "@chorus-research/mcp"
      ],
      "env": {
        "CHORUS_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktop

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "chorus-research": {
      "command": "npx",
      "args": [
        "-y",
        "@chorus-research/mcp"
      ],
      "env": {
        "CHORUS_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "chorus-research": {
      "command": "npx",
      "args": [
        "-y",
        "@chorus-research/mcp"
      ],
      "env": {
        "CHORUS_API_KEY": "your-api-key"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "chorus-research": {
      "command": "npx",
      "args": [
        "-y",
        "@chorus-research/mcp"
      ],
      "env": {
        "CHORUS_API_KEY": "your-api-key"
      }
    }
  }
}

Tools

The MCP server exposes 10 tools organized into 5 groups. Your AI agent can call these directly — no HTTP setup required.

Audiences

list_audiences

List all available audience segments for survey targeting. Each audience includes cost per response, targeting criteria, and estimated fielding times.

No parameters required.

get_audience

Get detailed information about a specific audience segment including targeting criteria, cost, and fielding time estimates.

Pricing

get_pricing_config

Get the current pricing configuration including cost per response and currency.

No parameters required.

estimate_cost

Calculate the cost to launch a survey to a specific audience. Returns a breakdown of baseCostPerComplete × targetCompletes.

Surveys

list_surveys

List surveys with optional filtering by status and pagination.

get_survey

Get full details of a specific survey including the complete JSON definition, status, and metadata.

create_survey

Create a new survey draft. The survey will be created in draft status.

Launch

launch_survey

Launch a survey to collect responses. This is a two-step process to prevent accidental charges.

# Step 1: Get estimate and confirmation token
launch_survey(surveyId, audienceId: "genpop", targetCompletes: 100)
→ { estimatedCost: 100.00, confirmToken: "abc123...", expiresAt: "..." }

# Show cost to user, get explicit confirmation

# Step 2: Confirm launch (charges payment, starts fielding)
launch_survey(surveyId, confirmToken: "abc123...")
→ { success: true, workflowId: "launch-...", amountCharged: 100.00 }

get_survey_status

Get real-time fielding status including completion count, progress percentage, and estimated completion time. Results are cached for 30 seconds.

Responses

get_responses

Export survey response data with pagination. Returns individual responses including answer data, metadata, and completion status. Only returns responses from published (launched) surveys.

Resources

MCP resources provide read-only data that your AI agent can access as context.

Prompts

MCP prompts are reusable templates that guide AI agents through multi-step workflows.

design_survey

Guides an AI agent through survey creation best practices for the Chorus Research platform. Produces a valid SurveyJS JSON definition.

launch_checklist

Pre-launch validation checklist. Guides an AI agent through verifying a survey is ready to launch, estimating costs, and confirming with the user before charging.

Quick Start

Here's a typical workflow showing how an AI agent uses the MCP server from start to finish.

1. Configure your client

Add the configuration JSON for your MCP client and restart it. Verify the server connects by asking your agent to list audiences.

2. Add a payment method

Launching a survey requires a credit card on file. Add one at app.chorusresearch.io/payment-methods in the Chorus Research app.

3. Explore audiences

You: "What audiences are available?"

Agent calls: list_audiences()
Agent: "There's one audience available — General Population (US adults 18+)
       at $1.00 per response. Supports 5-5000 completes ($5 minimum)."

4. Create a survey

You: "Create a customer satisfaction survey with 5 questions"

Agent calls: create_survey(name: "Customer Satisfaction", survey: {...}, targetCompletes: 100)
Agent: "Done! Survey created in draft status. ID: 550e8400-..."

5. Estimate cost

You: "How much would 200 responses cost?"

Agent calls: estimate_cost(audienceId: "genpop", targetCompletes: 200)
Agent: "200 responses × $1.00 each = $200.00 USD total."

6. Launch (two-step)

You: "Launch it"

Agent calls: launch_survey(surveyId: "550e8400-...", audienceId: "genpop", targetCompletes: 200)
Agent: "The estimated cost is $200.00 USD. This will charge your account.
       Shall I proceed?"

You: "Yes, go ahead"

Agent calls: launch_survey(surveyId: "550e8400-...", confirmToken: "eyJhb...")
Agent: "Survey launched! Workflow is now fielding 200 responses."

7. Monitor and export

You: "How's the survey doing?"

Agent calls: get_survey_status(surveyId: "550e8400-...")
Agent: "45 of 200 responses collected (22.5%). Estimated completion: tomorrow."

You: "Export what we have so far"

Agent calls: get_responses(surveyId: "550e8400-...")
Agent: "Here are the 45 completed responses: [data summary]"

Troubleshooting

Need More Help?

• REST API Reference — full HTTP endpoint documentation
• User Guide — getting started with Chorus Research
• Contact Support — reach out for help