13FLOW

13FLOW MCP サーバー

このディレクトリには、13FLOW の本番環境向け MCP インターフェースが含まれています。

Flask アプリケーションとは意図的に分離されています。

• Flask は公開ウェブサイト、公開 API、Pro API を提供します。
• この Node サービスは、Streamable HTTP を介して Model Context Protocol エンドポイントを公開します。
• Apache は https://13flow.eu/api/mcp でこのサービスを公開します。
• このサービスはローカルの Flask API http://127.0.0.1:8000 を呼び出し、EDGAR には一切アクセスしません。

この設計は、l0g.fr の MCP アーキテクチャを踏襲しています。ステートレスなトランスポート、リクエストごとに 1 つの MCP サーバー、サイズを制限した JSON ボディ、Host／Origin の検証、IP ごとのレート制限、ヘルスチェック、構造化されたツール出力、読み取り専用の注釈を備えています。

機能の境界

公開ツールは無料で、読み取り専用です。

• get_live_status
• get_product_status
• get_research_readiness
• list_funds
• get_fund
• get_stock
• preview_watchlist
• discover_watchlist
• get_confluence_signals
• get_signal_history
• get_confluence_methodology
• get_data_quality
• get_agent_stats

公開リソースには、13flow://product-status、13flow://research-readiness、13flow://agent-stats が含まれます。 これらは、現在の検証、データ品質、運用者レビューの境界を示し、終了した公開商用サービスをエージェント向けの契約に変えることはありません。

get_agent_stats、このリソース、GET /stats は、/agents、/fr/agents、/api/agent-stats で使用されるものと同じ、プライバシーに配慮したカウンターを公開します。保存されるのは UTC の日次集計のみです。固定のクライアント種別、登録済みツール名、ハンドラーの結果、所要時間のカウンターが含まれます。テレメトリストアには、IP アドレス、User-Agent、クライアントのバージョン、未加工のクライアント名、引数、プロンプト、応答、キーは保存されません。初期化はハンドシェイクであり、一意のユーザーを示すものではありません。

コンテキストを多く消費するツールには、デフォルトで上限が設定されています。list_funds はページネーションに対応した簡潔な行を返し、ファンドおよびティッカーのツールは結果ウィンドウの件数を明示し、ウォッチリストのツールは移動の根拠を制限しながら、ウェブおよび API の正規 URL を構造化出力に含めます。

任意の Pro ツールは読み取り専用ですが、運用者が意図的に MCP_PRO_TOOLS_ENABLED=1 を設定しない限り、登録も公開もされません。

• pro.list_funds
• pro.get_fund
• pro.get_data_quality

この別のプロファイルが有効な場合、次の条件のいずれかを満たすときに限り、呼び出しが受け付けられます。

1. リクエストに X-13FLOW-Key で有効な既存の 13FLOW Pro API キーが含まれている。
2. リクエストに x402 v2 PAYMENT-SIGNATURE が含まれ、設定済みのファシリテーターによって検証および決済される。

クライアントの Authorization ヘッダーは MCP Pro の認証情報として受け付けられず、下流に転送されることもありません。これにより、MCP OAuth トークンが異なる API オーディエンスに渡されるのを防ぎます。

どちらの条件も満たされない場合、サーバーは PAYMENT-REQUIRED ヘッダーとともに HTTP 402 Payment Required を返します。MCP クライアントが明確なエラーを表示できるよう、ボディの形式は JSON-RPC に準拠します。

x402 ポリシー

13FLOW は、個々の Pro MCP ツール呼び出しに対するマシン間決済ゲートとして x402 を使用できます。 デフォルトでは無効で、Registry プロファイルには含まれず、現在の公開提供の一部でもありません。 有効にするには、明示的な Pro プロファイルと新たな運用セキュリティレビューも必要です。 サーバーは、有料ツールごとに受け付ける決済オプションを 1 つ提示します。

• scheme：デフォルトでは exact
• network：デフォルトでは eip155:8453
• price：MCP_X402_PRICE
• destination：MCP_X402_PAY_TO
• resource：https://13flow.eu/api/mcp#<tool>

サーバーはフェイルクローズ方式です。

• MCP_X402_ENABLED=1 が設定されていない場合、x402 による有料アクセスは許可されません。
• MCP_X402_PAY_TO が設定されていない場合、x402 による有料アクセスは許可されません。
• MCP_X402_FACILITATOR_URL が設定されていない場合、x402 による有料アクセスは許可されません。
• MCP_13FLOW_INTERNAL_PRO_TOKEN_FILE が設定されていない場合、x402 による有料アクセスは許可されません。
• MCP ツールの実行前に、決済がファシリテーターの /verify と /settle を通過する必要があります。

実装は x402 v2 HTTP ヘッダーに準拠しています。

• PAYMENT-REQUIRED：サーバーからクライアントへ送信する、決済要件を含む base64 JSON
• PAYMENT-SIGNATURE：クライアントからサーバーへ送信する、決済ペイロードを含む base64 JSON
• PAYMENT-RESPONSE：サーバーからクライアントへ送信する、決済処理結果を含む base64 JSON

オプションの決済識別子拡張を受け付けます。この拡張がある場合、サーバーは有効期間の短いフィンガープリント結合済み決済キャッシュを保存するため、まったく同じリクエストの再試行が別の有料操作として実行されることはありません。ロードバランサーの背後で複数の MCP レプリカを実行する場合は、Redis または別の共有ストアを使用してください。

環境

MCP_HOST=127.0.0.1
MCP_PORT=8849
MCP_PATH=/mcp
MCP_PUBLIC_SITE=https://13flow.eu
MCP_13FLOW_API_BASE=http://127.0.0.1:8000
# Required only for an explicitly enabled isolated Pro profile.
MCP_13FLOW_PRO_API_BASE=http://127.0.0.1:8001
MCP_ALLOWED_HOSTS=13flow.eu,www.13flow.eu,127.0.0.1,localhost
MCP_ALLOWED_ORIGINS=https://13flow.eu,https://www.13flow.eu
MCP_RATE_MAX=120
MCP_MAX_RATE_BUCKETS=10000
MCP_MAX_BODY=1048576
MCP_MAX_UPSTREAM_BODY=8388608
MCP_MAX_IN_FLIGHT=32
MCP_MAX_CONNECTIONS=128
MCP_MAX_PAYMENT_CACHE=500
MCP_STATS_RETENTION_DAYS=30
# Production is pinned to this systemd StateDirectory path.
MCP_STATS_FILE=/var/lib/13flow-mcp/agent-stats.json
MCP_API_TIMEOUT_MS=10000
MCP_REQUEST_TIMEOUT_MS=15000
MCP_GIT_SHA=<deploy sha>

# Keep this disabled on the public Registry daemon.
MCP_PRO_TOOLS_ENABLED=0

# Optional isolated profile only (do not uncomment on the Registry daemon):
# MCP_PRO_TOOLS_ENABLED=1
# MCP_X402_ENABLED=1
# MCP_X402_SCHEME=exact
# MCP_X402_NETWORK=eip155:8453
# MCP_X402_PRICE=$0.05
# MCP_X402_PAY_TO=0x...
# MCP_X402_ASSET=<optional asset identifier>
# MCP_X402_FACILITATOR_URL=https://...
# Production secrets must use root-owned files, never inline environment values.
# MCP_X402_FACILITATOR_AUTH_FILE=/etc/13flow/mcp-facilitator-auth

# Server-side Pro credential used only after a verified x402 settlement.
# Prefer the _FILE form with a root-readable/flowmcp-readable 0640 secret.
# MCP_13FLOW_INTERNAL_PRO_TOKEN_FILE=/etc/13flow/mcp-internal-pro-token

MCP_X402_TEST_MODE=1 はローカルテスト専用です。本番環境では有効にしてはいけません。

ローカル実行

cd mcp-server
npm ci
npm run check
MCP_13FLOW_API_BASE=https://13flow.eu npm start

別のターミナルで実行します。

cd mcp-server
URL=http://127.0.0.1:8849/mcp npm test

テストクライアントは、トランスポートヘッダー、Host/Origin の拒否、JSON-RPC バッチの拒否、プロトコルバージョンの処理、本文サイズ制限、ツール／リソースの検出、読み取り専用アノテーション、結果サイズの上限、正規の来歴リンク、デフォルトで Pro ツールが存在しないことを検証します。フェイルクローズ設定、上流からの過大なレスポンス、同時実行数上限のリグレッションを確認するには、npm run test:config と npm run test:security を実行してください。npm run test:telemetry は、永続化、保持期間、メトリクスの整合性、クライアント／ツールの生データが存在しないことを検証します。/healthz を意図的に非公開にしているパブリックプロキシ経由でテストする場合に限り、SKIP_HEALTH=1 を設定してください。本番環境の ModSecurity エッジでは、MCP バックエンドに到達する前に、サポート対象外のリクエストコンテンツタイプが拒否される場合があります。Debian 12 では、パッケージ版の ModSecurity 2.x JSON プロセッサも 上流の問題 #2807 の影響を受けます。切り詰められた JSON は、フェーズ 2 のルールで REQBODY_ERROR が利用可能になる前に、汎用 HTTP 500 で拒否される場合があります。EXPECT_WAF_REJECTIONS=1 を設定すると、こうした範囲が限定されたフェイルクローズ方式のエッジでの差異（サポート対象外のコンテンツタイプには 403 または 415、切り詰められた JSON には 400 または 500）のみを許容できます。バックエンドへの直接テストでは厳密な検証が引き続き適用され、それぞれ 415 と 400 が必要です。これらのステータスを統一するために SecRequestBodyAccess または JSON プロセッサを無効にしないでください。リクエスト本文の検査が低下します。

URL=https://13flow.eu/api/mcp \
STATS_URL=https://13flow.eu/api/agent-stats \
SKIP_HEALTH=1 EXPECT_WAF_REJECTIONS=1 npm test

Official MCP Registry

ルートの server.json では、パブリック Streamable HTTP エンドポイントを io.github.bluetouff/13flow として宣言しています。公開前にマニフェストを検証してください。

cd /opt/13flow
mcp-publisher validate

対応するサーバーバージョンのデプロイとパブリックスモークテストの成功を確認したら、認証はできるだけ直前に行い、一度だけ公開してから、正確なバージョンとリモート URL を確認してください。

mcp-publisher login github
mcp-publisher publish
cd mcp-server
npm run registry:verify -- --version 1.0.0

Registry への公開はメタデータの公開です。MCP デーモンはデプロイされないため、稼働中のエンドポイントと Registry エントリーは個別に検証する必要があります。

デフォルトの Registry プロファイルでプライベートツールが実行されないことを確認してください。

curl -i http://127.0.0.1:8849/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pro.list_funds","arguments":{}}}'

期待される結果：JSON-RPC の不明なツールエラーです。pro.list_funds が tools/list にも含まれていないことを確認してください。

分離され、明示的に有効化された Pro プロファイルでは、専用のキー ヘッダーのみを受け付けます。

printf "API token: "
read -r -s TOKEN
printf "\n"

curl -fsS http://127.0.0.1:8849/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-13FLOW-Key: $TOKEN" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pro.list_funds","arguments":{}}}'

unset TOKEN

本番環境へのデプロイ

依存関係を一度だけインストールします。

sudo useradd --system --no-create-home --shell /usr/sbin/nologin flowmcp
cd /opt/13flow/mcp-server
sudo npm ci --omit=dev
sudo chown -R root:flowmcp /opt/13flow/mcp-server
sudo chmod o+x /opt/13flow

deploy/13flow-mcp.service から systemd ユニットをインストールし、 /etc/13flow/13flow-mcp.env に環境変数を設定してから、次を実行します。

sudo systemctl daemon-reload
sudo systemctl enable --now 13flow-mcp
curl -fsS http://127.0.0.1:8849/healthz | python3 -m json.tool
curl -fsS http://127.0.0.1:8849/stats | python3 -m json.tool

このユニットは、モード 0700 の systemd StateDirectory として /var/lib/13flow-mcp を作成し、デーモンにはそれ以外の永続的な書き込み先を許可しません。 agent-stats.json は、サイズを制限した一時ファイルと rename を使い、モード 0600 で書き込まれます。本番環境では、別のテレメトリーパスは拒否されます。

Apache では /api/mcp への POST のみを許可し、そのパスを Node サービスにプロキシする必要があります。メインサイトのメソッド許可リストはそのまま維持し、ほかの公開エンドポイントが読み取り専用のままになるようにしてください。付属の vhost はリクエストを 1 MiB に制限し、プロキシする前にクライアントが送信した転送ヘッダーを削除します。付属の systemd ユニットはループバック以外のネットワーク通信を拒否します。したがって、外部の x402 ファシリテーターを有効にするには、意図的なネットワークポリシーの上書きと新たなレビューが必要です。また、環境ファイルの読み込み後に Pro/x402 の有効化変数とシークレット変数をすべて削除するため、この公開ユニットが環境変数の誤編集によってプライベートプロファイルに変わることはありません。

方法論に関する契約

MCP サーバーは、配信プロトコルにすぎません。投資シグナルの定義を変更するものではありません。

Confluence v1 は、凍結された公開調査契約として引き続き適用されます。

• スコアは確率や期待リターンではなく、序列を示すヒューリスティックな順位です。
• デフォルトの重みは、実際の過去データによる検証結果が公開されるまではヒューリスティックです。
• ライブステータス、データ品質、提出書類数、カバレッジは公開されたままにします。
• 追記専用のシグナル履歴が、シグナル改訂の監査証跡となります。
• Pro の出力には、選択した提出書類、基準日、ポジション、変動、データ品質に関する注意事項を再現するのに十分なメタデータを含める必要があります。

MCP ツールが EDGAR を直接呼び出すことはありません。鮮度と 13F のカバレッジは、すでに公開されている市場データベースとキャッシュファイルから取得します。