Simulated focus groups
as agent-callable tools.

WHAT IS MCP

The protocol Claude already speaks

Model Context Protocol is Anthropic's open standard for connecting AI agents to external services. Claude Desktop, Cursor, Cline, Zed, and a growing list of agent frameworks (LangGraph, CrewAI, AutoGPT, Devin) speak it natively. Drop an MCP server into the host's config and its tools show up in the model's tool picker — no glue code, no per-app SDK.

CrowdOS speaks it two ways: a hosted endpoint the API serves directly, and a pip-installable stdio server for desktop hosts. Both expose the same ten tools and handle request shaping, response trimming, and error sanitization.

CONNECT

Hosted: add a URL, nothing to install

The API serves the MCP endpoint itself, so it's always in sync with the platform — no package to update. Add it 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 API key.

INSTALL

Self-hosted: one pip, one config block

Then mint an API key at /account/api-keys (included with Pro and Max plans) and paste this into your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "crowdos": {
      "command": "crowdos-mcp",
      "env": {
        "CROWDOS_API_KEY": "crowd_..."
      }
    }
  }
}

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.

TOOLS

Ten tools, agent-shaped

preview_costis the one most agents underuse — call it before any sim with population > 100 to see the cents and seconds estimate, then decide whether the budget allows. Free to call.

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: 400

The agent picks preview_cost because the population is non-trivial, sees that $4.00 is affordable, then commits to run_focus_group. The trimmed envelope (sentiment summary + 5 representative quotes + billing) fits in context; if the agent needs every agent's reasoning, get_simulation pulls the full payload.

COST

Included with Pro and Max

API + MCP access comes with a Pro or Max subscription. Every plan includes monthly wallet credit that studies draw down at the same per-respondent rates as the web app — a small focus group costs about $0.20.

Pro runs panels up to 750 respondents at 30 req/min; Max raises both, plus a larger monthly token quota. Pricing →

Every run_focus_group / run_debate response includes a billing.actual_cents field so the agent can keep its own running total.

FRAMEWORKS

Or call the REST API directly

Not on an MCP host? The same tools are available as plain REST. API reference → LangGraph and CrewAI have community MCP-bridge packages that let you mount our server into a framework agent without running an MCP host.