SQD

SQD Portal MCP サーバー

EVM、Solana、Bitcoin、Substrate、Hyperliquid、Tron の各ネットワークにおけるトランザクション、ログ、トレース、トークンの送金、ウォレット、分析、時系列、ローソク足など、SQD Portal のデータからブロックチェーンに関する質問に回答する MCP サーバーです。ホスト内で Explorer を利用することもできます。

このサーバー自体はチェーンのインデックスを作成しません。入力を検証し、範囲を限定した Portal クエリを計画して、カバレッジ、鮮度、ページネーション、エビデンスのメタデータとともに結果を返すため、アシスタントは確認した内容を正確に説明できます。SQD アカウント、API キー、クライアント認証情報は不要です。

HTTP と stdio でステートレスな MCP 2026-07-28 プロトコルを使用し、まだこのリビジョンへの移行中のクライアント向けに、SDK 管理のレガシーなネゴシエーション経路も維持しています。リリースノートは CHANGELOG.md にあります。コードに取り組む場合は CONTRIBUTING.md を、脆弱性を報告する場合は SECURITY.md をご覧ください。

現在の公開インターフェイス

• 公開ツール 28 個
• 高度なデバッグツール 3 個
• 公開パラメーターでは network を使用
• 検出フィルターでは vm を使用
• v0.8.x にレガシーなツールエイリアスはありません

生クエリツールは、デフォルトで簡潔なレスポンスを返します。より大きなペイロードが必要な場合にのみ、response_format: "full" を指定してください。

エンティティに関する質問では、まず portal_resolve_entity を使用できます。EVM トークンのシンボル／アドレス、EVM コントラクトのエイリアス、プール識別子、プロトコル名、Hyperliquid のコイン名を、曖昧な候補を明示したまま、クエリに使用できるフィルターに解決します。

トークンシンボルの解決とトークンメタデータには、コードに埋め込まれたトークンアドレス定数ではなく、オープンなトークンリストデータを使用します。トークンリストのデータが利用できない場合、古い場合、またはそのネットワークでサポートされていない場合は、レスポンスに明示的な通知が含まれます。

ウォレットに関する質問では、まず portal_get_wallet_summary を使用してください。デフォルトで fund_flow を返し、生ツールで詳細を調べる前に、流入／流出、資産フロー、取引相手、観測された最大の移動、次に確認すべきエビデンスの手がかりを提示します。

ツールグループ

検出：

• portal_list_networks
• portal_get_network_info
• portal_get_head
• portal_resolve_entity

クロスチェーンの利便性ツール：

• portal_get_recent_activity
• portal_get_wallet_summary
• portal_get_time_series

EVM：

• portal_evm_query_transactions
• portal_evm_query_logs
• portal_evm_query_traces
• portal_evm_query_token_transfers
• portal_evm_get_contract_deployment
• portal_evm_get_contract_activity
• portal_evm_get_analytics
• portal_evm_get_ohlc

Solana：

• portal_solana_query_transactions
• portal_solana_query_instructions
• portal_solana_get_analytics

Bitcoin：

• portal_bitcoin_query_transactions
• portal_bitcoin_get_analytics

Substrate：

• portal_substrate_query_events
• portal_substrate_query_calls
• portal_substrate_get_analytics

Hyperliquid：

• portal_hyperliquid_query_fills
• portal_hyperliquid_get_analytics
• portal_hyperliquid_get_ohlc

Tron：

• portal_tron_query_transactions
• portal_tron_query_logs

高度なデバッグ：

• portal_debug_query_blocks
• portal_debug_resolve_time_to_block
• portal_debug_hyperliquid_query_replica_commands

これらのグループはツールセット（discovery、convenience、evm、solana、bitcoin、substrate、hyperliquid、tron、debug）としても利用できます。デプロイ時に MCP_TOOLSETS または MCP_TOOLS を使ってカタログを絞り込めます。また、HTTP 接続では ?toolsets= または X-MCP-Toolsets ヘッダーを使って、さらに絞り込むことができます。詳しくは HTTP デプロイに関する注意事項をご覧ください。何も設定しない場合は、31 個のツールすべてが提供され、ホスト型エンドポイントもこのデフォルト設定を維持します。

対応データ

• Portal がインデックス化した EVM ネットワーク。Base、Ethereum、Optimism、Arbitrum、Monad、Hyperliquid EVM など、多数のネットワークが含まれます
• Tron のネイティブトランザクション（TRX の送金、TRC-10 の送金、インラインログと内部トランザクションを含むコントラクト呼び出し）と、TRC-20 の送金などの TVM イベントログ。Base58 または 16 進数のアドレス、正確な TRX 金額、各ログの親トランザクションハッシュが含まれます。これ以外の用途向けに、同梱の SQD プラグインスキルで Stream API の生データを説明しています
• Solana メインネット
• Bitcoin メインネット
• Hyperliquid の約定とレプリカコマンド
• Portal がインデックス化した Substrate ネットワーク

Substrate のサポートは現在、過去データのみです。リアルタイムの追跡には対応していません。

応答形式

ほとんどのツールは、MCP の structuredContent と、古いクライアント向けの簡潔な JSON テキストフォールバックで、同じエンベロープを返します。エンベロープには通常の結果本文のほか、次のような共通メタデータが含まれます。

• answer
• display
• next_steps
• investigation
• _freshness
• _coverage
• _pagination
• _ordering

investigation はエージェント向けの簡潔な根拠ガイドです。主な結果のパス、範囲を限定した期間、アドレスやトランザクションハッシュなどの有用な絞り込み項目、追加のフィルター、結果を完全なものとして扱う前に把握しておくべき制限を示します。データを含む成功応答には、正規化された引数、決定論的なダイジェスト、行の照合結果、データソースの期間、正確な再実行または意味的な再実行のセマンティクスを記録した _evidence レシートも含まれます。正確なレシートでは根拠となる期間が固定されます。意味的なレシートでは、変動する相対期間で再実行すると、より新しいスナップショットが返される可能性があることが明示されます。

推定、部分取得、サンプリング、上限適用、ページネーションのいずれかが使用された場合、その旨はトップレベルの回答とメタデータに示されます。_pagination.has_more が true になるのは next_cursor がある場合に限られ、_coverage は要求された期間を最後まで読み取ったか（window_complete）、および応答に一致するすべての行が含まれているか（result_complete）を示します。安全にページネーションを続行するための情報には、カーソル引数を明示した実行可能なツール呼び出しメタデータが含まれます。安全に再構成できない候補は、実行不可能として示されます。

チャート向けのツールは、MCP クライアントや LLM がペイロードをリバースエンジニアリングせずに表示できるよう、チャートとテーブルの記述子も返します。

SQD Explorer（ベータ版）

SQD Explorer は、MCP Apps に対応したホスト内にツールの結果を表示する MCP App です。ベータ版であり、デフォルトでは無効になっています。デフォルトのデプロイでは、structuredContent と簡潔な JSON テキストのみを返し、ツールの結果からホストに UI を開くよう要求することはありません。有効にするには、次の 2 つの方法があります。

• 1 つの接続のみ：エンドポイントに ?app=1 を追加します。例：https://portal.sqd.dev/mcp?app=1。ほかのユーザーには何も変更を加えずにベータ版を試せます。
• デプロイ全体：MCP_APP_ENABLED=true を設定します。接続ごとにどちらの方向にも上書きできるため、?app=0 を指定すると、1 つのクライアントだけ無効に戻せます。

アプリのリソースはどちらの場合も登録されたままなので、オプトインしていない場合でも、ホストは直接読み取ることができます。

有効にすると、互換性のあるホストには、コンテンツに合わせたサイズのインラインカードと、21 個のデータツールに対応した全画面ワークスペースが表示されます。主な数値を先頭にしたメトリクス、複数系列および符号付き値のチャート、連動する出来高と固定表示の読み取り値を備えた価格ローソク足、10 行を表示する「すべて表示」コントロール付きのランキングパネルとタイムラインパネル、すべての行を対象に検索できる 10 行単位のページングに対応したエビデンステーブル、アドレス・ハッシュ・ブロック用のエクスプローラーリンク、SQD ネットワークメタデータに基づくチェーンのロゴと名称、続きのデータを取得するコントロール、現在のセッションの履歴、ホスト経由での JSON または CSV エクスポートを利用できます。ポインターやキーボードで調べると、プロットされた正確な値を確認できます。データのないバケットもギャップとして表示され、識別子は短縮されません。また、ローカルでの行数上限はサーバー側のデータ完全性とは別に扱われます。後続の取得に失敗した場合も、最後に正常に取得した結果がエラーの下に保持されます。このアプリは自己完結型で、ブラウザーの永続ストレージは使用しません。ブラウザー側からのリクエストは、リソース CSP で宣言された 2 つのオリジン cdn.subsquid.io と sqd.dev からのチェーンロゴ画像のみです。MCP App に対応していないホストには、同じ structuredContent と簡潔な JSON テキストのフォールバックが返されるため、基となる回答が UI に依存することはありません。docs/explorer-design.md には、アプリが従う設計ルールが記載されています。

3 つの MCP プロンプトにより、ツールを追加せずに再現可能な出発点を用意できます。

• investigate-wallet
• investigate-contract
• investigate-market

チャートを中心としたデモでは、次のように尋ねてください：Show BTC price action and trading volume on Hyperliquid for the past hour, using five-minute candles. Explain whether the final candle is closed. 結果を開くと、ローソク足チャート、出来高、エビデンステーブル、要求された時刻とインデックス済み時刻の範囲、および受領証が SQD Explorer に表示されます。安定した検証を行う必要がある場合は、返された requested_window_start_timestamp と requested_window_end_exclusive を、固定の from_timestamp 入力および to_timestamp 入力として再利用してください。

Claude で試す

ホストされているエンドポイントでは Explorer が無効になっているため、新規ユーザーは自分の接続で有効にします。

1. claude.ai または Claude Desktop で、Settings → Connectors → Add custom connector を開き、https://portal.sqd.dev/mcp?app=1 を入力して、認証なしを選択します。?app=1 により、この接続でのみベータ版が有効になります。Claude Desktop では、代わりに最新リリースから sqd.mcpb をインストールし、「SQD Explorer (beta)」設定をオンにすることもできます。
2. 新しいチャットを開始し、そのチャットで SQD コネクターを有効にします。
3. データについて質問します。次のいずれかを尋ねると、Explorer を表示できるツールが呼び出されます。
   • アドレスを指定して What has this wallet been doing on Base lately?（ウォレットの概要）
   • Show me recent activity on Ethereum（最近のアクティビティ）
   • Chart hourly transaction counts on Base for the last day（時系列）

結果はテキストのブロックではなくインラインカードとして表示されます。全画面ワークスペースを開くには、カードを開いてください。Explorer を表示できるのは 21 個のデータツールのみです。Which networks do you support? のようなカタログに関する質問では portal_list_networks が呼び出され、プレーンテキストで回答されます。これは想定された動作であり、失敗ではありません。

インストール

npm install
npm run build

実行

stdio：

npm start

HTTP：

npm run start:http

開発者向けディスカバリー

サーバーは、クライアントの開発者向けに構造化されたツール選択ガイドを公開しています。

• MCP リソース sqd://tools は、グループ化されたツールのメタデータ、例、開始点、統合に関する注意事項を返します。
• MCP リソース sqd://tools/{name} は、1 つのツールのガイド項目を返します。例：sqd://tools/portal_get_time_series。

ツールとリソースのディスカバリーは、MCP プロトコル自体で行います。サーバーは、重複する HTTP カタログを管理しません。

Codex プラグイン

Codex プラグインのラッパーは plugins/portal にあり、デフォルトではホスト型 MCP エンドポイント https://portal.sqd.dev/mcp を使用します。

このリポジトリ内のマーケットプレイスからインストールします。

codex plugin marketplace add .
codex plugin add portal@sqd

インストール後、新しい Codex スレッドを開いてください。初回使用時のプロンプトには、Hyperliquid の BTC 無期限先物の約定、最近の Base のトランザクション量、Base 上の最新の USDC 送金が含まれます。

Claude Code プラグイン

Claude Code プラグインは、同じホスト型 MCP エンドポイントと同じ公開セレクターを使用します。

claude plugin marketplace add subsquid-labs/portal-mcp-server
claude plugin install portal@sqd

インストール後、新しい Claude Code セッションを開き、SQD MCP ツールが読み込まれるようにしてください。

Grok

Grok チャットでは、SQD をカスタムコネクターとして使用できます。

1. grok.com/connectors を開きます。
2. New Connector を選択し、次に Custom を選択します。
3. MCP サーバー URL として https://portal.sqd.dev/mcp を入力します。
4. 認証は設定しないでください。

Grok Build は Claude Code プラグインを直接読み込むため、同じパッケージを使用します。

grok plugin install --trust subsquid-labs/portal-mcp-server#plugins/portal

ChatGPT

カスタム MCP アプリが有効になっているワークスペースで、Settings → Apps → Create を開き、https://portal.sqd.dev/mcp を入力して、認証なしを選択し、ツールをスキャンして、ドラフトアプリを作成します。サーバーは読み取り専用で、ユーザーの認証情報は必要ありません。

Claude Desktop

最新リリースから sqd.mcpb をダウンロードして開きます。Claude Desktop はワンクリックでバンドルをインストールし、31 個のツールを一覧表示します。バンドルにはサーバー、本番用の依存関係、任意の設定項目「SQD Explorer (beta)」が含まれており、この設定はデフォルトでオフになっています。マシンには Node 22 以降が必要です。

手動での代替方法として、ローカルクローンから npm run build を実行した後、claude_desktop_config.json に次のようなエントリーを追加します。

{
  "mcpServers": {
    "SQD": {
      "command": "node",
      "args": ["/absolute/path/to/sqd-portal-mcp-server/dist/index.js"]
    }
  }
}

使用上の注意

• 正確なネットワーク名がわからない場合は、portal_list_networks から始めてください。
• 最近のインデックス済み状態が必要な場合は、まず portal_get_network_info または portal_get_head を使用してください。
• 質問が広範な場合は、生のクエリに移る前に portal_get_recent_activity、portal_get_wallet_summary、または portal_get_time_series から始めてください。
• 時間範囲には、30m、past 30 minutes、in the past 1h、in last 38 mins、last hour、30 minutes ago などの短縮表記や自然な表現を使用できます。
• ローソク足形式の出力が実際に必要な場合に限り、portal_evm_get_ohlc と portal_hyperliquid_get_ohlc を使用してください。
• 大規模なクエリや探索的なクエリでは、完全なレコード形式が必要な場合を除き、response_format: "compact" を優先してください。

HTTP デプロイに関する注意事項

HTTP モードでは、MCP を / と /mcp、ライブネスを /health、レディネスを /ready で公開します。ホスト型サービスは、同じバージョン管理されたヘルスレスポンスを https://portal.sqd.dev/mcp/health で公開します。

• MCP およびヘルスエンドポイントでは認証は不要です。
• ツールとリソースの検出には MCP プロトコルを使用します。廃止された /tools および /tools.json ルートは 404 を返します。
• 複数のプロセスを実行するデプロイでは、MCP_CURSOR_SECRET を設定してください。これにより、あるインスタンスが発行したカーソルを次のインスタンスでも受け付けられます。未設定の場合、各プロセスはそれぞれ異なるランダムキーで署名するため、再起動後やロードバランサーを経由した際にカーソルが使えなくなります。
• /health は version と commit を報告します。これはイメージのビルド元となった git commit です。また、各ツールの結果には両方が _server 内で繰り返し含まれます。Docker Hub タグの latest、X.Y.Z、X.Y は、v* リリースタグからのみ作成されます。edge と sha-<commit> は、すべての main プッシュから作成されます。本番環境ではバージョンタグを固定してください。
• /ready は、データセットカタログが一度読み込まれ、最新の Portal プローブが MCP_READY_MAX_AGE_MS 以内に成功した場合にのみ 200 を返します。それ以外の場合は reason と Retry-After を含む 503 を返します。オーケストレーターのレディネスチェックには /ready、ライブネスチェックには /health を指定してください。Docker イメージの HEALTHCHECK は /ready を使用します。
• サーバーは、MCP_BIND で別途指定しない限り 127.0.0.1 にバインドします。また、すべてのルートで Host ヘッダー（ブラウザーから送信される場合は Origin も）を許可リストと照合するため、DNS リバインディングされたページからローカルインスタンスにアクセスすることはできません。ループバックのホストとオリジンは常に許可されます。Origin のないリクエストは常にオリジンチェックを通過します。ループバック以外にバインドする場合は、MCP_ALLOWED_HOSTS と MCP_ALLOWED_ORIGINS を設定してください。どちらかが未設定の場合、サーバーは起動時にエラーをログに記録し、そのチェックを行わずにリクエストを処理します。Docker イメージでは MCP_BIND=0.0.0.0 が設定されるため、デプロイ環境で両方の変数を設定するか、すでにそれらを検証するプロキシの背後で * を設定してください。
• すべてのリクエストには上限があります。ヘッダーは MCP_HEADERS_TIMEOUT_MS 以内、リクエスト全体は MCP_REQUEST_TIMEOUT_MS 以内、アイドル状態のキープアライブは MCP_KEEP_ALIVE_TIMEOUT_MS 以内に制限されます。また、MCP_MAX_BODY_BYTES を超える MCP ボディは解析前に 413 で拒否されます（長さの指定がないチャンク転送ボディの場合は 411）。

便利な環境変数：

• MCP_CURSOR_SECRET ページネーションカーソルの署名に使用するキーです。複数のプロセスを実行するデプロイでは必ず設定してください。 設定しない場合、各プロセスはそれぞれ異なるランダムキーで署名するため、あるインスタンスが発行したカーソルは次のインスタンスで拒否され、再起動時やロードバランサー経由で接続先が変わった際に、クライアントは現在の位置を失います。また、ツールが提示しないウィンドウのカーソルを呼び出し元が生成するのを防ぎます。
• MCP_TOOLSETS 提供するツールセットをカンマ区切りで指定します（discovery、convenience、evm、solana、bitcoin、substrate、hyperliquid、tron、debug。すべてを指定する場合は all または default）。不明な名前は無視され、起動時にエラーが表示されます。MCP_TOOLS より優先されます。デフォルトは9つすべてで、全31ツールのカタログです。
• MCP_TOOLSETS が設定されていない場合に提供する、正確なツール名をカンマ区切りで指定する MCP_TOOLS
• 接続ごとに、エンドポイント URL の ?toolsets=evm または X-MCP-Toolsets: evm ヘッダーを指定すると、その接続に限りデプロイのツールセットを絞り込めます。ツールセットを追加することはできません。有効なセットに含まれないツールを参照するプロンプトは提供されません。有効なセットは、mcp_tool_client_calls_total 上で上限付きラベル（all、1つのツールセット名、または custom）として記録されます。
• MCP_BIND リッスンするインターフェースです。デフォルトは 127.0.0.1 です（Docker イメージでは 0.0.0.0）。
• MCP_ALLOWED_HOSTS ループバックに加えて、Host で許可するホスト名をカンマ区切りで指定します（ポートは無視されます）。* を指定するとチェックが無効になります。ループバック以外にバインドする場合は必須です。
• MCP_ALLOWED_ORIGINS ループバックに加えて、Origin で許可するホスト名をカンマ区切りで指定します。* を指定するとチェックが無効になります。ループバック以外にバインドする場合は必須です。
• MCP_REQUEST_TIMEOUT_MS、MCP_HEADERS_TIMEOUT_MS、MCP_KEEP_ALIVE_TIMEOUT_MS リクエストのタイムアウト上限です。デフォルトはそれぞれ 120000、30000、65000 です。
• MCP_MAX_BODY_BYTES MCP リクエストボディの上限です。デフォルトは 1048576 です。
• MCP_READY_PROBE_INTERVAL_MS および MCP_READY_MAX_AGE_MS レディネスプローブの間隔と鮮度の上限です。デフォルトはそれぞれ 30000 と 90000 です。
• MCP_APP_ENABLED 対応ホストにベータ版 SQD Explorer を提供するかどうかを指定します。デフォルトはオフです。true または 1 を指定できます。接続ごとに ?app=1 または ?app=0 を指定すると上書きできます。
• MCP_TOOL_WEIGHT_BUDGET アクティブなツール呼び出しの合計コストの上限です。デフォルトは 32 です。計測済みのプロファイルでは、キューに処理待ちがある間、検索は最大32件、raw または summary 呼び出しは最大4件、analytics 呼び出しは最大2件まで同時に実行できます。キュー内の処理は、引き続きキャンセルを認識します。
• MCP_TOOL_MAX_QUEUE キューに入れるツール呼び出し数の上限です。デフォルトは 64 です。
• MCP_TOOL_QUEUE_TIMEOUT_MS ツールの受付待ち時間の上限です。デフォルトは 5000 です。
• MCP_TOOL_CLIENT_WEIGHT_SHARE 1つの呼び出し元（ハッシュ化されたアドレスで識別する1つの接続）が同時に保持できるウェイト予算の割合です。デフォルトは 50 です。すべてのツールをスケジュールできるよう、最もウェイトの大きい単一ツールの値を下回ることはありません。MCP_TOOL_CLIENT_MAX_QUEUE は、1つの呼び出し元がキューに入れられる呼び出し数の上限です。デフォルトは 16 です。呼び出し元が共有上限を超えると、他の呼び出しは引き続き処理される一方で、再試行可能な overloaded 結果が reason: client_share とともに返されます。
• MCP_TRUST_PROXY 1（またはサーバーの手前にあるプロキシの数）を設定すると、ソケットアドレスではなく、プロキシが認識したアドレスを公平性の判定に使用します。このヘッダーは、直近のピア自体が信頼済みプロキシである場合にのみ読み取られます。また、呼び出し元は左側に任意の値を記述できるため、X-Forwarded-For の右側からホップ数を数えます。アドレスはハッシュ化され、保存もラベル付けもされません。
• MCP_TRUSTED_PROXY_PREFIXES プロキシとして扱うアドレスプレフィックスのカンマ区切りリストです。ピアアドレスの先頭との一致で判定します（例：203.0.113. または 2606:4700:）。これを設定すると、デフォルトに追加されるのではなく、デフォルトが置き換えられます。同じ場所にあるプロキシもサーバーに接続する場合は、ループバックまたはプライベートアドレス範囲も含めてください。未設定の場合、ループバックとプライベートアドレス範囲が信頼されます。同じ場所にあるプロキシはこの範囲内にあります。共有プライベートネットワークでは、そのネットワーク上の任意のホストが転送先アドレスを提示できるため、プロキシを明示的に指定してください。
• MCP_SLOW_REQUEST_MS 1件のツール呼び出しについて、受付待ち時間、実行時間、上限付きのクライアント種別を含む JSON 行を stderr に出力するしきい値です。デフォルトは 5000 です。

コストガードレール

サーバー内の各スキャン上限はコンパイル時に組み込まれており、ツールごとに設定されています。フィルタリングされたトレーススキャンは5,000ブロックで、コントラクトのデプロイ検索は1,000,000ブロックで停止します。ガードレールは、デプロイ環境で環境変数から設定する追加の上限を設けます。これにより、新しいイメージを用意しなくても、負荷が高いエンドポイントの上限を引き下げられます。

• MCP_GUARDRAIL_MODE は off（デフォルト）、shadow、enforce のいずれかです。
• MCP_GUARDRAIL_<CLASS>_<LIMIT> は上限を1つ設定します。<CLASS> は LOOKUP、RAW_QUERY、SUMMARY、ANALYTICS のいずれかで、<LIMIT> は MAX_SCAN_BLOCKS、MAX_WINDOW_SECONDS、MAX_UPSTREAM_BYTES のいずれかです。たとえば、 MCP_GUARDRAIL_RAW_QUERY_MAX_SCAN_BLOCKS=50000 のように設定します。

数値のデフォルト値はありません。 何も設定されていないクラスには追加の上限がないため、何も設定されていない場合、off と enforce は同じ動作になります。ガードレールが動作を変えるのは、数値を設定した場合だけです。

shadow はすべての上限を評価し、適用した場合にどうなっていたかを記録しますが、レスポンスは一切変更しません。enforce は次のように動作します。

• スキャンが上限を超えると、その上限で停止し、スキャン対象となった範囲を報告します。これは、スキャンがコンパイル時の上限に達した場合にすでに使用されている、同じ部分的なカバレッジの処理経路を使うため、_coverage.result_complete は false になり、レスポンスには検索したブロックが示されます。得られていない完全な回答を得られたかのように示すことはありません。
• クエリの時間幅が上限を超えると、データを取得する前にリクエストを拒否します。上限と次の手順をエラーに示します。開始が許可されなかったリクエストに対して、返せる部分的な結果はないためです。

カーディナリティに上限を設けたラベルを使用する4つのカウンター：mcp_guardrail_admitted_total{class}、 mcp_guardrail_would_block_total{class,limit}、 mcp_guardrail_blocked_total{class,limit}、および mcp_guardrail_fail_open_total{reason}。

推奨される段階的な導入方法。 設定を検討している上限を設定し、1週間 shadow を実行します。mcp_guardrail_would_block_total を確認してください。この値は、上限を設定した場合に実際に制限されるリクエストを正確に示します。その件数が想定より多い場合、問題はトラフィックではなく上限の設定にあります。意図した件数になったら、enforce に切り替えてください。

トレース

メトリクスで分かるのは頻度と所要時間です。トレースでは、1 回の呼び出しの中でどこに時間がかかったかが分かります。トレースは OTEL_EXPORTER_OTLP_ENDPOINT を設定しない限り無効です。未設定の場合、この機能に関するものは何もインポート、割り当て、送信されず、OpenTelemetry パッケージをインストールする必要もありません。

このパッケージは SDK に依存していません。SDK とエクスポーターを合わせると、公開済み tarball のおよそ 3.4MB に対して約 74 個のパッケージが追加されます。stdio 経由で実行するユーザーのほとんどはこれらを必要としないため、オプションのピア依存関係として宣言しています。トレースを有効にするには、サーバーと一緒にこれらをインストールし、コレクターを指定します。

npm i @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http

OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318

1 回のツール呼び出しが 1 つのツリーになります。

mcp.request                       (HTTP only: method, transport)
└─ tools/call portal_evm_query_logs
   ├─ mcp.admission               (the wait for a slot)
   ├─ portal.fetch                (one per attempt: dataset, status, bytes, resend count)
   ├─ portal.fetch
   └─ mcp.format_result           (hashing the answer for the evidence receipt)

OTEL_* 変数は OpenTelemetry SDK 自身が読み取るため、サンプリング、ヘッダー、バッチ処理、プロトコルは標準的な方法で設定できます。その他の動作は次のとおりです。

• HTTP リクエスト、またはツール呼び出しの _meta に traceparent がある場合、その呼び出しは新しいトレースを開始せず、呼び出し元のトレースの一部になります。この呼び出しがどのターンに属するかについて、より具体的な指定であるため、_meta の値が優先されます。
• 各 Portal リクエストには、それぞれのフェッチスパンを示す traceparent が含まれるため、Portal 側のトレースをこのトレースにつなげられます。トレースが無効の場合は、何も追加されません。
• トレースが有効な場合、JSON のログ行には trace_id と span_id が含まれるため、ログイベントとそのスパンを相互に検索できます。
• /health では、トレースが設定されているか、開始されたか、引数の記録が有効かどうかを確認できます。

スパン属性には、引数、アドレス、ハッシュ、カーソル、自由記述テキストは含まれません。 属性に含まれるのは、ツール名、処理クラス、データセット、上限を設けた件数、上限を設けた結果です。スパンはプロセスを離れてコレクターに送られますが、そのコレクターにクエリ自体が届くことはありません。そのため、ここでのルールはメトリクスのラベルに適用されるものと同じで、少なくとも自分の stderr にとどまるログよりも厳格です。MCP_OTEL_INCLUDE_ARGS=1 を設定すると、ツールスパンにツールの生の引数が追加されます。デフォルトでは無効で、本番環境での使用は安全ではありません。ツールの引数には、ウォレットアドレスが含まれることが多く、ユーザー自身の言葉が含まれることもよくあります。

テスト

npm run test:offline は、ビルド、lint、型チェック、ユニットテストを実行し、Portal へのアクセスを必要としないすべてのスイートを実行します。npm run test:live は Portal を使用するスイートを実行します。RELEASE_ASSURANCE.md にはリリース時に検証する内容がまとめられており、scripts/README.md にはすべてのスイートが記載されています。

ライセンス

MIT