presidio-hardened-x402-mcp

presidio-hardened-x402-mcp

x402 向けの決済前セーフティゲートです。エージェントは署名前に screen_payment_metadata(...)、check_payment_policy(...)、check_payment_replay(...) を呼び出し、メタデータや資金がエージェントのホストから外部に送信される前に、PII、予算超過、重複決済を検出します。

presidio-hardened-* ツールキットファミリーの一部です。presidio-hardened-x402 ライブラリを薄くラップした MCP（Model Context Protocol）アダプターで、親ライブラリの 0.13.x（presidio-hardened-x402>=0.13.0,<0.14.0）に固定されています。0.13.0 は、署名付き決定エビデンスに必要な制御の状態を NOT_EVALUATED として記録できるようになった最初の親ライブラリのバージョンです。また、セキュリティ上の最低基準である、パーセントエンコードされた PII の秘匿化バイパスを修正した 0.11.1 の修正も含まれています。

このツールの目的

x402 によるエージェント決済では、説明、メモ、クエリ文字列パラメーターなど、ユーザーが入力した自由形式のテキストが、加盟店やファシリテーターにそのまま送られることがよくあります。LLM エージェントがそのテキストを生成すると、ユーザーが共有するつもりのなかった PII が含まれる可能性があります。加盟店がそれをログに記録した後は、保持するかどうかは加盟店の判断であり、あなたの管理下にはありません。

この MCP サーバーは、決済がエージェントのホストから外部に送信される前に、デフォルトで拒否する小規模なゲートをエージェントに提供します。3 つのツールで、親ライブラリの安定した決済前制御である PII の秘匿化、支出ポリシー、リプレイ検出を利用できます。0.3.0 以降、各決定は、第三者がオフラインで検証できる署名付き payment-decision@1 レコードとして出力することもできます（署名付き決定エビデンスを参照）。これらのツールは、決済実行およびエンドポイント安全性を提供する MCP サーバー（x402station、Coinbase x402、Sardis など）と連携するように設計されています。一方、親ライブラリのその他の機能、すなわち受信エビデンスの evidence-ref@1 検証、v0.9.1 の SLO ブローカー、v0.10.0 の settlement-ref@1 財務バインディング、v0.11.0 の CapabilityEnforcer は、後に MCP ツールで明示的にラップされない限り、Python ライブラリにとどまります。

インストールと設定

Python ≥ 3.10 が必要です。PyPI で配布されています。グローバルにインストールする必要のない uvx による実行を推奨します。

Claude Desktop / Claude Code

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）またはお使いのプラットフォームに対応する設定ファイルに追加します。

{
  "mcpServers": {
    "presidio-x402": {
      "command": "uvx",
      "args": ["presidio-hardened-x402-mcp"]
    }
  }
}

Cursor / Windsurf / Continue

設定形式は同じです。すべての MCP ホストで command / args / env を利用できます。設定ファイルの場所については、お使いのエディターの MCP サーバー向けドキュメントを参照してください。

環境変数

すべて省略可能です。デフォルトでは、クォータなし、ネットワークなし、PII の保存なしで、設定不要のプロセス内モードが有効になります。

変数	用途	デフォルト
PRESIDIO_X402_MCP_MODE	regex（セットアップ不要）または nlp（[nlp] エクストラと spaCy モデルが必要）	regex
PRESIDIO_X402_MCP_MAX_PER_CALL_USD	1 回の支払いの最大 USD 額（ポリシーゲート）	未設定 → 上限なし
PRESIDIO_X402_MCP_DAILY_LIMIT_USD	ローリングウィンドウ内の最大 USD 額（ポリシーゲート）	未設定 → 上限なし
PRESIDIO_X402_MCP_PER_ENDPOINT_JSON	エンドポイントごとの上限。例：'{"api.foo.com": 5.00}'	未設定
PRESIDIO_X402_MCP_WINDOW_SECONDS	1 日あたりの上限に適用するローリングウィンドウ	86400
PRESIDIO_X402_MCP_AGENT_ID	監査レコードに記録するラベル	未設定
PRESIDIO_X402_MCP_REPLAY_TTL	フィンガープリントキャッシュの TTL（秒）	300
PRESIDIO_X402_MCP_REDIS_URL	リプレイ状態の保存先として、メモリ内の代わりに Redis を使用	未設定
PRESIDIO_X402_MCP_AUDIT_PATH	追記専用の JSON-L 監査ログのパス。無効にする場合は省略	未設定
PRESIDIO_X402_MCP_LOG_LEVEL	DEBUG / INFO / WARNING / ERROR	INFO
PRESIDIO_X402_MCP_REMOTE_BASE_URL	ツール 1 の HTTP プロキシモードを有効化 — 「モード」を参照してください。https:// が必要です。通常の http:// はループバックの場合のみ受け付け、それ以外では起動を拒否します	未設定
PRESIDIO_X402_MCP_REMOTE_API_KEY	リモートスクリーニングサービスの API キー	未設定
PRESIDIO_X402_FINGERPRINT_KEY	プロセス間のリプレイ検出に使用する 32 バイトの 16 進数キー	未設定（プロセスごと）
PRESIDIO_X402_CHAIN_KEY	プロセス間の監査チェーン HMAC に使用する 32 バイトの 16 進数キー	未設定（プロセスごと）
PRESIDIO_X402_REQUIRE_FINGERPRINT_KEY	リプレイキーがない、または無効な場合に起動を失敗させる	未設定
PRESIDIO_X402_REQUIRE_CHAIN_KEY	監査チェーンキーがない、または無効な場合に起動を失敗させる	未設定
PRESIDIO_X402_MCP_EVIDENCE_KEY_FILE	判定署名キーを格納するファイル（推奨。環境変数のキーより優先されます）	未設定
PRESIDIO_X402_EVIDENCE_KEY	判定署名キー（親ライブラリの変数）：64 文字の 16 進数 Ed25519 秘密鍵、または HMAC シークレット	未設定
PRESIDIO_X402_MCP_DECISION_PATH	署名付き payment-decision@1 レコード用の追記専用 JSON-L ファイル	未設定
PRESIDIO_X402_MCP_EVIDENCE_ALGORITHM	ed25519 または hmac-sha256	ed25519
PRESIDIO_X402_MCP_EVIDENCE_SIGNER	署名者の識別情報。トラストストアのキー検証ツールが検索に使用します	presidio-hardened-x402-mcp
PRESIDIO_X402_MCP_EVIDENCE_KEY_ID	各レコードに記録する任意のキー ID（キーのローテーション用）	未設定
PRESIDIO_X402_MCP_REQUIRE_EVIDENCE_KEY	署名付きエビデンスが完全に設定され、キーで署名できない場合に起動を失敗させる	未設定

プロセス間キーは openssl rand -hex 32 で生成できます。

ツール

screen_payment_metadata(resource_url, description, reason, entities?)

支払いメタデータ内の PII を検出してマスキングします。副作用はありません — 繰り返し呼び出しても安全です。

// Input
{
  "resource_url": "https://api.foo.com/u/[email protected]",
  "description": "monthly fee for [email protected]",
  "reason": ""
}

// Output
{
  "redacted_resource_url": "https://api.foo.com/u/<EMAIL_ADDRESS>",
  "redacted_description": "monthly fee for <EMAIL_ADDRESS>",
  "redacted_reason": "",
  "entities_found": [
    { "entity_type": "EMAIL_ADDRESS", "field": "resource_url", "count": 1 },
    { "entity_type": "EMAIL_ADDRESS", "field": "description", "count": 1 }
  ],
  "mode": "in_process"
  // + "decision_ref": "<64 hex>" when signed decision evidence is enabled
}

entities（任意の Presidio エンティティ型のリスト）を指定すると、検出対象を許可リストに絞り込めます。フィールド長の上限は、親の 0.7.x を通じて安定している screening-api のワイヤーコントラクトに準拠しています：resource_url ≤ 2048、description ≤ 4096、reason ≤ 4096 文字。上限を超える入力では ValueError が発生します。

check_payment_policy(resource_url, amount_usd, prior_decision_refs?)

支出ポリシーのゲートです。成功時に支出を記録します — 決済の直前に、必ず1回だけ呼び出してください。チェック成功後に実際の決済を行わないと、期間が切り替わるまで日次上限の台帳に実際より多く記録されます。

URLは最初にスクリーニングされ、ポリシーエンジンに渡されるのはマスキング済みのURLのみです。そのため、生のURLが親のログに残ることはありません。エンドポイントごとの上限はマスキング済みのURLに基づいて照合されるため、設定したエンドポイントのプレフィックスにはPIIを含めないでください。スクリーニングに失敗した場合、支出を記録せずにゲートが拒否します。

// Input
{ "resource_url": "https://api.foo.com/x", "amount_usd": 1.50 }

// Output (allowed)
{ "allowed": true }

// Output (denied — over per-call limit of $5.00)
{ "allowed": false, "reason": "...", "limit_usd": 5.00, "amount_usd": 6.00 }

署名付きエビデンスが有効な場合、両方の出力に decision_ref も含まれます。prior_decision_refs（任意、最大8件）は、このサーバーが以前に返した、この決済に関する参照を署名付きレコードに関連付けます。通常は screen_payment_metadata が返した参照を指定します。このプロセスが発行していない参照は、支出が記録される前に拒否されます。

check_payment_replay(resource_url, pay_to, amount, currency, deadline_seconds, prior_decision_refs?)

正規化されたフィールドのHMAC-SHA256フィンガープリントによる重複決済ゲートです。成功時にフィンガープリントを記録します — 決済の直前に、必ず1回だけ呼び出してください。

精度を維持するため、amount は文字列です。プロセス間の検知には PRESIDIO_X402_FINGERPRINT_KEY（および任意で PRESIDIO_X402_MCP_REDIS_URL）が必要です。それ以外の場合、各MCPサーバープロセスは独自のインメモリストアを使用します。

// Input
{
  "resource_url": "https://api.foo.com/x",
  "pay_to": "0xabc...",
  "amount": "1.50",
  "currency": "USDC",
  "deadline_seconds": 1700000000
}

// Output (first seen)
{ "is_replay": false, "fingerprint": "29aaf60f..." }

// Output (duplicate within TTL)
{ "is_replay": true, "fingerprint": "29aaf60f..." }

decision_ref と prior_decision_refs の動作は check_payment_policy と同じです。

署名付き決定エビデンス

監査ログ（PRESIDIO_X402_MCP_AUDIT_PATH）はHMACチェーンで保護されます。PRESIDIO_X402_CHAIN_KEY を保持する者には改ざんを検知できますが、それ以外の者には検知できません。0.3.0以降、すべてのツールの決定（許可とブロックの両方）を、署名付きの payment-decision@1 レコードとして書き込むこともできます。このレコードは親ライブラリ（build_payment_decision_content、build_decision_evidence）が作成・署名し、公開鍵を持つ誰もが検証できます（verify_decision_ref）。監査ログも引き続き書き込まれます。レコードは監査ログと並行して保存され、監査ログの代わりにはなりません。

# One-time: an Ed25519 key pair for the signer (hex private key, 0600).
python - <<'PY'
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
sk = Ed25519PrivateKey.generate()
open("evidence.key", "w").write(sk.private_bytes_raw().hex())
print(sk.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw).hex())  # -> trust store
PY
chmod 600 evidence.key

"env": {
  "PRESIDIO_X402_MCP_EVIDENCE_KEY_FILE": "/etc/presidio/evidence.key",
  "PRESIDIO_X402_MCP_DECISION_PATH": "/var/log/presidio/x402-mcp-decisions.jsonl",
  "PRESIDIO_X402_MCP_REQUIRE_EVIDENCE_KEY": "1"
}

署名者名に対応する公開鍵をピン留めしたトラストストアを使用して、親ライブラリのCLIでオフライン検証できます。

echo '{"presidio-hardened-x402-mcp": {"alg": "ed25519", "public_key": "<public hex>"}}' > trust.json
python -m presidio_x402.decision_ref /var/log/presidio/x402-mcp-decisions.jsonl trust.json

鍵がない場合、サーバーは0.2.xとまったく同じように動作し、監査ログのみを記録します。また、署名付きエビデンスが無効であることを示すWARNINGログを起動時に1回出力します。PRESIDIO_X402_MCP_DECISION_PATH が設定されていない状態での鍵の指定、読み取れない鍵ファイル、または署名者に拒否された鍵はERRORログに記録され、エビデンスも無効になります。いずれの場合も起動を拒否するには、PRESIDIO_X402_MCP_REQUIRE_EVIDENCE_KEY=1 を設定してください。起動後に書き込みが失敗した場合はログに記録されますが、ゲートの判断はそのまま維持されます。決定の記録によって決定が覆ることはありません。

レコードに記録される内容。 payment-decision@1 には、常に5つすべての制御（pii → trusted_wallet → policy → replay → mpa）が含まれます。各レコードには、そのツールが実行した制御の実際の判定と、それ以外の制御の NOT_EVALUATED が記録されます。すべてのツールがURLをスクリーニングします（pii）。check_payment_policy は policy を追加し、check_payment_replay は replay を追加します。trusted_wallet と mpa はここでは評価されません。NOT_EVALUATED によって決定が失敗することも、合格が示されることもありません。そのため、制御のブロックだけを見れば、どのゲートが決定したかがわかります。決済ごとに1つの関連付けられたセットを作成するには、3つの参照を prior_decision_refs で連結します。

レコードに含まれない内容。 生の resource_url、description、reason は含まれません。記録されるのはURLのスキームとホスト、検出されたエンティティタイプのラベル、ハッシュ（ポリシーのスナップショット、リプレイのフィンガープリント、決済の詳細）のみです。ゲートは渡されたURL内のPIIを参照しますが、変更せずに渡すため、PII判定は PII_WARNED になります。screen_payment_metadata はマスキング済み文字列を返し、PII_REDACTED を記録します。MCPツールから参照できないフィールド（支払人のウォレット、ネットワーク、生の402オファー）は、unspecified / not-presented として記録されます。レコードにはケイパビリティチェーンの parents が含まれないため、ADR-0002のトップレベル parents フィールドは設定されません。

モード

インプロセス（デフォルト）。 MCP サーバーと同じプロセス内で、ローカルの presidio-hardened-x402 ライブラリをラップします。ネットワークも API キーもクォータも不要です。PII がエージェントのホストの外に出ることはありません。特別な理由がない限り、このモードを使用してください。

HTTP プロキシ。 PRESIDIO_X402_MCP_REMOTE_BASE_URL と PRESIDIO_X402_MCP_REMOTE_API_KEY の両方が設定されている場合、screen_payment_metadata は集中監査のため、設定されたホスト（例：https://screen.presidio-group.eu）の /v1/screen を呼び出します。認証／クォータ／ネットワークのエラー時には、構造化された { "error": "auth_error" | "rate_limit" | "unavailable", "detail": ..., "mode": "remote" } を返します。インプロセスに暗黙的にフォールバックすることはありません。ツール 2 と 3 は常にインプロセスで動作します。

組み合わせて利用する

支払い実行やエンドポイント安全性の MCP サーバーとともに、エージェントのフローに組み込めるよう設計されています。

agent intent: pay https://api.foo.com/x with 1.50 USDC
    │
    ├─ x402station    preflight(url)            ← is the ENDPOINT safe? (decoys, dead, traps)
    │
    ├─ presidio-x402  screen_payment_metadata   ← is the PAYLOAD safe? (PII)
    ├─ presidio-x402  check_payment_policy      ← within budget?
    ├─ presidio-x402  check_payment_replay      ← not a duplicate?
    │
    └─ pay()

screen_payment_metadata は読み取り専用で、どの位置に挟んでも安全です。ポリシーゲートとリプレイゲートは呼び出し時に状態を記録するため、支払いの直前に続けて実行してください。

これらのゲートに見えないもの、それはエージェントが作り出したリクエストボディです。 3 つのツールは 402 チャレンジのメタデータと支出をスクリーニングしますが、エージェントが POST ルートに送信するボディは確認しません。x402 と MPP のカタログを独自に測定した結果（probe402、MCRI #001、2026 年 9 月 1 日）、掲載されている POST ルート 8,056 件のうち 1,521 件（18.9%）で利用可能なリクエスト例が公開されておらず、そのうち 72% は壁の前で引き続き支払い可能な見積もりを返すことが分かりました。このようなルートは掲載済みで、価格設定済みですが、公開されたコントラクトから機械的に実行することはできません。ボディを合成して不足を補うエージェントは推測しており、推測したボディはユーザーデータがスクリーニングされずにリクエストへ入る場所です。方針として、カタログのエントリーにリクエスト例もスキーマもない場合は、402 の見積もりの段階で止めてその旨を提示し、壁を越えるためにボディを作り出さないでください。このルールはエージェントの指示に記載してください。これは、これらのツールが実行される前にエージェントが判断することです。

組み合わせたスニペット：事前チェック → スクリーニング → 支払い

エンドポイント安全性とペイロード安全性は独立したシグナルです。署名の前に両方を呼び出すのが本来の使い方です。2 つの MCP サーバーを並べて設定してください。

{
  "mcpServers": {
    "x402station":   { "command": "npx", "args": ["-y", "x402station-mcp"],
                       "env": { "AGENT_PRIVATE_KEY": "0x…" } },
    "presidio-x402": { "command": "uvx", "args": ["presidio-hardened-x402-mcp"] }
  }
}

支払いに署名する前のエージェントフロー（擬似コード。各ステップは 1 回の MCP ツール呼び出しです）。

# 1. endpoint safety: is the URL trustworthy? (x402station-mcp)
pf = preflight(url)
if not pf["ok"]:
    abort(reason=pf["warnings"])  # decoy / zombie / dead / price-trap

# 2. payload safety: redact PII before it leaves the host (presidio-x402)
s = screen_payment_metadata(resource_url=url, description=description, reason="")
url, description = s["redacted_resource_url"], s["redacted_description"]

# 3. spend gates: record-on-success, call exactly once each (presidio-x402)
if not check_payment_policy(url, amount_usd)["allowed"]:
    abort(reason="policy")
if check_payment_replay(url, pay_to, amount, currency, deadline_seconds)["is_replay"]:
    abort(reason="replay")

# 4. sign + pay
pay(url, amount, description=description)

2 つのサーバーは意図的に独立して開発されています。シグナルの相関性を低く保つことが重要です。事前チェックツールの完全な出力スキーマと警告カタログについては、x402station-mcp をご覧ください。

開発者向けの注意事項

• ログは stderr に出力されます（MCP クライアントは stderr を取得します）。stdout は JSON-RPC フレーム用に確保されています。
• このパッケージは薄いアダプターです。セキュリティロジックはすべて presidio-hardened-x402 にあります。エンティティタイプのカタログ、ポリシーのセマンティクス、エビデンス参照の検証、SLO ブローカー、監査チェーンの詳細については、そのドキュメントをお読みください。
• この MCP リリースでは、0.1.1 と同じ 3 つのツールを公開しています。0.3.0 では、これらのツールからの署名付き payment-decision@1 の出力と、2 つのゲートに対するオプションの prior_decision_refs 引数が追加されました。それ以外の親ライブラリの SLO／エビデンス／ケイパビリティの機能は MCP に昇格されていません。
• mcp-inspector --cli でテストする場合、数値のみの --tool-arg amount=1.50 は自動的に浮動小数点数へ変換され、スキーマで拒否されます。実際の MCP クライアントは適切な JSON 型を送信します。amount ツール引数は精度を維持するための文字列です。
• ローカル開発：uv venv && uv pip install -e ".[dev]" && pytest tests/。

ライセンス

MIT。LICENSE をご覧ください。

リンク

• このリポジトリ：https://github.com/presidio-v/presidio-hardened-x402-mcp
• イシュー：https://github.com/presidio-v/presidio-hardened-x402-mcp/issues
• 親ライブラリ：https://github.com/presidio-v/presidio-hardened-x402
• PyPI のライブラリ：https://pypi.org/project/presidio-hardened-x402/
• 要件：PRESIDIO-REQ.md
• セキュリティポリシー：SECURITY.md
• MCP 仕様：https://modelcontextprotocol.io
• x402：https://x402.org

---

SDLC

このリポジトリは、PRESIDIO 強化ファミリー SDLC のオープンソース基準に準拠しています （レポート · PDF）。 評価対象の管理策と未解決のギャップは、 適用性マトリックスの該当行をご覧ください。

ロードマップ（今後12か月）

• 現在／進行中 — OpenSSF Best Practices のシルバー認定と、7を超えるScorecardスコアを目指します： ガバナンス関連ドキュメント、Banditと併用する実際のCodeQLジョブ、最小権限のワークフロートークン、 設定バリデーターのAtherisによるファジングです。残りの指摘事項をSECURITY-AUDIT.mdで解消します。
• 次の段階 — CI依存関係をハッシュで固定します。できればこのリポジトリだけでなく、ファミリー全体での変更とします。
• その後 (評価中) — ビルドの来歴情報を含む署名付きリリース、安定化に合わせたMCP仕様の追跡、エージェントからの需要が追加の機能を正当化する場合に、親ライブラリのcapability-grant@1による適用機能を4つ目のツールとして公開します。

ガバナンス、アーキテクチャ、セキュリティ

• ガバナンス — 役割、意思決定プロセス、メンテナーになる方法です。
• アーキテクチャ — コンポーネント、信頼境界、主要な処理経路です。
• 保証ケース — セキュリティ上の主張と、それぞれを裏付ける証拠です。
• セキュリティポリシー — サポート対象バージョンと、脆弱性の報告方法です。
• 貢献方法 — レビュー基準、テスト方針、検証コマンドです。
• 安定性の保証 — パブリックAPIに該当するものと、変更されない可能性のあるものです。