crowdos-mcp 0.1.0__tar.gz

crowdos_mcp-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# Dependencies
+node_modules
+.pnp
+.pnp.js
+
+# Local env files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Testing
+coverage
+
+# Turbo
+.turbo
+
+# Vercel
+.vercel
+
+# Build Outputs
+.next/
+out/
+build
+dist
+
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Python
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# Misc
+.DS_Store
+*.pem
+.claude/
+
+# ANES raw microdata — research-use license prohibits redistribution.
+# The ingestion script reads these files locally; only derived,
+# anonymized JSONL lands in benchmark_results/interview_seeds_pool.jsonl
+# (which IS committed). See scripts/ingest_anes.py.
+anes_*_raw/
+anes_2020_raw/
+*.dta
+anes_timeseries_*.csv
+anes_timeseries_*.pdf

crowdos_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: crowdos-mcp
+Version: 0.1.0
+Summary: Model Context Protocol server for CrowdOS — synthetic focus groups as agent-callable tools.
+Project-URL: Homepage, https://crowdos.ai
+Project-URL: Documentation, https://crowdos.ai/developers
+Project-URL: Repository, https://github.com/bjnagent/crowd
+Project-URL: Issues, https://github.com/bjnagent/crowd/issues
+Author-email: CrowdOS <support@crowdos.ai>
+License: MIT
+Keywords: ai-agents,anthropic,claude,crowdos,focus-group,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# CrowdOS MCP Server
+
+Synthetic focus groups as agent-callable tools. Exposes the
+[CrowdOS](https://crowdos.ai) developer API as
+[Model Context Protocol](https://modelcontextprotocol.io) tools so AI
+agents (Claude Desktop, Cursor, Cline, LangGraph, CrewAI, AutoGPT,
+Devin, etc.) can run synthetic public-opinion research with a single
+tool call.
+
+## What this gives you
+
+Your agent can now do things like:
+
+```
+> Run a focus group on whether companies should mandate 4-day weeks.
+   Use 200 agents from the us_general_population preset.
+
+[tool: run_focus_group]
+{
+  "id": "ad4b3736-...",
+  "sentiment_summary": {
+    "support_pct": 71.5, "oppose_pct": 18.0, "mixed_pct": 10.5
+  },
+  "sample_responses": [
+    {"agent_name": "Maria Chen", "stance": "supports", ... },
+    ...
+  ]
+}
+```
+
+## Installation
+
+```bash
+pip install crowdos-mcp
+```
+
+Then mint a free sandbox API key at <https://crowdos.ai/developers> —
+no credit card required for the free tier (50 agents per study,
+5 req/min).
+
+## Configure for Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "crowdos": {
+      "command": "crowdos-mcp",
+      "env": {
+        "CROWDOS_API_KEY": "crowd_..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The CrowdOS tools should appear in the
+slash-command picker.
+
+## Configure for Cursor
+
+Settings → MCP Servers → Add. Same env block as above; command =
+`crowdos-mcp`.
+
+## Configure for Cline (VS Code)
+
+Settings → Cline → MCP Servers → Edit JSON:
+
+```json
+{
+  "mcpServers": {
+    "crowdos": {
+      "command": "crowdos-mcp",
+      "env": { "CROWDOS_API_KEY": "crowd_..." }
+    }
+  }
+}
+```
+
+## Tools exposed
+
+| Tool | What it does | Auth |
+|---|---|---|
+| `run_focus_group` | Synthetic poll on a topic, returns sentiment + quotes | required |
+| `run_debate` | Multi-round synthetic debate, returns convergence | required |
+| `list_demographic_presets` | Discover available audience templates | required |
+| `get_simulation` | Fetch full results of a previously-run study | required |
+| `crowd_sample` | Browse the public CrowdOS crowd (sanitized) | none |
+
+`run_focus_group` and `run_debate` block 5–120s depending on
+population size — that's a real synthetic-research call running
+behind the scenes, not a cached response. The MCP server returns a
+trimmed envelope (sentiment summary + first 5 representative quotes
++ billing breakdown). Use `get_simulation` to pull the full payload
+when you need every agent's full reasoning.
+
+## Configuration
+
+| Env var | Default | Required |
+|---|---|---|
+| `CROWDOS_API_KEY` | — | yes (except `crowd_sample`) |
+| `CROWDOS_API_BASE_URL` | `https://api.crowdos.ai` | no |
+
+## Cost
+
+CrowdOS uses a metered wallet. The MCP server returns the actual
+debit on every successful call inside `billing.actual_cents`. Free
+tier ships with $5 of credit; top up at <https://crowdos.ai/account/billing>
+once it runs out.
+
+Free-tier monthly quota is 120k tokens (~3 large studies). Pro tier
+removes the cap.
+
+## Programmatic use (without an MCP host)
+
+The server is also a regular Python module:
+
+```bash
+python -m crowdos_mcp
+# stdio MCP server, waits for messages on stdin
+```
+
+Or import and embed:
+
+```python
+from crowdos_mcp.server import build_server
+server = build_server()
+# server is a configured mcp.server.Server instance
+```
+
+## Versioning
+
+Follows semver. The MCP tool surface (tool names, input schemas) is
+stable; additive changes (new tools, new optional fields) ship as
+minor versions. Removing or renaming a tool is a major version.
+
+## License
+
+MIT.
+
+## Issues / questions
+
+<https://github.com/bjnagent/crowd/issues>

crowdos_mcp-0.1.0/README.md

@@ -0,0 +1,145 @@
+# CrowdOS MCP Server
+
+Synthetic focus groups as agent-callable tools. Exposes the
+[CrowdOS](https://crowdos.ai) developer API as
+[Model Context Protocol](https://modelcontextprotocol.io) tools so AI
+agents (Claude Desktop, Cursor, Cline, LangGraph, CrewAI, AutoGPT,
+Devin, etc.) can run synthetic public-opinion research with a single
+tool call.
+
+## What this gives you
+
+Your agent can now do things like:
+
+```
+> Run a focus group on whether companies should mandate 4-day weeks.
+   Use 200 agents from the us_general_population preset.
+
+[tool: run_focus_group]
+{
+  "id": "ad4b3736-...",
+  "sentiment_summary": {
+    "support_pct": 71.5, "oppose_pct": 18.0, "mixed_pct": 10.5
+  },
+  "sample_responses": [
+    {"agent_name": "Maria Chen", "stance": "supports", ... },
+    ...
+  ]
+}
+```
+
+## Installation
+
+```bash
+pip install crowdos-mcp
+```
+
+Then mint a free sandbox API key at <https://crowdos.ai/developers> —
+no credit card required for the free tier (50 agents per study,
+5 req/min).
+
+## Configure for Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "crowdos": {
+      "command": "crowdos-mcp",
+      "env": {
+        "CROWDOS_API_KEY": "crowd_..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The CrowdOS tools should appear in the
+slash-command picker.
+
+## Configure for Cursor
+
+Settings → MCP Servers → Add. Same env block as above; command =
+`crowdos-mcp`.
+
+## Configure for Cline (VS Code)
+
+Settings → Cline → MCP Servers → Edit JSON:
+
+```json
+{
+  "mcpServers": {
+    "crowdos": {
+      "command": "crowdos-mcp",
+      "env": { "CROWDOS_API_KEY": "crowd_..." }
+    }
+  }
+}
+```
+
+## Tools exposed
+
+| Tool | What it does | Auth |
+|---|---|---|
+| `run_focus_group` | Synthetic poll on a topic, returns sentiment + quotes | required |
+| `run_debate` | Multi-round synthetic debate, returns convergence | required |
+| `list_demographic_presets` | Discover available audience templates | required |
+| `get_simulation` | Fetch full results of a previously-run study | required |
+| `crowd_sample` | Browse the public CrowdOS crowd (sanitized) | none |
+
+`run_focus_group` and `run_debate` block 5–120s depending on
+population size — that's a real synthetic-research call running
+behind the scenes, not a cached response. The MCP server returns a
+trimmed envelope (sentiment summary + first 5 representative quotes
++ billing breakdown). Use `get_simulation` to pull the full payload
+when you need every agent's full reasoning.
+
+## Configuration
+
+| Env var | Default | Required |
+|---|---|---|
+| `CROWDOS_API_KEY` | — | yes (except `crowd_sample`) |
+| `CROWDOS_API_BASE_URL` | `https://api.crowdos.ai` | no |
+
+## Cost
+
+CrowdOS uses a metered wallet. The MCP server returns the actual
+debit on every successful call inside `billing.actual_cents`. Free
+tier ships with $5 of credit; top up at <https://crowdos.ai/account/billing>
+once it runs out.
+
+Free-tier monthly quota is 120k tokens (~3 large studies). Pro tier
+removes the cap.
+
+## Programmatic use (without an MCP host)
+
+The server is also a regular Python module:
+
+```bash
+python -m crowdos_mcp
+# stdio MCP server, waits for messages on stdin
+```
+
+Or import and embed:
+
+```python
+from crowdos_mcp.server import build_server
+server = build_server()
+# server is a configured mcp.server.Server instance
+```
+
+## Versioning
+
+Follows semver. The MCP tool surface (tool names, input schemas) is
+stable; additive changes (new tools, new optional fields) ship as
+minor versions. Removing or renaming a tool is a major version.
+
+## License
+
+MIT.
+
+## Issues / questions
+
+<https://github.com/bjnagent/crowd/issues>

crowdos_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "crowdos-mcp"
+version = "0.1.0"
+description = "Model Context Protocol server for CrowdOS — synthetic focus groups as agent-callable tools."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "CrowdOS", email = "support@crowdos.ai" },
+]
+keywords = ["mcp", "crowdos", "ai-agents", "focus-group", "claude", "anthropic"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://crowdos.ai"
+Documentation = "https://crowdos.ai/developers"
+Repository = "https://github.com/bjnagent/crowd"
+Issues = "https://github.com/bjnagent/crowd/issues"
+
+[project.scripts]
+crowdos-mcp = "crowdos_mcp.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/crowdos_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/",
+    "README.md",
+    "pyproject.toml",
+]

crowdos_mcp-0.1.0/src/crowdos_mcp/__init__.py

@@ -0,0 +1,8 @@
+"""CrowdOS MCP server — synthetic focus groups as agent-callable tools.
+
+Exposes the CrowdOS REST API as MCP tools so AI agents (Claude Desktop,
+Cursor, Cline, LangGraph, CrewAI, etc.) can run synthetic focus groups,
+debates, and crowd lookups via tool calls.
+"""
+
+__version__ = "0.1.0"

crowdos_mcp-0.1.0/src/crowdos_mcp/__main__.py

@@ -0,0 +1,19 @@
+"""Entrypoint: ``python -m crowdos_mcp`` or ``crowdos-mcp``.
+
+Reads CROWDOS_API_KEY from the environment and runs the MCP server
+on stdio. Hosts that launch MCP servers (Claude Desktop, Cursor,
+Cline) handle stdio routing.
+"""
+from __future__ import annotations
+
+
+def main() -> None:
+    # Imported here so `import crowdos_mcp` doesn't drag in the mcp
+    # SDK + httpx unless we're actually running the server.
+    from crowdos_mcp.server import run
+
+    run()
+
+
+if __name__ == "__main__":
+    main()

crowdos_mcp-0.1.0/src/crowdos_mcp/server.py

@@ -0,0 +1,409 @@
+"""CrowdOS MCP server.
+
+Exposes the CrowdOS developer REST API as MCP tools. Stdio transport;
+hosts that launch MCP servers (Claude Desktop, Cursor, Cline) wire
+stdio to the model. Tools:
+
+  - run_focus_group       : sentiment / voting study (sync, returns full results)
+  - run_debate            : multi-round debate study (sync)
+  - list_demographic_presets : discover available audiences
+  - get_simulation        : fetch results of a previously-run study
+  - crowd_sample          : public, unauth'd crowd browse (no API key needed)
+
+Configuration via env vars:
+  CROWDOS_API_KEY      — required for run_focus_group, run_debate,
+                          get_simulation. Get one at /developer.
+  CROWDOS_API_BASE_URL — defaults to https://api.crowdos.ai
+
+The server NEVER returns the customer's API key in any response. All
+errors are sanitized to {error_type, message} so an agent's response
+log can be safely stored.
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Optional
+
+import httpx
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+
+DEFAULT_API_BASE_URL = "https://api.crowdos.ai"
+# Sync sims take 5–120s for typical population sizes. We cap at 5 min
+# so a stuck job doesn't hang the agent's tool-calling turn forever.
+DEFAULT_TIMEOUT_S = 300.0
+
+
+# ── HTTP client helpers ─────────────────────────────────────────────
+
+
+def _api_base_url() -> str:
+    return os.environ.get("CROWDOS_API_BASE_URL", DEFAULT_API_BASE_URL).rstrip("/")
+
+
+def _api_key() -> Optional[str]:
+    """Return the configured CrowdOS API key or None.
+
+    Tools that require auth call _require_api_key() to convert None
+    into a clear error rather than leaking through to a 401 from the
+    server with an unhelpful message.
+    """
+    key = os.environ.get("CROWDOS_API_KEY", "").strip()
+    return key or None
+
+
+def _require_api_key() -> str:
+    key = _api_key()
+    if not key:
+        raise ValueError(
+            "CROWDOS_API_KEY environment variable is not set. "
+            "Get a free sandbox key at https://crowdos.ai/developers "
+            "and configure it in your MCP server's env block."
+        )
+    return key
+
+
+async def _post(path: str, body: dict, *, auth: bool = True) -> dict:
+    headers = {"Content-Type": "application/json"}
+    if auth:
+        headers["Authorization"] = f"Bearer {_require_api_key()}"
+    url = f"{_api_base_url()}{path}"
+    async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT_S) as client:
+        resp = await client.post(url, json=body, headers=headers)
+    return _parse_response(resp)
+
+
+async def _get(path: str, *, auth: bool = True) -> dict:
+    headers: dict[str, str] = {}
+    if auth:
+        headers["Authorization"] = f"Bearer {_require_api_key()}"
+    url = f"{_api_base_url()}{path}"
+    async with httpx.AsyncClient(timeout=60.0) as client:
+        resp = await client.get(url, headers=headers)
+    return _parse_response(resp)
+
+
+def _parse_response(resp: httpx.Response) -> dict:
+    """Convert an HTTP response into a dict, raising a clean ValueError
+    on non-2xx responses. The error message is the API's structured
+    detail when present, the body otherwise — never includes headers
+    that might leak the API key."""
+    if 200 <= resp.status_code < 300:
+        try:
+            return resp.json()
+        except Exception:
+            return {"raw": resp.text[:1000]}
+    # Try to surface the API's structured error detail.
+    try:
+        body = resp.json()
+        detail = body.get("detail") if isinstance(body, dict) else body
+    except Exception:
+        detail = resp.text[:500]
+    raise ValueError(f"CrowdOS API returned {resp.status_code}: {detail}")
+
+
+# ── Result trimming ─────────────────────────────────────────────────
+# Sim results can be 100KB–5MB on a 500-agent run. The full payload
+# blows past most agents' context windows. The MCP server returns a
+# trimmed envelope by default (sentiment summary + top quotes); the
+# agent can ask for full results via get_simulation if needed.
+
+
+def _trim_sim_result(result: dict) -> dict:
+    """Return a compact, agent-friendly subset of a sim result."""
+    if not isinstance(result, dict):
+        return {"raw": result}
+    out: dict[str, Any] = {
+        "id": result.get("id"),
+        "status": result.get("status"),
+        "topic": result.get("topic"),
+        "demographic_preset": result.get("demographic_preset"),
+        "population_size": result.get("population_size"),
+    }
+    inner = result.get("results") or {}
+    if isinstance(inner, dict):
+        out["sentiment_summary"] = inner.get("sentiment_summary")
+        out["billing"] = inner.get("billing")
+        # First 5 representative quotes
+        responses = inner.get("responses") or []
+        if isinstance(responses, list):
+            out["sample_responses"] = [
+                {
+                    "agent_name": r.get("agent_name"),
+                    "stance": r.get("stance"),
+                    "sentiment": r.get("sentiment"),
+                    "reasoning": (r.get("reasoning") or "")[:400],
+                }
+                for r in responses[:5]
+            ]
+            out["total_responses"] = len(responses)
+        # Debate convergence + final summary, if present
+        if "convergence" in inner:
+            out["convergence"] = inner.get("convergence")
+        if "final_summary" in inner:
+            out["final_summary"] = inner.get("final_summary")
+    return out
+
+
+# ── Tool definitions ────────────────────────────────────────────────
+
+
+TOOLS: list[Tool] = [
+    Tool(
+        name="run_focus_group",
+        description=(
+            "Run a synthetic focus group on a topic. Samples N AI agents from "
+            "a demographic preset (e.g. us_general_population, gen_z, etc.), "
+            "each with persistent Big Five personality + life context, and "
+            "returns sentiment breakdown plus representative quotes. "
+            "Synchronous — blocks 5-120s depending on population_size. Use "
+            "this when you want quick public-opinion signal on a question, "
+            "policy, product idea, or political stance."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "topic": {
+                    "type": "string",
+                    "description": "The question or stance to test, e.g. 'Should the federal minimum wage be $20/hr?'",
+                    "minLength": 1,
+                    "maxLength": 4000,
+                },
+                "population_size": {
+                    "type": "integer",
+                    "description": "Number of agents to poll. Free tier max 50; pro 750; enterprise 2000.",
+                    "minimum": 5,
+                    "maximum": 2000,
+                    "default": 50,
+                },
+                "demographic_preset": {
+                    "type": "string",
+                    "description": (
+                        "Audience preset. Use list_demographic_presets to see all "
+                        "options. Default: us_general_population."
+                    ),
+                    "default": "us_general_population",
+                },
+                "stance_statement": {
+                    "type": "string",
+                    "description": (
+                        "Optional declarative the agents take a position FOR or "
+                        "AGAINST. Improves clarity on comparison questions."
+                    ),
+                },
+                "language": {
+                    "type": "string",
+                    "description": "ISO language code for agent responses. Default: en.",
+                    "default": "en",
+                },
+            },
+            "required": ["topic"],
+        },
+    ),
+    Tool(
+        name="run_debate",
+        description=(
+            "Run a multi-round synthetic debate. N agents discuss the topic "
+            "across several rounds, updating their positions in response to "
+            "peers. Returns final convergence (or lack of), per-round "
+            "position shifts, and a synthesis. Use this when you want to "
+            "see whether a position survives scrutiny or how disagreement "
+            "evolves, not just a snapshot poll."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "topic": {"type": "string", "minLength": 1, "maxLength": 4000},
+                "num_rounds": {
+                    "type": "integer",
+                    "description": "Debate rounds. More rounds = more convergence pressure.",
+                    "minimum": 3,
+                    "maximum": 15,
+                    "default": 5,
+                },
+                "population_size": {
+                    "type": "integer",
+                    "minimum": 5,
+                    "maximum": 2000,
+                    "default": 30,
+                },
+                "demographic_preset": {
+                    "type": "string",
+                    "default": "us_general_population",
+                },
+                "stance_statement": {"type": "string"},
+            },
+            "required": ["topic"],
+        },
+    ),
+    Tool(
+        name="list_demographic_presets",
+        description=(
+            "List all available demographic presets (audience templates). Each "
+            "preset is a calibrated mix of demographics + Big Five OCEAN "
+            "personality distributions for a country, region, or behavioral "
+            "segment. Call this first if you don't know which preset to use."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {},
+        },
+    ),
+    Tool(
+        name="get_simulation",
+        description=(
+            "Fetch the FULL results of a previously-run simulation by id. "
+            "Use when run_focus_group's trimmed response isn't enough and "
+            "you need every agent response, full reasoning text, etc."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "sim_id": {
+                    "type": "string",
+                    "description": "The id returned by run_focus_group / run_debate.",
+                },
+            },
+            "required": ["sim_id"],
+        },
+    ),
+    Tool(
+        name="crowd_sample",
+        description=(
+            "Browse the persistent CrowdOS crowd — a sample of the live "
+            "agent population, sanitized to remove internal IDs. Useful for "
+            "showing 'what kind of people are in this audience' to a user. "
+            "No API key required — this endpoint is public."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 100,
+                    "default": 20,
+                },
+            },
+        },
+    ),
+]
+
+
+# ── Tool handlers ───────────────────────────────────────────────────
+
+
+async def _handle_run_focus_group(args: dict) -> dict:
+    body = {
+        "topic": args["topic"],
+        "mode": "voting",
+        "demographic_preset": args.get("demographic_preset", "us_general_population"),
+        "population_size": int(args.get("population_size", 50)),
+        "language": args.get("language", "en"),
+    }
+    if args.get("stance_statement"):
+        body["stance_statement"] = args["stance_statement"]
+    result = await _post("/api/v1/developer/simulations", body)
+    return _trim_sim_result(result)
+
+
+async def _handle_run_debate(args: dict) -> dict:
+    body = {
+        "topic": args["topic"],
+        "mode": "debate",
+        "demographic_preset": args.get("demographic_preset", "us_general_population"),
+        "population_size": int(args.get("population_size", 30)),
+        "num_rounds": int(args.get("num_rounds", 5)),
+    }
+    if args.get("stance_statement"):
+        body["stance_statement"] = args["stance_statement"]
+    result = await _post("/api/v1/developer/simulations", body)
+    return _trim_sim_result(result)
+
+
+async def _handle_list_demographic_presets(args: dict) -> dict:
+    return await _get("/api/v1/developer/presets")
+
+
+async def _handle_get_simulation(args: dict) -> dict:
+    sim_id = args["sim_id"]
+    return await _get(f"/api/v1/developer/simulations/{sim_id}")
+
+
+async def _handle_crowd_sample(args: dict) -> dict:
+    limit = int(args.get("limit", 20))
+    return await _get(f"/api/v1/crowd/sample?limit={limit}", auth=False)
+
+
+_HANDLERS = {
+    "run_focus_group": _handle_run_focus_group,
+    "run_debate": _handle_run_debate,
+    "list_demographic_presets": _handle_list_demographic_presets,
+    "get_simulation": _handle_get_simulation,
+    "crowd_sample": _handle_crowd_sample,
+}
+
+
+# ── Server wiring ───────────────────────────────────────────────────
+
+
+def build_server() -> Server:
+    """Build and return a configured MCP Server. Exposed for tests."""
+    server: Server = Server("crowdos-mcp")
+
+    @server.list_tools()
+    async def list_tools() -> list[Tool]:
+        return TOOLS
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+        handler = _HANDLERS.get(name)
+        if handler is None:
+            return [TextContent(type="text", text=json.dumps({
+                "error": "unknown_tool",
+                "tool": name,
+                "available": list(_HANDLERS.keys()),
+            }))]
+        try:
+            result = await handler(arguments or {})
+            return [TextContent(type="text", text=json.dumps(result, default=str))]
+        except ValueError as e:
+            # Expected, customer-facing errors (auth, validation, API
+            # 4xx/5xx). Surface verbatim — the message is already
+            # sanitized by _parse_response / _require_api_key.
+            return [TextContent(type="text", text=json.dumps({
+                "error": "request_failed",
+                "tool": name,
+                "message": str(e),
+            }))]
+        except Exception as e:
+            # Bug in the handler. Don't leak the stack to the agent;
+            # return the type name only.
+            return [TextContent(type="text", text=json.dumps({
+                "error": "internal_error",
+                "tool": name,
+                "type": type(e).__name__,
+            }))]
+
+    return server
+
+
+def run() -> None:
+    """Run the MCP server on stdio. Called by ``crowdos-mcp`` /
+    ``python -m crowdos_mcp``."""
+    import asyncio
+
+    server = build_server()
+
+    async def _serve() -> None:
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(
+                read_stream,
+                write_stream,
+                server.create_initialization_options(),
+            )
+
+    asyncio.run(_serve())