Claude Desktop をセットアップ

1. API キーを取得

ダッシュボードで Org Settings → API Keys → Create に進みます。スコープは mcp:*(以下の 5 つのツールすべてをカバー)。シークレットは 1 度だけ 表示されるので、snt_live_<prefix>.<secret> 文字列の全体をコピーしてください。

OS のキーチェーン、またはローカルの .env に保存し、絶対にコミットしないでください。キーは org に紐づき(任意で 1 プロジェクトにも)、スコープ外の呼び出しは 404 を返します。ダッシュボードからいつでも失効可能で、失効後は次回呼び出しで 401 になります。

2. インストール(または省略)

MCP サーバーは npm と Homebrew で公開されています。npx を使えばインストール不要 — Claude Desktop が起動ごとに最新版を取得します。brew なら固定したローカルバイナリが手に入り、厳しいファイアウォール環境で便利です。

1// インストール不要 — npx が必要に応じて最新の @sonenta/mcp を取得します2npx -y @sonenta/mcp --version

1// 任意: グローバルに 1 度インストール — V1 ローンチに合わせて提供2brew install sonenta/tap/sonenta-mcp

3. Claude Desktop に接続

Claude Desktop の設定ファイルを開き、mcpServers の下に sonenta エントリを追加してから、アプリを終了して再起動します。

1// macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json2// Windows: %APPDATA%/Claude/claude_desktop_config.json3{4  "mcpServers": {5    "sonenta": {6      "command": "npx",7      "args": ["-y", "@sonenta/mcp"],8      "env": {9        "SONENTA_API_KEY": "snt_live_<prefix>.<secret>",10        "SONENTA_PROJECTS": "<uuid1>,<uuid2>"11      }12    }13  }14}

環境変数は計 3 つです: SONENTA_TOKEN(必須)、SONENTA_PROJECT(任意 — プロジェクトを事前指定すると、エージェントが先に list_projects を呼ぶ必要がなくなります)、SONENTA_API_BASE(任意 — デフォルトは https://api.sonenta.com。セルフホストやステージング向けに上書きしてください)。

SONENTA_PROJECTS には @sonenta/mcp ≥ 0.11.0 が必要です。それより古いリリースでは、後述の 後方互換性を参照してください。

複数プロジェクトのツール呼び出し

SONENTA_PROJECTS に複数の UUID が列挙されている場合、エージェントはどのプロジェクトを指しているか推測できないため、すべてのツール呼び出しに project_uuid を含める必要があります。単一の UUID（または旧来の SONENTA_PROJECT のみ）が設定されている場合は任意で、呼び出しはそのプロジェクトにデフォルトで設定されます。

1// list_missing_keys — project_uuid is REQUIRED when SONENTA_PROJECTS lists more than one UUID2{3  "name": "list_missing_keys",4  "arguments": {5    "project_uuid": "<uuid1>",6    "namespace": "checkout",7    "language_code": "ja"8  }9}

プロジェクトを意識してプロンプトを記述してください（「Checkout プロジェクトで、ja の欠落キーを一覧表示して」）。エージェントはプロジェクトをその UUID に解決し、ツール呼び出しに project_uuid を渡します。複数プロジェクトにまたがる曖昧なプロンプトの場合、エージェントはまず list_projects を呼び出します。

Cursor(およびその他の MCP クライアント)

JSON は同じで、ファイルの場所が違います。Cursor では .cursor/mcp.json(プロジェクト単位)または ~/.cursor/mcp.json(ユーザー単位)に置きます。他のクライアントでは、それぞれの MCP 設定ドキュメントに従ってください — mcpServers.sonenta エントリは同一です。

1// .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-scoped)2{3  "mcpServers": {4    "sonenta": {5      "command": "npx",6      "args": ["-y", "@sonenta/mcp"],7      "env": { "SONENTA_API_KEY": "snt_live_<prefix>.<secret>" }8    }9  }10}

V1 の 5 つのツール

設定後、エージェントはこれらのツールを利用できます。名前で直接呼び出すのではなく、チャットで意図を伝えればエージェントが選択します。以下の名前はキャノニカル ID で、エージェントトレースを読むときや、同じサーバー上にカスタムエージェントを構築するときに役立ちます。

プランごとの上限とクォータ

エージェントがプロジェクトを変更するときに課金され、観察するだけのときは課金されません。読み取りと一覧表示は無料で、書き込みは 1 ユニットを消費し、一括処理や AI 支援の操作は実行する作業量に応じてスケールします。

課金対象の呼び出しとは

プランごとの上限

月間クォータ、分あたりのハードな上限レート、同時 MCP セッション数、そして書き込みが許可されているかどうかです。同じ値が、すべてのレスポンスの X-MCP-Quota-Remaining ヘッダーに反映されます。

上限に達したとき

分あたりのレートを超えた場合 → 429 mcp_rate_limited と Retry-After（秒）です。月間クォータを超えた場合 → 429 mcp_quota_exceeded と、ロールオーバーに合わせた Retry-After です。Free プランでの書き込み → 403 mcp_writes_disabled です。クォータは各暦月の 1 日、UTC でリセットされます。

動作確認

1. 1 Claude Desktop を完全に再起動します(終了 → 再起動。設定は起動時に読み込まれます)。
2. 2 新しいチャットを開きます。ハンマーアイコンに sonenta と 5 つのツールが表示されるはずです。
3. 3 「List my Sonenta projects.」 と入力してください。エージェントが list_projects を呼び、ワークスペース一覧を返します。

詰まったら? Claude Desktop のログ ~/Library/Logs/Claude/mcp*.log(macOS)を確認してください。問題の 9 割は JSON のタイポか期限切れトークンです。