Xrpl Utilities

@xrpl-utilities/mcp

XRPL-Utilities™ ポートフォリオ向けのModel Context Protocol サーバーです。6 つのサービスすべての読み取りエンドポイントを MCP ツールとして公開し、AI エージェントが検出して利用できるようにします。利用方法は、stdio 経由でローカルに利用する方法（Claude Desktop、MCP Inspector など）と、mcp.xrpl-utilities.io のホスト型エンドポイント経由でリモートに利用する方法があります。

対象サービス

サービス	機能	ツール
XR-Sentinel	XRPL ウォレットのアクティビティパターン分類器。アクティビティスコア、シグナルカタログ、ラベルコンテキスト、AI による説明を提供します。x402 の販売者が、広告している XRPL アカウントを管理していることを確認する無料チェックも利用できます	xrpl_sentinel_scan (有料), xrpl_sentinel_scan_history (有料), xrpl_sentinel_verify_origin (無料)
XR-Pulse	正規化された XRPL イベントフィード（ニュース、クジラの動き、RWA の発行と焼却、Sentinel のシグナル）と、無料の市場ビューを提供します。市場ビューには Ripple の取引相手、取引所フロー、エスクローカレンダー、RLUSD の分布、RWA の概要、トークンの健全性が含まれます。ライブ WebSocket ストリームは xrpl_pulse_stream_purchase で購入できます	xrpl_pulse_recent_events (有料), xrpl_pulse_events_by_address (有料), xrpl_pulse_stream_purchase (有料), xrpl_pulse_ripple_counterparties (無料), xrpl_pulse_ripple_topology (無料), xrpl_pulse_cex_attribution (無料), xrpl_pulse_network_stats (無料), xrpl_pulse_xrpl_primitives (無料), xrpl_pulse_whale_flow_24h (無料), xrpl_pulse_exchange_flow_delta (無料), xrpl_pulse_rwa_summary (無料), xrpl_pulse_exchange_net_flow (無料), xrpl_pulse_escrow_calendar (無料), xrpl_pulse_entity_positioning (無料), xrpl_pulse_rlusd_distribution (無料), xrpl_pulse_token_health (無料)
XR-Telemetry	XRPL のマクロスナップショット（供給量、流動性、AMM、Active Float）と、決済および DEX 取引量の時系列データを提供します	xrpl_telemetry_snapshot (有料), xrpl_telemetry_get_quote (有料、請求書), xrpl_telemetry_get_status (有料、請求書), xrpl_telemetry_get_results (有料、請求書), xrpl_telemetry_settlement_totals (無料), xrpl_telemetry_settlement_series (無料), xrpl_telemetry_dex_pair_volume (無料)
XR-Trust	XRPL の許可型アセットスタック（XLS-70/80/81、XLS-40 DID）のディレクトリと詳細情報、オペレーターインデックス、管轄区域、許可型ドメインのアクティビティを提供します	xrpl_trust_list_domains (有料), xrpl_trust_get_domain (有料), xrpl_trust_credential_issuers (有料), xrpl_trust_recent_events (無料), xrpl_trust_list_operators_index (無料), xrpl_trust_operator_drilldown (有料), xrpl_trust_operator_attribution (無料), xrpl_trust_usage_summary (無料), xrpl_trust_jurisdictions (無料), xrpl_trust_permissioned_activity (無料)
XR-Vault	リアルワールドアセットトラッカー。発行者ごとの供給量、発行と焼却のフロー、AMM プールへのエクスポージャーを提供します	xrpl_vault_scan (有料), xrpl_vault_daily_flow (無料)
XR-Flows	XRP ETF の AUM と XRPL の取引所フロー、ローンチの影響、クロスボーダーフローを提供します	xrpl_flows_scan (有料), xrpl_flows_correlation (無料), xrpl_flows_cross_border_flow (無料), xrpl_flows_launch_impact (無料), xrpl_flows_etf_flow_summary (無料)
XR-Desk	市場の状況、ポジショニング、RLUSD の健全性、供給圧力、RWA 市場をまとめたデスク向けブリーフィングを提供します	xrpl_desk_briefing (無料)

ツールは合計 44 個です。有料 15 個、無料 29 個で、すべて読み取り専用です。 有料呼び出しは、XRPL 上の XRP または RLUSD、あるいは Base 上の USDC で、x402 v2 を通じて決済されます。

認証モデル

MCP サーバーはステートレスなパススループロキシです。ウォレットを保持したり、ユーザーアカウントを管理したり、呼び出しの費用を補助したりすることはありません。

有料ツール（すべてのエンドポイントが $0.10 USD）の場合、呼び出し元は payment_signature 引数を指定します。これは、認証なしのプローブで返される要件のいずれかに一致する XRPL Payment に署名する、base64 でエンコードされた JSON 形式の x402 v2 決済ヘッダーです。サーバーはこれを、基盤となる呼び出しの PAYMENT-SIGNATURE ヘッダーとして転送します。

payment_signature を指定しない場合、基盤サービスは、決済方法として t54 ファシリテーター経由の XRPL 上の XRP と RLUSD、または Coinbase x402 ファシリテーター経由の Base mainnet 上の USDC の 3 つを提示する、実際の 402 Payment Required チャレンジを返します。MCP サーバーはこれを構造化エラーとして LLM に返すため、LLM は自身のウォレットが対応する決済方法を使って署名し、再試行できます。

運用者はサーバーに MCP_BYPASS_KEY を設定して、希望者向けのバイパスを有効にできます。呼び出し元はツール引数の _bypass_key に一致するキーを渡します。

ホスト型エンドポイントでは、呼び出し元ごとの、失敗した _bypass_key の試行回数に対する予算が、通常のリクエストとは別に、はるかに厳しく設定されています。1 分あたり 60 リクエストという上限は、フェアユースの制限であり、シークレットへのアクセス制御ではありません。予算は HTTP リクエストごとではなく推測 1 回ごとに消費されるため、JSON-RPC ボディをバッチしても上限を回避できません。予算を使い切った後に制限されるのは、実際に _bypass_key を含むリクエストだけです。tools/list、無料ツール、有料の x402 呼び出しは引き続き利用できます。バッチは最大 20 メッセージです。少なくとも 32 個のランダムバイトからなるキーを使用し、ポートフォリオ全体で 1 つのキーを共有するのではなく、サービスごとに範囲を限定するか、キーをローテーションしてください。バケットのキー設定は、TRUST_PROXY_HOPS がコンテナ前段にあるプロキシの実際の数と一致しているかどうかに依存します。.env.example を参照してください。

H-Seal レシートへの共同署名（任意）

サーバーに PROVIDER_IDENTITY（当社の CAIP-10。例：xrpl:0:r...）と PROVIDER_KEY_RAW（32 バイトの ed25519 シード、hex）を設定すると、すべてのツール応答に H-Seal プロバイダー証明が共同署名されます。この証明はツール結果の _meta.hSeal に含まれるため、呼び出し元は、改ざんを検知でき、独立して検証可能なインタラクションのオンチェーンレシートをアンカーできます。どちらかの変数が未設定の場合、この機能は無効となり、応答は変更されません。キーをハードコードしないでください。環境変数のみを使用してください。

バックエンドが自身の出力に共同署名する場合、MCP は 2 者間のレシート（_meta.hSealReceipt）も作成します。これは運用者キーで署名するため、信頼を与える XR-* バックエンドの CAIP-10 ID を HSEAL_ALLOWED_PROVIDERS に設定してください。この設定がない場合、指定した ID のキーを保持していることを証明できるプロバイダーはすべて受け入れられます。responseHash は常に配信されるボディから再計算されます。requestHash はプロバイダーが申告した値のままです（バックエンドは MCP が再現できない合成リクエストオブジェクトのハッシュを計算するため）。その旨は requestHashBasis で示されます。src/hSeal.ts と運用ランブックの docs/hseal-provider.md（現在の ID、ed25519 曲線に関する注意点、キーのローテーションと復旧方法）を参照してください。

使用方法

Claude Desktop からローカルで使用する（stdio）

Claude Desktop の設定（macOS では ~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "xrpl-utilities": {
      "command": "npx",
      "args": ["-y", "@xrpl-utilities/mcp", "--transport", "stdio"]
    }
  }
}

Claude Desktop を再起動します。44 個のツールが xrpl_ のプレフィックス付きで表示されます。Claude に「XR-Sentinel でウォレット rXXX をスキャンして」や「XRPL 上の権限付きドメインを一覧表示して」と依頼すると、ツール呼び出しが実行されます。

リモートで使用する（HTTP/SSE）

任意の MCP クライアントから https://mcp.xrpl-utilities.io/mcp に接続します。ツールの一覧も認証モデルも同じです。

実際に必要な支払い

すべての呼び出しで402チャレンジが発生しないようにするには、クライアントが次の条件を満たす必要があります。

1. サポートされているレールのうち、少なくとも1つでウォレットを保有していること： XRPを保有するXRPLウォレット（および任意のRLUSDトラストライン）、または BaseメインネットでUSDCを保有するEVMウォレット。
2. 有料ツールを呼び出すたびに、事前のプローブで取得したacceptsエントリーのいずれかに合致する支払いに署名すること。XRPLレールではXRPL Paymentを、BaseレールではEIP-3009 transferWithAuthorizationを使用します。
3. base64でJSONエンコードしたエンベロープをpayment_signatureとして渡すこと。

リファレンス実装： x402-xrplはXRPLレールに対応しています。公式のx402 パッケージ（[evm]エクストラ付き）はBaseのUSDCレールに対応しています。どちらも、あらゆる言語でテンプレートとして役立ちます。

ローカル開発

npm install
npm run build
node dist/index.js --transport http --port 8080
npm test          # builds, then runs the node:test suite in tests/

MCP Inspectorでhttp://localhost:8080/mcpを指定すると、ツール定義を対話的に確認できます。

STRICT_VALIDATE=1を設定すると、読み込めなかったマニフェストを警告ではなくドリフトとして扱います。デフォルトでは無効です。RailwayはON_FAILUREで再起動するため、起動時にフェイルクローズするとエンドポイントがクラッシュループに陥り、バックエンドの1つがコールド状態になるたびに、正常な残り5つのサービスのツールも停止してしまうためです。どちらの場合も、マニフェストが読み込まれなかったサービスにはNOT CHECKEDと記録されます。「確認できなかった」ことが「問題なし」と報告されることはありません。

リリース

リリースはタグのプッシュによって作成されます。Releaseワークフローはビルドを行い、package.jsonのバージョンがタグと一致することを検証してから、sigstoreの来歴情報付きでnpmに公開し、GitHub OIDCを通じて同じバージョンを公式MCP Registryにミラーリングします（追加のシークレットは不要です）。

npm version patch       # or minor / major
git push --follow-tags  # pushes commit + tag, CI does the rest

公開された成果物は、約90秒以内に npmjs.com/package/@xrpl-utilities/mcp に表示されます。来歴の証明は、パッケージページに緑色のチェックマークとして表示されます。MCP Registryのエントリーは、逆DNS名io.github.XRPL-Utilities/mcpで registry.modelcontextprotocol.io に登録されています。

ライセンス

MIT。ポートフォリオ全体はxrpl-utilities.comをご覧ください。