MCP x402 - Evidence-Backed Web Verification

MCP x402 — AI エージェント向けのエビデンスに基づくウェブ検証

エージェントが行動する前に、販売者、製品、オファー、ポリシー、または主張を検証します

AI エージェントに、一般公開されている HTTP(S) ページと、具体的な条件を1～10件指定します。verificar_condicoes ツールは、各条件についてエビデンスに基づく判定を返します。

• confirmado — ページが条件を明確に裏付けています。
• rejeitado — ページが条件と明確に矛盾しています。
• incerto — 利用可能なページのエビデンスでは不十分です。

各検証には、最終的なソース URL、ページタイトル、タイムスタンプ、条件ごとの説明、入手可能な場合は引用されたエビデンス、一意の verificationId、SHA-256 の pageHash が含まれます。

次の用途向けに設計されています

• AI による購入・調達エージェント
• 販売者、製品、オファーの検証
• 購入前のデューデリジェンス
• ポリシーや利用規約の確認
• 行動前にエビデンスが必要な商用自動化

シンプルな x402 統合

• 支払い前の無料の事前検証。
• Base メインネットで、検証1件あたり $0.05 USDC。
• アカウントやサブスクリプションは不要です。
• MCP と HTTP から利用できます。
• このリポジトリには、すぐに実行できる購入者が含まれています。
• 有料の HTTP と MCP のエンドポイントで Bazaar 検出メタデータが有効になっています。

ライブエンドポイント

• MCP：https://mcp-x402-production.up.railway.app/mcp
• 無料の MCP 事前検証：POST https://mcp-x402-production.up.railway.app/preflight/mcp
• 無料の検証事前確認：POST https://mcp-x402-production.up.railway.app/preflight/verify-conditions
• 有料の検証：POST https://mcp-x402-production.up.railway.app/verify-conditions
• ヘルスチェック：GET https://mcp-x402-production.up.railway.app/health

このサービスでは、analisar_url と consultar_ia を通じて、有料の公開 URL 分析と一般的な AI コンサルテーションも提供しています。

ライブサービス

• ベース URL：https://mcp-x402-production.up.railway.app
• ヘルスチェック：GET /health
• MCP エンドポイント：POST /mcp
• 有料 URL 分析：POST /analyze
• 価格：有料リクエスト1件あたり $0.05 USDC
• ネットワーク：Base メインネット（eip155:8453）

本番環境の状況

• Railway で本番環境にデプロイ済み
• x402 バージョン2の支払いフロー
• Base メインネットでの支払い（eip155:8453）
• 有料 HTTP エンドポイントが、Bazaar メタデータを含む有効な x402 チャレンジを返します
• MCP と HTTP での支払い、実行、決済、配信をオンチェーンで確認済み
• MCP Bazaar メタデータで、公開 HTTPS MCP サーバー URL を告知
• CDP のネイティブ MCP カタログへのインデックス登録は、確認済みとはまだしていません。上流での追跡先：coinbase/cdp-sdk#764

MCP ツール

判定の検証

verificar_condicoes — $0.05 USDC

エージェント向けの有料意思決定検証ツールです。

公開 URL と具体的な条件を 1 つ以上指定します。このページから抽出した証拠のみに基づいて、判定を返します。

• confirmado — ページが条件を明確に証明しています。
• rejeitado — ページが条件と明確に矛盾しています。
• incerto — ページに十分な証拠がありません。

各結果には、最終的なソース URL、ページタイトル、検証日時、条件ごとの説明、入手可能な場合は短い引用証拠が含まれます。

条件の例：

• 「このページは販売者を特定しています。」
• 「この商品はポルトガルで購入できます。」
• 「このページにはユーロ建ての価格が表示されています。」
• 「この文書には、サービスが x402 をサポートすると記載されています。」

次のアクションに進む前に、証拠に基づく判定が必要なエージェント向けに設計されています。

ツール	説明	価格
consultar_ia	プロンプトを OpenAI Responses API に送信します。	$0.02 USDC
analisar_url	公開 HTTP または HTTPS ページを取得して分析します。	$0.05 USDC
verificar_condicoes	公開ページ上の具体的な条件を検証し、証拠に基づく判定を返します。	$0.05 USDC

技術

• Node.js と TypeScript
• Express
• Model Context Protocol
• OpenAI Responses API
• x402 決済
• viem
• Cheerio
• Railway

セキュリティ

• Railway による HTTPS の提供
• Helmet セキュリティヘッダー
• 15 分間に 100 リクエストのレート制限
• 一意のリクエスト ID を含む構造化リクエストログ
• ホスト検証と Railway ヘルスチェックのサポート
• /v1/responses のみにアクセスできるよう制限された OpenAI API キー
• 環境ファイルとシークレットを Git の対象外に設定

環境変数

サーバー

変数	必須	説明
OPENAI_API_KEY	はい	OpenAI プロジェクトの API キーです。
OPENAI_MODEL	いいえ	OpenAI モデルです。デフォルトは gpt-5-mini です。
HOST	いいえ	リッスンするホストです。デフォルトは 0.0.0.0 です。
PORT	いいえ	リッスンするポートです。デフォルトは 3000 です。
RAILWAY_PUBLIC_DOMAIN	Railway	Railway によって自動的に設定されます。
PUBLIC_SERVICE_URL	いいえ	ディスカバリーメタデータで使用する、正規の公開 HTTPS オリジンです。Railway では RAILWAY_PUBLIC_DOMAIN から自動的に設定されます。フォールバックには本番 URL が使用されます。
OBSERVABILITY_SALT	推奨	再起動をまたいでソース／クライアントのフィンガープリントを仮名化する場合にのみ使用する、安定した秘密のソルトです。

ローカル購入者

変数	必須	説明
EVM_PRIVATE_KEY	はい	Base メインネットの購入者ウォレットの秘密鍵です。この値をコミットしないでください。
JOURNEY_ID	いいえ	再利用する既存の相関 ID です。指定しない場合は、購入者が生成します。

ローカルの .env.test ファイルの例：

EVM_PRIVATE_KEY=your_private_key_here

ローカル開発

依存関係をインストールします：

npm install

開発サーバーを起動します：

npm run dev

プロジェクトをビルドします：

npm run build

コンパイル済みのサーバーを起動します：

npm start

ヘルスチェック

ヘルスエンドポイントは公開されており、支払いは不要です：

curl https://mcp-x402-production.up.railway.app/health

Railway ログ診断

Railway は現在、過去の HTTP ログに対する --since は受け付けますが、 --until は拒否します。Windows PowerShell で、問題のあるフラグを使わずに 期間を指定してアプリケーションログと HTTP ログを書き出します。

.\scripts\export-railway-window.ps1 `
  -StartUtc "2026-08-22T16:31:22.401228537Z" `
  -EndUtc "2026-08-23T06:21:18.045229877Z" `
  -OutputPrefix "railway-diagnostic"

このスクリプトは下限時刻からログを取得し、ISO-8601 形式の文字列を序数順で比較して 上限の UTC 時刻をローカルで適用します。これにより、Railway のナノ秒精度の タイムスタンプが保持されます。生ログのキャプチャに加えて、期間を絞った app と http の NDJSON ファイルを書き出します。

期間を絞った両方のファイルを読み込み、すべての物理行を検証しながら分析します。

npm run logs:analyze -- \
  --since "2026-08-22T16:31:22.401228537Z" \
  --pretty \
  --out railway-diagnostic-report.json \
  railway-diagnostic-app.ndjson railway-diagnostic-http.ndjson

レポートには、ファイルごとの対象範囲、空行・有効な行・無効な行の数、 タイムスタンプの範囲、Diogo-*、RailwayHealthcheck、既知のプローブや インデクサー、および外部の可能性があるトラフィックの分類、ユーザージャーニーの再構築、 ファネルの離脱地点が含まれます。アプリケーションの railwayRequestId の値と Railway HTTP の requestId の値を結合し、HTTP の clientUa を処理します。 さらに、サーバーが生成したジャーニー ID をフィンガープリントと時間的な近さでグループ化し、 受理された正規化済みフィードバックのみを集計します。単独の 402 を購入意図とは見なさず、 リクエストのメタデータから人間の身元や動機を推測することもありません。

すぐに実行できる x402 購入クライアント

このリポジトリには、アプリケーションと AI エージェント向けの、すぐに実行できる購入クライアントが含まれています。MCP 購入クライアントは稼働中のサービスに接続し、x402 の支払い要件が Base メインネットの USDC および最大支払額 $0.05 に適合することを検証してから、支払いに署名し、同じツール呼び出しを再試行して、決済の受領証と結果を出力します。

購入クライアントをクローンして準備します。

git clone https://github.com/Diogoup26/mcp-x402.git
cd mcp-x402
npm install

プロジェクトのルートにローカルの .env.test ファイルを作成します。

EVM_PRIVATE_KEY=0xYOUR_64_HEX_CHARACTER_PRIVATE_KEY

.env.test をコミットしたり、秘密鍵を公開したりしないでください。

プロジェクトをビルドします。

npm run build

次のコマンドは、Base メインネットで実際の x402 支払いを承認します。

• consultar_ia：$0.02 USDC
• analisar_url：$0.05 USDC
• verificar_condicoes：$0.05 USDC

HTTP URL 分析

npm run analyze -- "https://example.com" "Summarize this page."

HTTP 判定の検証

npm run verify -- "https://example.com" "The page identifies the seller."

MCP URL 分析

npm run mcp:analyze -- "https://example.com" "Summarize this page."

MCP AI コンサルテーション

npm run mcp:consult -- "Reply only with: MCP OK"

MCP 判定の検証

npm run mcp:verify -- "https://example.com" "The page identifies the seller."

MCP の支払いが成功すると、次の内容が出力されます。

• PAGAMENTO MCP: success
• 決済の受領証
• ツールの応答

MCP 購入クライアントは秘密鍵を出力せず、次のいずれかに該当する支払いを拒否します。

• Base メインネット上の支払いではない。
• 設定された Base USDC コントラクトを使用していない。
• $0.05 USDC を超える。

機械可読な支払い継続手順

GET /.well-known/x402 のディスカバリードキュメントと、成功したすべての無料 事前確認レスポンスには、完全な継続手順が公開されます。互換性のあるエージェントは、 最初の未払いリクエストの後に何をすべきかを推測する必要がなくなります。

1. 無料の事前確認を実行し、その x-journey-id を保持します。
2. 支払い署名を付けずに、検証済みのリクエストを送信します。
3. payment-required の要件を読み取り、検証します。
4. 期待されるネットワーク、資産、金額、受取人のみを承認します。
5. x402 支払いペイロードを付けて、同一のリクエストを再試行します。
6. 配信と決済の受領証の両方を検証します。

REST のメタデータは @x402/fetch を、MCP のメタデータは @x402/mcp を 推奨します。有料レスポンスも x-payment-instructions を通じてディスカバリー手順に リンクします。さらに、登録済みの payment および help リレーションを持つ RFC 8288 の Link ヘッダーも公開します。これにより、汎用 HTTP エージェントは、プロジェクト固有の ヘッダーに依存せず、同じ機械可読な継続手順と任意のフィードバック経路を 検出できます。このフローでは、秘密鍵、Railway または GitHub の認証情報、 OpenAI のキーを要求することはありません。

変換に関する任意のフィードバック

すべての有料 HTTP または MCP レスポンスでは、x-feedback-endpoint と、正規化された理由、ステージ、インテントとして許可されている値が通知されます。無料の事前確認レスポンスには、同じ情報が feedback ブロックに含まれます。フィードバックは POST /feedback に送信され、自由記述は含まず、秘密鍵、プロンプト、URL、ページの内容、決済ペイロードが含まれることはありません。

3 つの購入クライアントで指定できる値は次のとおりです。

--feedback-reason <research_only|no_wallet|unsupported_network|insufficient_funds|spending_not_authorized|price|insufficient_value|integration_error|other>
--feedback-stage <discovery|preflight|payment|execution|delivery>
--feedback-intent <research|analyze_page|verify_conditions|general_question|evaluate_service|other>

--feedback-stage を指定せずに --feedback-reason を指定した場合、ステージは payment が既定値となり、購入クライアントは決済を承認しません。HTTP の購入クライアントはまず署名されていない 402 チャレンジを受け取り、明示的なフィードバックを送信して終了します。MCP の購入クライアントは無料の事前確認後に終了し、ウォレットなしで明示的なフィードバックを送信します。

例：支払いをせずに、価格が評価を中止する要因になったことを報告します。

npm run analyze -- "https://example.com" "Summarize this page." --feedback-reason price --feedback-intent evaluate_service

配信完了後に明示的なフィードバックを送信するには、そのステージを選択します。

npm run mcp:consult -- "Reply only with: MCP OK" --feedback-reason other --feedback-stage delivery --feedback-intent general_question

購入クライアントが自動送信するのは integration_error のみです。対象となるのは、ディスカバリー／事前確認の失敗、HTTP 5xx の結果、有料 MCP ツールのエラー、決済後に決済完了のレシートが見つからない場合など、客観的に検出できる技術的な失敗に限られます。price、research_only、no_wallet、その他の人間的または商業的な動機を推測することはありません。

制御されたスモークテスト（支払いなし）

デプロイ後、ディスカバリー、事前確認、OpenAPI のフィードバック契約、正規化されたフィードバックの送信、HTTP 402 チャレンジとフィードバックヘッダー、HTTP メソッドの処理、MCP の初期化、ツールのディスカバリー、MCP x402 チャレンジを検証します。

npm run build
npm run smoke

別のデプロイ先を対象にするには、SERVICE_URL を使用します。このテストでは永続的な x-journey-id を 1 つ使用し、User-Agent: Diogo-Smoke/1.2.9 を送信します。また、MCP x402 チャレンジが type=mcp と正しい toolName を指定した公開 HTTPS エンドポイントを通知することを検証し、決済の作成や署名は行いません。

3 つの決済購入クライアントは、有料リクエストの前にディスカバリーと無料の事前確認を行うようになり、一連の処理を通じて同じ永続的なジャーニー ID を使用します。既存のジャーニーを再利用するには JOURNEY_ID を設定します。設定しない場合、各購入クライアントがジャーニーを作成して表示します。さらに、MCP の購入クライアントは、署名する前に、通知された価格、Base USDC、Base mainnet、設定済みのサービス受取人がそれぞれ正確に一致することを求めます。

ファネルの可観測性

サーバーは、MCP ツールの試行、x402 チャレンジ、決済の検証、実行、決済完了、最終的なツールの結果について、構造化イベントを出力します。ツールの引数や決済ペイロードは記録しません。決済完了のログには公開ネットワークとトランザクション識別子が含まれるため、完了した購入の集計と重複排除が可能です。

拒否された MCP リクエストには、メソッド、コンテンツタイプ、Accept、JSON-RPC の形式、SDK のエラー分類など、安全なプロトコル診断情報が含まれます。すべてのイベントには、利用可能な場合、リクエストおよびジャーニーの相関フィールドが含まれます。既知の有料ツールへの呼び出しが決済ラッパーに到達しなかった場合は、mcp_pre_payment_rejection も出力されます。このイベントは、無効なメソッド、コンテンツタイプ、JSON-RPC エンベロープ、引数、トランスポート／プロトコルによる拒否、またはハンドラーに到達しなかったその他のケースに分類されます。引数の値と決済ペイロードは決して記録されません。OpenAI の使用状況イベントには、同じリクエスト、ジャーニー、クライアント、ソースの相関情報が引き継がれます。Railway の X-Railway-Request-Id、エッジ POP、リクエスト開始時刻も記録されます。一方、クライアントソースのフィンガープリントには Railway の安定した X-Real-IP 値を使用し、OBSERVABILITY_SALT で仮名化します。

デプロイ

main ブランチは Railway に接続されています。プッシュが成功するたびに新しいデプロイが実行されます。Railway では次のように設定されています。

npm run build
npm start

デプロイのヘルスチェックパスは /health です。

ライセンス

ISC