How to Run Consumer Research from Claude Code (Step-by-Step)

Claude Code can talk to real people. Not simulated personas, not training data, not synthetic responses — actual consumers from a 4M+ vetted global panel who will tell you what they think about your headlines, claims, and messaging.

One line of config. Results in 2-3 hours. Studies from approximately $200.

This guide walks through setup, three real workflow examples, and the cost management features you should know about.

Setup (60 Seconds)

Use the hosted endpoint, https://mcp.userintuition.ai/mcp, with OAuth in compatible clients. For local stdio, run npx -y @userintuition-ai/mcp with USERINTUITION_API_KEY set to your ui_sk_ key. The CLI supports browser login and API-key management. Hosted OAuth does not require exchanging a user-supplied API key.

For a local stdio client that uses an MCP configuration file:

{
  "mcpServers": {
    "userintuition": {
      "command": "npx",
      "args": ["-y", "@userintuition-ai/mcp"],
      "env": {"USERINTUITION_API_KEY": "ui_sk_your_key_here"}
    }
  }
}

Keep real keys out of version control. For shell workflows:

npm install -g @userintuition-ai/mcp
userintuition-mcp login
userintuition-mcp list
userintuition-mcp list_studies

Start with a read such as list_studies to check your connection. See the current MCP setup guide for client-specific instructions and the research skills for workflow guidance.

What You Can Test?

Three research modes, each designed for a different question:

Workflow 1: Validate Headlines Before Launch

Give Claude Code the actual headline options, target audience, and decision. Ask it to explain the proposed comparison before fielding.

Create a metadata draft with create_study, then send the research brief through customize_study. Relay any planning questions to the user. Retrieve the persisted plan with get_study and obtain approval before recruitment. The user must choose panel or BYOP explicitly.

For a panel study, use launch_panel with dry_run: true to obtain the recruitment estimate. Show the country, language, cost, and timeline; launch with the same settings after approval. Each launch specifies one country. Audiences below 10% incidence require a feasibility request.

Workflow 2: Test a Product Claim

Put the exact claim in the research brief. Ask what participants think it promises, what they believe, and what would make it more credible. Use the same create/customize/review sequence as a headline study. Preserve skepticism and contradictions in the final readout.

Workflow 3: Message-Test Your Positioning

Provide the copy or concept asset and explain who it is meant for. Customize Plan handles the brief and supported assets. Review the saved guide, then approve recruitment. Ask Claude Code to connect its proposed edits to specific participant reactions in the retrieved report and interviews.

Cost Management: Always Use Dry Run First

For a panel study, use launch_panel with dry_run: true to obtain the recruitment estimate. Show the country, language, cost, and timeline; launch with the same settings after approval. Each launch specifies one country. Audiences below 10% incidence require a feasibility request.

launch_panel({"study_id":"<study-id>","target":25,"incident_rate":50,"country_code":"US","dry_run":true})

The target and incidence above are illustrative, not a claim about your audience. Use the approved values. A dry run estimates recruitment; it does not field interviews. After approval, call the same tool with the same settings and dry_run: false. Timing depends on the audience and fielding conditions.

For a BYOP study, use create_participants with 1–100 unique participant emails per batch after the saved plan and invitations are approved. Invitations send by default; set silent: true on individual participant records when invitations should not send. Source customer lists through your own authorized export or integration; MCP has no direct CRM segment-sync tools.

Pricing

The MCP connection itself has no separate fee. Research uses platform credits, with panel recruitment priced separately in the estimate. Starter credits cost $30; Professional is $2,499/month with 100 credits and $25 additional credits. Chat uses 0.5 credit, voice 1, and video 2 per interview. Three free interviews are available on signup; review recruitment charges before launching a panel study.

See current pricing and agentic research.

Five Tips for Better Agent-Driven Research

1. Be specific about what you’re testing. “Test this copy” is fine. “Test whether this copy communicates speed or reliability as the primary benefit” is better. The more specific your question, the more actionable the results.

2. Use dry_run for every new study type. Until you have a feel for costs, estimate first. It takes two seconds and prevents surprises. This is especially important when you are experimenting with different sample sizes or interview types — the difference between a 25-person chat study and a 50-person video study is significant, and dry_run makes the cost transparent before you commit.

3. Default to 25 participants for quick checks. That’s enough for clear signal on preference checks and claim reactions. Go to 50+ for high-stakes decisions like rebrands or pricing changes. The reasoning: with 25 participants in a deep AI-moderated conversation (each probing 5-7 levels deep), you generate substantially more qualitative signal than a 500-person survey checkbox. Twenty-five people explaining their reasoning in detail typically surfaces the core themes, primary objections, and minority dissent patterns that matter for product decisions.

4. Check past research before launching new studies. Ask Claude Code: “List my completed studies.” Every study compounds in the intelligence hub — you might already have the answer.

5. Don’t bury the minority view. When results come back, the 15% who disagreed are often the most useful signal. They’re the edge case that becomes a support ticket, the objection that kills a deal, the confusion that tanks your conversion rate. (This is exactly why AI agents need real consumer data — training data can’t surface these edge cases.)

What Happens Under the Hood?

Create a metadata draft with create_study, then send the research brief through customize_study. Relay any planning questions to the user. Retrieve the persisted plan with get_study and obtain approval before recruitment. The user must choose panel or BYOP explicitly.

get_study_report returns report text, references, interview count, stale status, and timestamps in JSON. Use generate_report when analysis is needed, and get_interview to verify supporting messages and recording links. Preference shares, credibility scores, and ranked themes are not guaranteed typed fields in this response.

Agents can list studies, retrieve selected study reports, and inspect supporting interviews. They can compare that retrieved evidence in their own context. Direct cross-study Intelligence Hub search is available in the dashboard; the current public API and MCP catalog do not expose Hub search, Hub sessions, or presentation generation.

Get Started

1. Sign up for free (3 interviews, no credit card)
2. Add the MCP config above
3. Ask Claude Code to run your first preference check

Your agent just became the first one in your stack that can ask real people what they think. Every study you run compounds into a searchable intelligence hub that gets smarter over time.

Related: Consumer Research API: Full Call/Response Examples | MCP for Market Research: Complete Guide | Agentic Research Platform

Server URL: https://mcp.userintuition.ai/mcp Docs: docs.userintuition.ai/integrations/mcp-server Developer Quick Start: research.userintuition.ai