Simulatte

Simulatte MCP Server

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

User: "Test this sleep coaching concept on 50 stressed parents."

Claude: [calls simulatte_estimate_cost] → 150 credits (~$1.80). Approve? User: "yes" Claude: [calls simulatte_run_study] → Results in 4 minutes.

Installation

One-off (no install):

SIMULATTE_API_KEY=sim_live_your_key npx @simulatte-io/mcp-server

Global install:

npm install -g @simulatte-io/mcp-server

SIMULATTE_API_KEY=sim_live_your_key simulatte-mcp

Get an API key

1. Go to app.simulatte.io/settings/api-keys
2. Create a key — starts with sim_live_
3. Set it as SIMULATTE_API_KEY in your environment or MCP client config

Claude Desktop setup

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{

"mcpServers": { "simulatte": { "command": "npx", "args": ["-y", "@simulatte-io/mcp-server"], "env": { "SIMULATTE_API_KEY": "sim_live_your_key_here" } } } }

Restart Claude Desktop. Simulatte tools appear automatically.

Cursor setup

Edit ~/.cursor/mcp.json (or your project's .cursor/mcp.json):

{

"mcpServers": { "simulatte": { "command": "npx", "args": ["-y", "@simulatte-io/mcp-server"], "env": { "SIMULATTE_API_KEY": "sim_live_your_key_here" } } } }

Zed setup

In ~/.config/zed/settings.json, add:

{

"context_servers": { "simulatte": { "command": { "path": "npx", "args": ["-y", "@simulatte-io/mcp-server"], "env": { "SIMULATTE_API_KEY": "sim_live_your_key_here" } } } } }

Available tools

SKUs supported by simulatte_run_study

concept-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

Example prompts

Concept test:

"I have a new sleep coaching app concept. Test it on 50 stressed parent personas and tell me if it'll land."

Pricing sensitivity:

"Run a price sensitivity study on my premium plan ($99/mo) against 100 millennial professionals. Use pool_abc123."

Cross-study synthesis:

"What are the most common objections across all of our B2B studies this quarter?"

Depth interview:

"Conduct a depth interview with a skeptical 35-year-old UK parent about our onboarding flow. 15 turns."

Authentication

Preferred: per-customer API key

Send your sim_live_* key in either of these headers — both are accepted:

x-api-key: sim_live_your_key_here

or

Authorization: Bearer sim_live_your_key_here

Deprecated: shared platform key

The shared key forge-prod-2026 (used in internal integrations before v0.4) is deprecated and will be removed at v0.5. If your integration sends x-api-key: forge-prod-2026, migrate to a sim_live_* per-customer key now. The worker logs a deprecation warning on every request that uses the shared key.

Response headers

Every successful /v1/forge/* and /v1/iris/* response includes these headers:

Sample curl showing all headers

curl -X POST https://forge-worker-production.up.railway.app/v1/forge/concept-viability \

-H "x-api-key: sim_live_your_key" \ -H "x-workspace-id: your-workspace-uuid" \ -H "Content-Type: application/json" \ -d '{"concept":"A sleep app for stressed parents","population_id":"default","sample_size":20}' \ -i

Expected response headers (2xx):

HTTP/2 201

x-simulatte-credits-used: 28 x-simulatte-credits-remaining: 472

If your key is at 85% of its spend cap:

x-simulatte-spend-warning: 85%-of-cap-consumed

Error reference

Sample error bodies

402 — spend cap exceeded:

{

"detail": { "error": "key_spend_cap_exceeded", "cap": 500, "used": 498, "would_charge": 10 } }

429 — rate limited:

{

"detail": { "error": "rate_limited", "limit": "60/min", "retry_after_seconds": 42 } }

`Retry-After: 42` header is also present.

Rate limits and quotas

Rate limits and credit caps are enforced per API key:

Spend caps are optional, set per-key by workspace admins. A key with no spend cap has unlimited spend (bounded only by workspace credit balance).

See app.simulatte.io/settings/billing for your current usage.

Troubleshooting

"Missing SIMULATTE_API_KEY" — Make sure the env block in your MCP config contains your key. The key must start with sim_live_.

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.

`simulatte_get_results` returns `status: "running"` — Studies take 2–8 minutes. Poll again in 30 seconds, or ask Claude to wait and retry.

401 Unauthorized — Your API key may be revoked or incorrect. Generate a new one at app.simulatte.io/settings/api-keys.

429 Too Many Requests — You've hit the rate limit for your tier. Upgrade at app.simulatte.io/settings/billing.

Development

git clone https://github.com/Iqbalahmed7/simulatte-mcp-server

cd simulatte-mcp-server npm install npm run build # compiles TypeScript → dist/ npm test # runs vitest test suite npm run dev # runs directly via tsx (no build step)

License

MIT — see LICENSE.