@chorus-research/mcp

MCP server for the Chorus Research survey platform — create surveys, launch them to targeted audiences, and collect responses, all from your AI agent.

Built on the Model Context Protocol.

Quick Start

1. Get an API key

Sign up at chorusresearch.com and generate an API key from your dashboard.

2. Add to your MCP client

Claude Code (.mcp.json):

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

Claude Desktop (claude_desktop_config.json):

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

Tools

The server exposes 10 tools across surveys, audiences, pricing, launch, and responses.

Surveys

| Tool | Description | Key Parameters | |------|-------------|----------------| | list_surveys | List surveys with optional filtering and pagination | status?, page?, pageSize?, sort?, order? | | get_survey | Get full survey details including the JSON definition | surveyId | | create_survey | Create a new survey draft | name, survey (JSON), targetCompletes, description? |

Audiences

| Tool | Description | Key Parameters | |------|-------------|----------------| | list_audiences | List all available audience segments with costs and targeting criteria | (none) | | get_audience | Get details for a specific audience segment | audienceId |

Pricing

| Tool | Description | Key Parameters | |------|-------------|----------------| | estimate_cost | Calculate launch cost (costPerResponse x targetCompletes) | audienceId, targetCompletes, projectId? | | get_pricing_config | Get current cost-per-response and currency | (none) |

Launch (two-step)

| Tool | Description | Key Parameters | |------|-------------|----------------| | launch_survey | Launch a survey to collect responses | See below | | get_survey_status | Real-time fielding status (completes, progress %, ETA) | surveyId |

launch_survey is a two-step process to prevent accidental charges:

1. Estimate — call with surveyId, audienceId, and targetCompletes. Returns a cost estimate and a confirmToken (valid 5 minutes).
2. Confirm — call again with surveyId and the confirmToken to execute the launch and charge payment.

# Step 1: Get estimate
launch_survey(surveyId, audienceId="genpop", targetCompletes=100)
# → { step: "estimate", estimatedCost: 100, confirmToken: "tok_...", expiresAt: "..." }

# Step 2: Confirm (triggers real charges)
launch_survey(surveyId, confirmToken="tok_...")
# → { step: "confirmed", success: true, amountCharged: 100 }

Responses

| Tool | Description | Key Parameters | |------|-------------|----------------| | get_responses | Export response data with pagination | surveyId, page?, pageSize?, status?, includeDuplicates? |

Response metadata includes device info (userAgent, screenSize, timezone), geographic data (city, state, country), and provider demographics when available. Duplicates are excluded by default.

Resources

| URI | Name | Description | |-----|------|-------------| | chorus://audiences | Audience Catalog | Full catalog of audience segments with targeting, costs, and fielding times | | chorus://pricing/config | Pricing Configuration | Current cost-per-response and currency |

Prompts

| Name | Description | Arguments | |------|-------------|-----------| | design_survey | Guides survey creation with best practices | topic (required), audience?, numQuestions? | | launch_checklist | Pre-launch validation checklist with cost review | surveyId (required) |

Configuration

| Environment Variable | Description | Default | |---------------------|-------------|---------| | CHORUS_API_KEY | API key for authentication (required) | (none) | | CHORUS_API_BASE_URL | Base URL for the Chorus Research API | https://api.chorusresearch.io |

Requirements

• Node.js >= 20