CPZAI

CPZAI MCP サーバー

CPZAI 用の Model Context Protocol アダプターです。戦略、保存済みバックテスト、ブローカー口座、注文、ポートフォリオのポジション、市場データ、リスク、プロバイダー接続、中核業務のレポートに対応しています。

ホスト型エンドポイント： https://mcp.cpz-lab.com/mcp トランスポート： ステートレスな Streamable HTTP 現在のソース： バージョン 1.4.0：34 個のツール、3 つのガイドリソース、2 つのワークフロープロンプト。

この README では更新後のソースについて説明しており、本番環境へのデプロイが完了したことを示すものではありません。デプロイ済みの機能を確認するには、接続済みのクライアントで tools/list、resources/list、prompts/list を使用してください。以前のソースで登録されていたツールは 21 個です。18 個のツールや、リリース予定の 29 個のツールに関する古い記述は誤りです。

接続

CPZAI の Settings → API Keys でキーとシークレットを作成してください。カスタムヘッダーに対応したリモート MCP クライアントでは、次のように設定します。

{
  "mcpServers": {
    "cpzai": {
      "url": "https://mcp.cpz-lab.com/mcp",
      "headers": {
        "X-CPZ-Key": "YOUR_KEY",
        "X-CPZ-Secret": "YOUR_SECRET"
      }
    }
  }
}

設定形式が異なる場合は、クライアントに対応する接続設定を使用してください。OAuth 対応クライアントは、同じ MCP URL に接続し、PKCE S256 を使用してサインインできます。ディスカバリーエンドポイント：

• https://mcp.cpz-lab.com/.well-known/oauth-authorization-server
• https://mcp.cpz-lab.com/.well-known/oauth-protected-resource

OAuth アクセストークンは不透明なトークンで、このサーバーで受け付けられます。REST API に直接渡さないでください。従来の Bearer cpz_key_…SECRET 認証情報はデフォルトで無効になっています。ヘッダー認証または OAuth を使用してください。

ツールカタログ

ドメイン	ツール	目的
戦略	list_strategies	ステータス、戦略タイプ、タイトル
戦略	get_strategy	1件の戦略を読み取る
戦略	create_strategy	戦略を作成する
戦略	update_strategy	選択した戦略フィールドを更新する
オーバーレイ	list_overlays	オーバーレイ戦略と、その完全なヘッジポリシーおよび目標を一覧表示する
オーバーレイ	get_overlay_exposure	1つのオーバーレイのエクスポージャー、ヘッジのずれ、推奨注文、有効性、損益
オーバーレイ	configure_overlay	オーバーレイの役割、ポリシー、目標を一括で設定または削除する
バックテスト	get_backtest_results	保存済みのバックテスト実行を一覧表示する
バックテスト	get_backtest_result	保存済みのバックテスト実行を1件読み取る
注文	list_orders	ステータス、銘柄、売買区分、戦略ID
注文	get_order	1件のCPZ注文レコードを読み取る
注文	place_order	選択した接続済みアカウントに注文を送信する
ポートフォリオ	list_positions	アカウントID、銘柄
ポートフォリオ	sync_portfolio	接続済みブローカーのポートフォリオを同期する
アカウント	list_accounts	ブローカー、環境、取引可能かどうか
接続	list_connections	接続タイプ
接続	create_connection	プロバイダーの認証情報を暗号化して保存する
データファイル	list_data_files	名前、ステータス、ファイルタイプ
データファイル	get_data_file	アップロードされたファイルのメタデータを読み取る
市場データ	get_market_data	銘柄の現在の価格を取得する
市場データ	get_bars	過去のOHLCVバーを取得する
リスク	compute_risk	最新のリスクスナップショットを計算して保存する
リスク	list_risk_snapshots	アカウントID
リスク	get_risk_snapshot	保存済みのリスクスナップショットを1件読み取る
執行	execute_strategy	戦略コードを実行する。注文を出す場合があります
ミドルオフィス	list_deals	エンティティID、ファンド、ブック、取引ID、商品種別、ステータス
ミドルオフィス	list_lifecycle_events	エンティティID、取引ID、種別、ステータス、開始、終了
ミドルオフィス	list_cash_flows	エンティティID、取引ID、ファンド、ブック、開始、終了、未決済
ミドルオフィス	list_journal_entries	エンティティID、取引ID、開始、終了
ミドルオフィス	list_fund_periods	エンティティID、ファンド、ステータス
日常機能	list_watchlist	ウォッチリスト（最大10銘柄）
日常機能	add_to_watchlist	銘柄
日常機能	remove_from_watchlist	list_watchlist で取得したID
日常機能	export_transactions	年または開始／終了、アカウントID、銘柄、売買区分、環境、ブローカー、戦略ID
日常機能	cash_summary	ブローカー、環境、取引可能かどうか
Webhook	list_webhooks	有効かどうか
Webhook	create_webhook	イベントをHTTPSエンドポイントにサブスクライブする
Webhook	delete_webhook	Webhookのサブスクリプションを削除する
プロフィール	get_profile	認証済みプロフィールを読み取る

表内のフィルターは任意です。単一レコードを扱うツールには、対応する一覧表示ツールが返すCPZレコードUUIDが必要です。get_order が受け取るのはCPZレコードIDであり、ブローカー注文IDではありません。ファイル読み取りで返されるのはメタデータで、ファイルの内容やサンプル行はダウンロードされません。バックテストツールは保存済みの実行結果を読み取るもので、バックテストを開始するものではありません。

ページネーションとデータ

すべてのリストツールは、limit（整数、1～100）とoffset（0以上の整数、デフォルトは0）を受け取り、公開されているスキーマに応じてソートフィールドも受け取ります。デフォルトのlimitは50ですが、list_accountsは100です。ページを切り替えるときは、明示的にlimitを指定してください。RESTのcountは現在のページの件数であり、合計件数ではありません。完全なポートフォリオとして報告する前に、返される件数がlimit未満になるまでページを取得し続けてください。

{"limit":100,"offset":0}

同じリストの次のページを取得するには、{"limit":100,"offset":100}を使用してください。上流でのエラーは、最後のページが空であることを意味しません。

get_barsは、symbols、timeframe、start、end、limit（シンボルごとに1～10,000本のバー）、およびfeed（iexまたは sip。プロバイダーの権限によります）を受け取ります。サポートされている時間枠は1Min、5Min、15Min、30Min、1Hour、2Hour、4Hour、1Day、1Week、1Monthです。

ミドルオフィスのリストでは、呼び出し元がアクティブなメンバーであるエンティティブックを指定するために、任意でentity_idを使用できます。それ以外の場合は、個人ブックが使用されます。マイナー単位の小数文字列は、JavaScriptの数値に変換せず、正確な値として保持してください。

取引と副作用

アカウントを選択する前に、list_accountsを使用してenvironmentとtradableを確認してください。tradable: trueを指定すると、注文ルーティング可能なアカウントに絞り込まれます。falseまたは省略した場合は、すべてのアカウントが含まれます。アカウントの検索では、注文ルーティングよりも多くのプロバイダーが対象になります。ライブまたはペーパー取引の実行は、選択したアカウントとプラットフォームの制御に従います。

place_orderには正の数量が必要です。指値注文／逆指値指値注文にはpriceが、逆指値注文／逆指値指値注文にはstop_priceが必要です。レガシールートではこの期間のみがサポートされるため、公開されているtime_in_force: "day"のみ使用できます。サポートされる注文タイプはブローカーによって異なります。execute_strategyは取引を発注する可能性があり、シグナルのプレビューやドライランではありません。ユーザーが承認した取引にのみ、これらのツールを呼び出してください。

ツールの注釈には副作用が記載されています。実際の認可は、REST APIのキー、サブスクリプション、所有権、リソーススコープのチェックによって適用されます。レガシーのread／write／trade権限は、REST APIによってリソーススコープに展開されます。

オーバーレイ

オーバーレイとは、ヘッジポリシーに基づき、他の戦略や証券口座全体をヘッジする戦略です。3つのオーバーレイツールはいずれも、お客様自身の認証情報を使って cpz ゲートウェイを呼び出し、strategies スコープを必要とします。

list_overlays（GET /cpz/overlays）は、市場データを使わずに、各オーバーレイのポリシー全体（目的、ヘッジ比率、許容帯、ヘッジ対象商品、ベンチマーク、リバランスのトリガー、メモ）とターゲットを一度に返します。オーバーレイにポリシーがあり、かつ少なくとも1つのターゲットがある場合、configured は true になります。プラットフォームが返すオーバーレイは最大200件で、タイトル順に並びます。さらに存在する場合は truncated: true となり、結果には完全な一覧ではないことを示すメモが含まれます。

get_overlay_exposure（GET /cpz/overlay/exposure）は、1つのオーバーレイのヘッジを算出します。結果の先頭には判定が示されます。complete、hedge_ratio_status（目的に比率がない場合、またはヘッジ対象がない場合は measured、not_measured、もしくは withheld）、および hedge_ratio_reason が含まれ、その後に data としてプラットフォームのドキュメントが続きます。complete が false の場合、価格または価格履歴が不足しています。その場合、ヘッジ比率、乖離、バンド判定、推奨注文は null となり、不足しているシンボルを示す withheld ブロックが含まれます。不完全な結果に基づいて、ヘッジの規模を決めたり発注したりしないでください。推奨注文は助言です。発注するには、別途ユーザーの承認を得た place_order 呼び出しが必要です。409 は、その戦略がオーバーレイではないか、まだポリシーまたはターゲットがないことを示し、configure_overlay を案内します。

configure_overlay（PUT /cpz/overlays/{id}）は、役割、ポリシー、ターゲットを1回のトランザクションで保存し、保存した設定を返します。

• role: "overlay" にはポリシーと少なくとも1つのターゲットが必要で、両方を置き換えます。省略したポリシー項目にはデフォルト値（hedge_ratio は 1、tolerance_band は 0.1、rebalance_trigger は band、商品とメモはなし）が適用され、指定しなかったターゲットは削除されます。先に list_overlays を読み取り、設定全体を送信してください。
• role: "alpha" はポリシーとターゲットを削除します。この場合、どちらも渡さないでください。
• オーバーレイにすると、その戦略の空売りが有効になります。
• ツールはリクエストを送る前に、未知の目的、0～5の範囲外の hedge_ratio、（0, 1] の範囲外の tolerance_band、benchmark_symbol がない beta オーバーレイ、ターゲットがない場合、自分自身をターゲットにしている場合、同じターゲットが2回指定されている場合、（0, 10] の範囲外の重み、paper または live 以外の口座環境、スペルミスのあるフィールドを拒否します。所有権、口座への所属、循環参照はプラットフォームが確認し、その 400 メッセージはそのまま返されます。
• 読み戻しに失敗した場合、200 は保存済みとして報告され、list_overlays で確認するようメモが付けられます。5xx、タイムアウト、または読み取れない 200 は、保存済みとして報告されません。結果は不明なため、再度保存する前に list_overlays を確認してください。書き込みは再試行されません。

結果とエラー

ツールの応答には、読み取り可能な JSON テキストと構造化コンテンツが含まれます。ほとんどの読み取りツールは outputSchema を宣言しているため、クライアントは返された内容を検証できます。一覧ルートは {data, count}、単一レコードのルートは {data}、削除ルートは {message} を返します。他のサービスにプロキシするアクションツール（execute_strategy、sync_portfolio、compute_risk、get_market_data、get_bars）と、独自のハンドラーを持つ書き込み（place_order、create_connection、configure_overlay）は、このサーバーが応答形式を保証できないため、出力スキーマを宣言しません。エラー結果に対する出力検証はスキップされます。結果を使用する前に isError を確認してください。不正な形式の上流応答やプロバイダーの障害は、エラーのまま返されます。リクエスト ID を使うと、認証情報をログに記録せずにトレースできます。

対象となる GET 呼び出しは、上限付きタイムアウトの範囲内で、一時的な上流の障害を再試行する場合があります。書き込みは自動的に再試行されません。注文送信後にタイムアウトした場合、結果は未確認のままです。再試行する前に、既存の注文とブローカーを確認してください。公開注文ルートでは、一般的なエンドツーエンドの冪等性は保証されません。

リソースとプロンプト

種類	名前	目的
リソース	cpzai://guides/tool-usage	ツールの選択、ページネーション、機能の境界
リソース	cpzai://guides/permissions	リソースの権限と実行の境界
リソース	cpzai://guides/discovery	エンドポイント、遅延読み込み、検索の規則
プロンプト	review_portfolio	ポートフォリオのレビュー用ワークフロー。account_id は任意
プロンプト	analyze_strategy	戦略の調査。strategy_id は必須

プロンプトをリクエストすると指示が返されますが、ワークフローは実行されません。標準の MCP メソッドを使ってこれらを検出してください。/mcp/info エンドポイントはありません。

ツールの段階的な検出

完全なカタログには 34 個のツールと約 40 KB の JSON Schema が含まれており、ツールの読み込みを遅延できない場合、リクエストごとにクライアントがその全量を受け取ります。また、モデルが約 30 個を超えるツールから選択すると、ツール選択の精度も低下します。エンドポイントは 2 つあり、異なる検出方式で同じツールを提供します。

POST /mcp：完全なカタログ

tools/list はすべてのツールを返します。クライアント側で読み込みを遅延する場合に使用します。遅延させるには、ツールの定義が必要です。Claude の MCP コネクターでは、defer_loading とツール検索ツールを組み合わせ、日常的な読み取りツールは読み込んだままにします。

{
  "type": "mcp_toolset",
  "mcp_server_name": "cpzai",
  "default_config": { "defer_loading": true },
  "configs": {
    "list_accounts":  { "defer_loading": false },
    "list_positions": { "defer_loading": false },
    "place_order":    { "defer_loading": false }
  }
}

遅延された定義もリクエストごとに送信されますが、検索で検出されるまではモデルのコンテキストに含まれません。プロンプトのプレフィックスは変更されないため、キャッシュは維持されます。Claude Code は設定なしで、このエンドポイントに対して独自のツール検索を適用します。

POST /mcp/compact：サーバー側での検出

クライアントに独自の遅延機能がない場合に使用します。tools/list は 34 個ではなく 16 個のツールを返します（約 40 KB から約 18 KB へ、56％削減）。

• search_tools：自然言語またはキーワードによるクエリ。category は任意です。各検索結果には完全な入力スキーマが含まれます。ツール名、タイトル、説明、パラメーター名、パラメーターの説明が検索対象となるため、unsettled や entity_id などのフィールド名で、それを受け付けるツールを検索できます。カテゴリ：strategies、backtests、orders、positions、accounts、market-data、risk、data、webhooks、middle-office、profile。
• call_tool：input_schema に一致する引数オブジェクトを使って、検出済みのツールを名前で呼び出し、そのツールの結果を変更せずに返します。
• 状態を変更するすべてのツール（place_order、execute_strategy、create_strategy、update_strategy、create_connection、create_webhook、delete_webhook、sync_portfolio、compute_risk、configure_overlay）に加え、読み取り用のアンカーツールである list_accounts、list_positions、list_orders、get_market_data。

call_tool が振り分けるのは読み取り専用のツールのみです。クライアントは確認を、認識できるツール名に基づいて行います。そのため、注文を汎用ディスパッチャー経由で送ると、注文を検出するための確認処理から隠れてしまいます。また、すでに公開されている読み取り専用ツールは拒否し、未知の名前には推測で答えるのではなく、類似する候補を提示します。振り分け前に実際のツールスキーマに照らして引数を検証します。拒否された場合は、問題のあるパスとそのツールのスキーマが返されます。

プロトコルの改訂

両方のエンドポイントは、同じ URL で 2026-07-28 の改訂版と、2024-10-07 までのすべての旧改訂版を提供します。

• 2026-07-28 クライアントは、各リクエストを個別に送信し、initialize ハンドシェイクは行いません。メソッドを Mcp-Method ヘッダーで、ツールを Mcp-Name で指定するため、ゲートウェイは本文を解析せずにルーティングできます。プロトコルのバージョン、クライアント情報、機能は _meta に含めます。
• server/discover は、機能、指示、サポートされているバージョンを 1 回の呼び出しで返します。
• tools/list、prompts/list、resources/list、server/discover には、ttlMs と cacheScope が含まれます。tools/list は常に private です。認証情報ごとにフィルタリングされるため、共有キャッシュを使うと、あるキーのカタログが別のキーに渡されてしまいます。
• initialize ベースのクライアントは、これまでと同様に 2025-11-25、2025-06-18、またはそれ以前のバージョンをネゴシエートします。Claude Code と既存のコネクターへの影響はありません。

サーバーはどちらの方式でもステートレスです。セッションはなく、Mcp-Session-Id も使わず、リクエストごとに新しいサーバーを使用します。

スコープ対応のディスカバリー

tools/list には、呼び出し元の認証情報のスコープで許可されたツールだけが含まれます。data キーから見えるのは 39 個ではなく 13 個のツールです。取引がペーパー口座に制限された orders_paper キーからは注文関連の機能が見えますが、execute_strategy、list_accounts、ミドルオフィスは見えません。ID のみを含む OAuth トークンから見えるのは get_profile だけです。search_tools はスコープ外のツールを返さず、call_tool もスコープ外のツールを実行しません。スコープは REST API の GET /me から取得し、認証情報ごとに 60 秒間キャッシュします。参照するのは tools/list の場合のみで、呼び出し処理では参照しません。

参照に失敗した場合、または REST API のデプロイが scopes フィールドに対応していない場合は、理由をログに記録したうえでカタログ全体を提示します。不明であることは、スコープがないことと同じではありません。フィルタリングはディスカバリーのためのものであり、強制ではありません。認証情報で何にアクセスできるかを決定するのは、引き続き REST API のみです。そのため、提示されているツールでも 403 を返す場合があります。

計測された機能範囲：

エンドポイント	全スコープ	data スコープのみ
/mcp	34 個のツール、約 40 KB	10 個のツール、約 9 KB
/mcp/compact	16 個のツール、約 18 KB	6 個のツール、約 6 KB

両方のエンドポイントで、ツール名、引数、結果、ページネーションは同一です。ディスカバリーでは口座データを読み取らず、注文も行いません。

アーキテクチャ

Remote MCP client
  → POST /mcp  (full catalogue) or POST /mcp/compact (search_tools + call_tool)
  → createMcpHandler, legacy: 'stateless' (2026-07-28 and every legacy revision)
  → fresh stateless server per request
  → user's API credentials, resolved from headers or encrypted OAuth token
  → CPZ REST API /functions/v1/rest-api/v1 (overlay tools: cpz gateway /cpz)
  → existing user-scoped platform handlers

src/tools.ts、src/expanded-tools.ts、src/overlay-tools.ts は、公開する MCP スキーマを管理します。src/capabilities.ts はガイドリソースとワークフロープロンプトを定義します。src/tool-registry.ts は同じスキーマをデータとして保持し、src/tool-search.ts はそれらをコンパクトな機能範囲に変換するため、提示されるカタログと実行可能なカタログが食い違うことはありません。これらは内部の Simons ツールとは別個のものであり、共有スキーマパッケージからインポートされることもありません。サーバーは、サービスロールキーでユーザーデータを照会するのではなく、既存の REST アダプターにプロキシします。ホスト型サービスは、認証済みの Simons チャットプロキシルートにも対応しています。これらのルートは追加の MCP ツールではありません。

ローカル開発

npm ci
export CPZ_API_BASE_URL=https://api.cpz-lab.com/functions/v1/rest-api
export MCP_BASE_URL=http://localhost:3001
export MCP_TOKEN_SECRET=replace-with-a-strong-development-secret
npm run dev

クライアントはCPZ_API_BASE_URLの末尾に/v1を追加します。組み込みのデフォルト値にはすでに/functions/v1/rest-apiが含まれているため、環境変数にAPIドメインだけを設定すると正しく動作しません。このサーバーではCPZ_SERVICE_KEYは必要ありません。

変数	用途
PORT	HTTP ポート（デフォルトは 3001）
CPZ_API_BASE_URL	/v1より前のRESTアダプターのベースURL
CPZ_API_TIMEOUT_MS	上流リクエストのタイムアウト時間（デフォルトは 20000 ms）
CPZ_GATEWAY_BASE_URL	オーバーレイツール用のcpzゲートウェイのベースURL（デフォルトはhttps://api-ai.cpz-lab.com/cpz）
MCP_BASE_URL	OAuthのディスカバリーとリダイレクトで使用する公開オリジン
MCP_TOKEN_SECRET	暗号化されたOAuthトークンと登録情報に使用する共有シークレット
ALLOW_LEGACY_BEARER	trueの場合にのみ、従来のプレーンテキスト形式のベアラーを有効にします
SIMONS_UPSTREAM_URL	任意のSimonsプロキシ上流URLの上書き設定
SENTRY_DSN	任意のエラー報告設定

OAuthの登録情報、コード、トークンには暗号化された状態情報が含まれます。本番環境のレプリカでは、同じMCP_TOKEN_SECRETを共有する必要があります。設定されていない場合、開発環境ではプロセスごとにランダムなキーが使用されるため、トークンは再起動後に引き継がれず、別のレプリカでも解決できません。リフレッシュトークンの有効期間は30日です。ローテーションしても以前のリフレッシュトークンは無効になりません。アクセスを削除するには、基盤となるCPZ APIキーを失効させてください。

検証とビルド

npm run export:catalog  # refresh tool-catalog.json after schema/description changes
npm test
npm run build
npm start

テストでは、登録、検証、ルーティング、認証情報、レスポンスエラー、OAuthの動作を確認します。ローカルでの検証に、実際の注文や戦略の実行は必要ありません。

Docker

docker build -t cpzai-mcp-server .
docker run --rm -p 3001:3001 \
  -e MCP_BASE_URL=http://localhost:3001 \
  -e MCP_TOKEN_SECRET=replace-with-a-strong-development-secret \
  cpzai-mcp-server

対象範囲とコントリビューション

サポート対象のユーザー接続には、ホストされたエンドポイントを使用してください。このリポジトリは透明性の確保とローカル開発のために提供されており、現時点で本番環境でのセルフホストはサポートされていません。ホスト環境のインフラストラクチャは別途管理されています。

CIでは、tool-catalog.jsonとMCPのディスカバリー結果を比較し、すべてのツールがこのREADMEに記載されていることを確認します。同じスナップショットをnpm run export:catalog -- --output /path/to/cpzai/src/lib/mcp-tool-catalog.jsonでプラットフォームにエクスポートしてください。プラットフォームのドキュメントテストでは、公開ツールの一覧を確認します。

公開スキーマ、動作テスト、README、CPZAIのエージェント統合ドキュメントを常に同期してください。公開ルートの実装とテストが完了するまでは、内部向けのSimonsツールや、予定されているSDK検索、サンドボックス、パッチ、キャンセル、ミドルオフィスへの書き込み機能を宣伝しないでください。

MIT © CPZ Capital Ltd.