GUIDES · MCP
Your AI agent can run
a focus group mid-task.
An AI agent runs a focus group mid-task over the CrowdOS MCP server, on every plan, Free included. The panel is drawn from census data and disagrees with itself — not one model's opinion.
MID-TASK
The study runs inside the task
An agent that leaves its task to open a research product has stopped working. CrowdOS MCP puts the focus group in the tool picker, so the study runs inside the task the agent is already doing.
Claude, Cursor and Cline already speak Model Context Protocol. Drop the server into the host and its tools show up in the model's tool picker — no glue code, no per-app SDK.
THE SERVER
What CrowdOS MCP is
CrowdOS speaks MCP two ways. The API serves https://api.crowdos.ai/mcp as a remote server, so it stays in sync with the platform — no package to update. pip install crowdos-mcp is a desktop relay to that same hosted endpoint. Both offer the same tools for your account.
The Official MCP Registry id is ai.crowdos/mcp.
CONNECT
Connect it, then run the study
Hosted URL, or the pip relay. Then a key. Then a restart. The tools are in the picker.
01
Add the hosted endpoint
URLhttps://api.crowdos.ai/mcpAdd https://api.crowdos.ai/mcp as a remote MCP server in claude.ai (Settings → Connectors), Cursor, or any client that supports remote servers. OAuth-capable clients walk you through sign-in and consent on first connect; the grant shows up as a revocable key under /account/api-keys. Clients that send headers instead use Authorization: Bearer crowd_... with an MCP key.
02
Or install the desktop relay
BASHpip install crowdos-mcppip install crowdos-mcp. The package is a relay to the same hosted endpoint.
03
Paste the config and your key
JSON{ "mcpServers": { "crowdos": { "command": "crowdos-mcp", "env": { "CROWDOS_API_KEY": "crowd_..." } } } }Create an MCP key at /account/api-keys. Every plan can, Free included. Paste this JSON into your Claude Desktop config at ~/Library/Application Support/Claude/claude_desktop_config.json. Cursor and Cline use the same JSON shape in their MCP-server settings.
04
Restart the host
Restart the host. The CrowdOS tools appear in the agent's tool picker.
RUN A STUDY
Pick the tool by the question
These four groups are the research jobs an agent is hired for. Every plan, Free included, runs the studies the web app runs, at that plan's limits.
OPINION
What do people think?
run_focus_group is a voting study: a sentiment summary and representative quotes. run_debate is a multi-round debate: convergence and the shift from round to round. Both are on every plan. Panels follow the plan: up to 20 respondents on Free, 500 on Pro and 1,000 on Max.CHOICE
Which option wins?
compare_options is an A/B/C/D test on text options: a Borda leaderboard and a winner. It is on every plan. Plan limits: free 3, Pro 5, Max 10. rank_items is MaxDiff — a rank order with bootstrap rank intervals — and needs Pro or Max.PRICING
What would they pay?
test_pricing runs a Van Westendorp or Gabor-Granger study: price points and a revenue curve. It needs Pro or Max, because its smallest panel is larger than Free's limit.BUDGET
What will this study cost?
preview_cost estimates the cents and the seconds before the agent commits. It is free to call. Call it before any study whose population is over 100.
EVERY PLAN
Free included, at the plan's web limits
MCP works on every plan, Free included. Studies draw down your wallet at the same per-respondent rates as the web app — a small focus group costs about $0.40.
Panels follow your plan, as on the web: up to 20 respondents on Free, 500 on Pro and 1,000 on Max, with 5, 30 and 120 requests a minute and a monthly MCP spend ceiling of $5, $500 and $2,500.
Every run_focus_group and run_debate response includes billing.actual_cents, so the agent keeps its own running total. The REST API is for Enterprise accounts. MCP is the path on every plan.
IN PRACTICE
What an agent run looks like
> Run a focus group on whether companies should mandate
4-day weeks. Use 200 agents from us_general_population.
[tool: preview_cost] → estimate_cents=400 · ~33-88s
[tool: run_focus_group] → sim ad4b3736…
sentiment_summary: { positive_pct: 71.5, negative_pct: 18.0,
neutral_pct: 10.5 }
sample_responses: [ Maria Chen "It would be great for ...", ... ]
billing.actual_cents: 400This transcript is a published 200-agent run: preview_cost returns estimate_cents=400, and the study settles at billing.actual_cents 400. Free stops at 20 respondents, Pro at 500, Max at 1,000. preview_cost is free to call and shows the cents before the agent commits. The trimmed envelope — sentiment summary, representative quotes, and billing — fits in context. get_simulation pulls the full payload when the agent needs every respondent's reasoning.
A PROMPT IS NOT A PANEL
An agent role-playing a panel isn't enough
One model acting like N personas (effectively n=1).
An LLM persona is a costume for one prompt. Ours is a database row: census-grounded people with a fixed identity, an opinion history, and a standing news habit. Query that crowd. Do not ask one model to play the panel.
ACCURACY
The opinion benchmark, published
- Pew parity
- 93.3%
- Mean error
- 3.36pp
- Rank accuracy (Pearson r)
- 0.984
On the Pew opinion benchmark, the crowd's opinion distribution matches published polling at 93.3% parity, with a mean absolute error of 3.36 percentage points and a Pearson r of 0.984. That published figure is the opinion benchmark. The latest run is the first Grade A in this benchmark's history. Creative ranking and in-market ad performance are measured separately.
WHERE ELSE
The same crowd, from here
The MCP server is how an agent runs a focus group mid-task. These pages are the same crowd, stated for the job in front of you.
FAQ
Does the Free plan include MCP?
Yes. MCP works on every plan, Free included, at that plan's web limits: up to 20 respondents on Free, 500 on Pro and 1,000 on Max, with 5, 30 and 120 requests a minute and a monthly MCP spend ceiling of $5, $500 and $2,500. Studies draw down the wallet at the same per-respondent rates as the web app.
Does it work with Claude and Cursor?
Yes. Claude Desktop, Cursor and Cline speak Model Context Protocol natively. On claude.ai, add https://api.crowdos.ai/mcp under Settings → Connectors. Cursor and Cline use the same JSON shape in their MCP-server settings. Restart the host and the CrowdOS tools appear in the agent's tool picker.
Why not prompt one model to play a panel?
One model acting like N personas (effectively n=1). An LLM persona is a costume for one prompt. Ours is a database row: census-grounded people with a fixed identity, an opinion history, and a standing news habit. Query that crowd. Do not ask one model to play the panel.
How accurate is the crowd?
On the Pew opinion benchmark, the crowd's opinion distribution matches published polling at 93.3% parity, with a mean absolute error of 3.36 percentage points and a Pearson r of 0.984. That is the published opinion benchmark. The full ledger is on the benchmarks page. Creative ranking and in-market ad performance are measured separately.
How do I connect?
Add https://api.crowdos.ai/mcp as a remote MCP server, or run pip install crowdos-mcp and paste the JSON into ~/Library/Application Support/Claude/claude_desktop_config.json with an MCP key from /account/api-keys. Cursor and Cline use the same JSON shape. Restart the host. The Official MCP Registry id is ai.crowdos/mcp.