Synthetic 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.

Our MCP server wraps the CrowdOS REST API. Customer authenticates with a regular API key in the host's env block; the server handles JSON-RPC, request shaping, response trimming, and error sanitization.

INSTALL

One pip, one config block

Then mint a free sandbox API key at /account/api-keys (no credit card) 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

Six 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=4 · ~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: 12

The agent picks preview_cost because the population is non-trivial, sees that 4¢ 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

Free to start, metered after

Sandbox keys ship with $5 of credit and a 50-agent cap per study (5 req/min). That's enough for ~40 small focus groups before the wallet runs out. No card required.

Pro tier removes the agent cap (up to 750/study), bumps the rate limit to 30 req/min, and increases the 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.