{
  "markdown": "# Simulatte MCP Server\n\nRun any of Simulatte's 26 SKUs from Claude, Cursor, Zed, or any MCP-compatible AI client. Get results back as structured JSON. No new UI to learn.\n\n```\nUser: \"Test this sleep coaching concept on 50 stressed parents.\"\nClaude: [calls simulatte_estimate_cost] → 150 credits (~$1.80). Approve?\nUser: \"yes\"\nClaude: [calls simulatte_run_study] → Results in 4 minutes.\n```\n\n---\n\n## Installation\n\n**One-off (no install):**\n```bash\nSIMULATTE_API_KEY=sim_live_your_key npx @simulatte-io/mcp-server\n```\n\n**Global install:**\n```bash\nnpm install -g @simulatte-io/mcp-server\nSIMULATTE_API_KEY=sim_live_your_key simulatte-mcp\n```\n\n---\n\n## Get an API key\n\n1. Go to [app.simulatte.io/settings/api-keys](https://app.simulatte.io/settings/api-keys)\n2. Create a key — starts with `sim_live_`\n3. Set it as `SIMULATTE_API_KEY` in your environment or MCP client config\n\n---\n\n## Claude Desktop setup\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"simulatte\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@simulatte-io/mcp-server\"],\n      \"env\": {\n        \"SIMULATTE_API_KEY\": \"sim_live_your_key_here\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. Simulatte tools appear automatically.\n\n---\n\n## Cursor setup\n\nEdit `~/.cursor/mcp.json` (or your project's `.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"simulatte\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@simulatte-io/mcp-server\"],\n      \"env\": {\n        \"SIMULATTE_API_KEY\": \"sim_live_your_key_here\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## Zed setup\n\nIn `~/.config/zed/settings.json`, add:\n\n```json\n{\n  \"context_servers\": {\n    \"simulatte\": {\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"-y\", \"@simulatte-io/mcp-server\"],\n        \"env\": {\n          \"SIMULATTE_API_KEY\": \"sim_live_your_key_here\"\n        }\n      }\n    }\n  }\n}\n```\n\n---\n\n## Available tools\n\n| Tool | What it does |\n|------|-------------|\n| `simulatte_run_study` | Run any of 26 research SKUs — concept testing, pricing, messaging, B2B committee, and more |\n| `simulatte_get_results` | Retrieve full structured results for a completed study |\n| `simulatte_ask_insights` | Ask a natural-language question across your entire study history |\n| `simulatte_list_pools` | List all synthetic persona pools in your workspace |\n| `simulatte_create_pool` | Create a new persona pool with custom demographic/psychographic specs |\n| `simulatte_depth_interview` | Run a multi-turn simulated depth interview with a synthetic persona |\n| `simulatte_estimate_cost` | Get a credit + USD cost estimate before running a study (local — no API call) |\n\n### SKUs supported by `simulatte_run_study`\n\nconcept-viability · claim-credibility · brand-identity-test · message-resonance · price-sensitivity · feature-priority · ad-copy · b2b-committee · conjoint · iris-pulse · card-sort · open-end · ab-backlog · polarization-stress-test · name-test · founder-positioning · ad-concept-resonance · depth-interview · custom-study · iat · counterfactual-positioning · personalization-sensitivity · regulated-claim-preflight · volume-forecast · brand-tracker · creative-audit\n\n---\n\n## Example prompts\n\n**Concept test:**\n> \"I have a new sleep coaching app concept. Test it on 50 stressed parent personas and tell me if it'll land.\"\n\n**Pricing sensitivity:**\n> \"Run a price sensitivity study on my premium plan ($99/mo) against 100 millennial professionals. Use pool_abc123.\"\n\n**Cross-study synthesis:**\n> \"What are the most common objections across all of our B2B studies this quarter?\"\n\n**Depth interview:**\n> \"Conduct a depth interview with a skeptical 35-year-old UK parent about our onboarding flow. 15 turns.\"\n\n---\n\n## Authentication\n\n### Preferred: per-customer API key\n\nSend your `sim_live_*` key in either of these headers — both are accepted:\n\n```\nx-api-key: sim_live_your_key_here\n# or\nAuthorization: Bearer sim_live_your_key_here\n```\n\n### Deprecated: shared platform key\n\nThe shared key `forge-prod-2026` (used in internal integrations before v0.4) is\ndeprecated and **will be removed at v0.5**. If your integration sends\n`x-api-key: forge-prod-2026`, migrate to a `sim_live_*` per-customer key now.\nThe worker logs a deprecation warning on every request that uses the shared key.\n\n---\n\n## Response headers\n\nEvery successful `/v1/forge/*` and `/v1/iris/*` response includes these headers:\n\n| Header | Description |\n|--------|-------------|\n| `X-Simulatte-Credits-Used` | Credits charged for this request |\n| `X-Simulatte-Credits-Remaining` | Workspace credit balance after this charge |\n| `X-Simulatte-Spend-Warning` | Present only when your key has consumed ≥ 80% of its spend cap. Value: `\"85%-of-cap-consumed\"` (percentage varies). |\n\n### Sample curl showing all headers\n\n```bash\ncurl -X POST https://forge-worker-production.up.railway.app/v1/forge/concept-viability \\\n  -H \"x-api-key: sim_live_your_key\" \\\n  -H \"x-workspace-id: your-workspace-uuid\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"concept\":\"A sleep app for stressed parents\",\"population_id\":\"default\",\"sample_size\":20}' \\\n  -i\n```\n\nExpected response headers (2xx):\n```\nHTTP/2 201\nx-simulatte-credits-used: 28\nx-simulatte-credits-remaining: 472\n```\n\nIf your key is at 85% of its spend cap:\n```\nx-simulatte-spend-warning: 85%-of-cap-consumed\n```\n\n---\n\n## Error reference\n\n| Status | `error` field | Meaning |\n|--------|--------------|---------|\n| `401` | `invalid_api_key` | Key not found, revoked, or expired |\n| `401` | (message) | Bearer JWT invalid or expired |\n| `402` | `key_spend_cap_exceeded` | Key has a spend cap and this request would exceed it. Body: `{\"error\":\"key_spend_cap_exceeded\",\"cap\":500,\"used\":498,\"would_charge\":10}` |\n| `429` | `rate_limited` | 60 req/min or 1000 req/hr limit hit. Check `Retry-After` header |\n| `503` | `database_unavailable` | Worker DB not reachable — retry in 30s |\n\n### Sample error bodies\n\n**402 — spend cap exceeded:**\n```json\n{\n  \"detail\": {\n    \"error\": \"key_spend_cap_exceeded\",\n    \"cap\": 500,\n    \"used\": 498,\n    \"would_charge\": 10\n  }\n}\n```\n\n**429 — rate limited:**\n```json\n{\n  \"detail\": {\n    \"error\": \"rate_limited\",\n    \"limit\": \"60/min\",\n    \"retry_after_seconds\": 42\n  }\n}\n```\n`Retry-After: 42` header is also present.\n\n---\n\n## Rate limits and quotas\n\nRate limits and credit caps are enforced per API key:\n\n| Default limit | Value |\n|---------------|-------|\n| Per-minute | 60 req/min |\n| Per-hour | 1,000 req/hr |\n\nSpend caps are optional, set per-key by workspace admins. A key with no spend\ncap has unlimited spend (bounded only by workspace credit balance).\n\nSee [app.simulatte.io/settings/billing](https://app.simulatte.io/settings/billing) for your current usage.\n\n---\n\n## Troubleshooting\n\n**\"Missing SIMULATTE_API_KEY\"** — Make sure the `env` block in your MCP config contains your key. The key must start with `sim_live_`.\n\n**Tool not appearing in Claude Desktop** — Restart Claude Desktop after editing `claude_desktop_config.json`. Check the MCP logs at `~/Library/Logs/Claude/mcp*.log`.\n\n**`simulatte_get_results` returns `status: \"running\"`** — Studies take 2–8 minutes. Poll again in 30 seconds, or ask Claude to wait and retry.\n\n**401 Unauthorized** — Your API key may be revoked or incorrect. Generate a new one at [app.simulatte.io/settings/api-keys](https://app.simulatte.io/settings/api-keys).\n\n**429 Too Many Requests** — You've hit the rate limit for your tier. Upgrade at [app.simulatte.io/settings/billing](https://app.simulatte.io/settings/billing).\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/Iqbalahmed7/simulatte-mcp-server\ncd simulatte-mcp-server\nnpm install\nnpm run build    # compiles TypeScript → dist/\nnpm test         # runs vitest test suite\nnpm run dev      # runs directly via tsx (no build step)\n```\n\n---\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 7809,
  "sha": "320b9759b30c2bc4477934dac818a210174997fda88eb0badfde5442d86ee49a",
  "repo_slug": "iqbalahmed7/simulatte-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_iqbalahmed7_simulatte_d1a9ebd6/readme"
}