simulatte

Simulatte MCP サーバー

Claude、Cursor、Zed、またはあらゆる MCP 対応 AI クライアントから、Simulatte の 26 SKU のいずれでも実行できます。結果は構造化 JSON で取得できます。新しい UI を覚える必要はありません。

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.

---

インストール

一度だけ実行（インストール不要）：

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

グローバルインストール：

npm install -g @simulatte-io/mcp-server
SIMULATTE_API_KEY=sim_live_your_key simulatte-mcp

---

API キーを取得する

1. app.simulatte.io/settings/api-keys にアクセスします
2. キーを作成します。キーは sim_live_ で始まります
3. 環境変数または MCP クライアントの設定で、SIMULATTE_API_KEY として設定します

---

Claude Desktop の設定

~/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"
      }
    }
  }
}

Claude Desktop を再起動します。Simulatte のツールが自動的に表示されます。

---

Cursor の設定

~/.cursor/mcp.json（またはプロジェクトの .cursor/mcp.json）を編集します。

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

---

Zed の設定

~/.config/zed/settings.json に追加します。

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

---

利用可能なツール

ツール	機能
simulatte_run_study	26 種類の調査 SKU を実行します。コンセプトテスト、価格設定、メッセージング、B2B 委員会などに対応しています
simulatte_get_results	完了した調査の構造化された結果一式を取得します
simulatte_ask_insights	調査履歴全体について、自然言語で質問します
simulatte_list_pools	ワークスペース内の合成ペルソナプールをすべて一覧表示します
simulatte_create_pool	カスタムの人口統計／心理統計仕様で新しいペルソナプールを作成します
simulatte_depth_interview	合成ペルソナとの複数ターンの模擬デプスインタビューを実施します
simulatte_estimate_cost	調査の実行前にクレジットと USD の費用見積もりを取得します（ローカルで実行。API 呼び出しなし）

simulatte_run_study が対応する SKU

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

---

プロンプトの例

コンセプトテスト：

「新しい睡眠コーチングアプリのコンセプトがあります。ストレスを抱える親のペルソナ 50 人でテストして、受け入れられそうか教えてください。」

価格感度：

「プレミアムプラン（月額 $99）の価格感度調査を、ミレニアル世代の社会人 100 人を対象に実施してください。pool_abc123 を使用してください。」

複数調査の統合分析：

「今四半期の B2B 調査全体で、最もよくある反論は何ですか？」

デプスインタビュー：

「オンボーディングの流れについて、懐疑的な 35 歳の英国在住の親にデプスインタビューを実施してください。15 ターンでお願いします。」

---

認証

推奨：顧客ごとの API キー

sim_live_* キーは、次のいずれかのヘッダーに指定してください。どちらも使用できます。

x-api-key: sim_live_your_key_here
# or
Authorization: Bearer sim_live_your_key_here

非推奨：共有プラットフォームキー

共有キー forge-prod-2026（v0.4 より前の内部統合で使用）は非推奨であり、v0.5 で削除されます。統合で x-api-key: forge-prod-2026 を送信している場合は、ただちに顧客ごとの sim_live_* キーに切り替えてください。共有キーを使用するリクエストごとに、ワーカーは非推奨を示す警告をログに記録します。

---

レスポンスヘッダー

成功した /v1/forge/* および /v1/iris/* のレスポンスには、次のヘッダーが含まれます。

ヘッダー	説明
X-Simulatte-Credits-Used	このリクエストで消費されたクレジット
X-Simulatte-Credits-Remaining	この請求後のワークスペースのクレジット残高
X-Simulatte-Spend-Warning	キーの利用額が上限の 80% 以上に達した場合にのみ含まれます。値：「85%-of-cap-consumed」（割合は変動します）。

すべてのヘッダーを表示する curl の例

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

想定されるレスポンスヘッダー（2xx）：

HTTP/2 201
x-simulatte-credits-used: 28
x-simulatte-credits-remaining: 472

キーの利用額が上限の 85% に達している場合：

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

---

エラーリファレンス

ステータス	error フィールド	意味
401	invalid_api_key	キーが見つからないか、取り消されているか、有効期限が切れています
401	(メッセージ)	Bearer JWT が無効か、有効期限が切れています
402	key_spend_cap_exceeded	キーに支出上限が設定されており、このリクエストによって上限を超過します。本文：{"error":"key_spend_cap_exceeded","cap":500,"used":498,"would_charge":10}
429	rate_limited	60 req/min または 1000 req/hr の上限に達しました。Retry-After ヘッダーを確認してください
503	database_unavailable	ワーカーの DB に接続できません。30 秒後に再試行してください

エラーボディの例

402 — 支出上限を超過：

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

429 — レート制限：

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

Retry-After: 42 ヘッダーも含まれます。

---

レート制限とクォータ

レート制限とクレジット上限は、API キーごとに適用されます。

デフォルトの上限	値
1 分あたり	60 req/min
1 時間あたり	1,000 req/hr

支出上限は任意で、ワークスペース管理者がキーごとに設定します。支出上限が設定されていないキーでは、ワークスペースのクレジット残高の範囲内で支出が無制限になります。

現在の使用状況については、app.simulatte.io/settings/billing をご覧ください。

---

トラブルシューティング

「Missing SIMULATTE_API_KEY」 — MCP 設定の env ブロックにキーが含まれていることを確認してください。キーは sim_live_ で始まる必要があります。

Claude Desktop にツールが表示されない — claude_desktop_config.json を編集した後、Claude Desktop を再起動してください。MCP ログは ~/Library/Logs/Claude/mcp*.log で確認できます。

simulatte_get_results が status: "running" を返す — 研究には 2～8 分かかります。30 秒後に再度ポーリングするか、Claude に待機して再試行するよう依頼してください。

401 Unauthorized — API キーが取り消されているか、間違っている可能性があります。app.simulatte.io/settings/api-keys で新しいキーを生成してください。

429 Too Many Requests — ご利用のプランのレート制限に達しました。app.simulatte.io/settings/billing でアップグレードしてください。

---

開発

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)

---

ライセンス

MIT — LICENSE を参照してください。