x207

@x207/mcp

x402 エージェント決済向けの、NEAR 上の相互クレジット決済レイヤーである x207 用の MCP サーバーです。Claude などのモデルから、サークルのルールとメンバー、あるメンバーのポジションと限度額、エポックの結果、コントラクトによる検証済みの清算提案、マーケットプレイス、および 1 件の注文を確認できます。

ステータス：バージョン 0.0.1、プレリリースです。デフォルトでは、サーバーにあるのは読み取り専用ツールのみです。署名も送信も行わず、キーも保持しません。8 つの書き込みツールは stdio でのみ利用でき、有効にした場合に限り、以下のガードによって保護されます。Node 22.22.2 以降が必要です。

6 つの読み取りツール

ツール	確認できる内容	読み取り先
x207_circle_overview	サークル、そのルール、およびメンバー	コントラクトビュー get_circle、get_params；読み取り API GET /members（読み取り API がない場合はビュー list_members）
x207_member_inspect	1 人のメンバー：ステータス、ステーク、ポジション、クレジット限度額	読み取り API GET /members/{account}、GET /members/{account}/limits（読み取り API がない場合はビュー member、limit）
x207_epoch_report	1 つの清算エポック。デフォルトでは現在のエポック：フェーズ、期限、清算比率、決済	コントラクトビュー get_epoch；読み取り API GET /epochs/{n}、GET /epochs/{n}/metrics、GET /epochs/{n}/settlements（読み取り API がない場合はビュー list_positions）
x207_simulate_clearing	提案された清算が有効かどうか、および清算される内容	コントラクトビュー simulate_clearing
x207_search_listings	アカウント、アセットの種類、クラスで絞り込んだマーケットプレイスの出品	読み取り API GET /listings（読み取り API が必要です）
x207_order_status	1 件のサービス注文、または当事者とステータスで絞り込んだ注文一覧	読み取り API GET /orders/{hash}、GET /orders（読み取り API が必要です）

6 つすべてに readOnlyHint: true が設定されています。クレジット額は、最小単位（小数点以下 6 桁）で表した 10 進数文字列です。ツールが失敗すると、簡潔な理由を含むエラー結果を返します。また、読み取れなかった回答の一部（たとえば、停止中の読み取り API）は warnings で報告され、残りは返されます。結果が 100,000 文字を超える場合は切り詰められ、その旨が示されます。

設定

設定はすべて環境変数から取得します。シークレットを保持する変数はありません。

変数	意味
X207_CIRCLE_CONTRACT	必須。 サークルのコントラクトアカウント。例：x207-v013.testnet。
X207_CIRCLE_ID	読み取り API のパスで使うサークル ID。デフォルトは agents-main です。
X207_RPC_URL	NEAR JSON-RPC エンドポイント。カンマ区切りで、記載順に試します。デフォルト：コントラクトが .testnet の場合は https://rpc.testnet.fastnear.com、次に https://rpc.testnet.near.org。それ以外の場合は @x207/core の mainnet エンドポイントです。エンドポイントが失敗するか 429 を返した場合は、次のエンドポイントに切り替わります。
X207_BACKEND_URL	x207 読み取り API のベース URL。例：http://127.0.0.1:8080。任意です。設定しない場合、x207_search_listings と x207_order_status は不足している内容を説明し、その他のツールはコントラクトから回答します。
X207_TIMEOUT_MS	1 回の RPC または読み取り API 呼び出しのタイムアウト。デフォルトは 10000 です。

Claude Desktop で使用する（stdio）

サーバーを claude_desktop_config.json（Claude Desktop）または .cursor/mcp.json（Cursor）に追加します。初回は npx がパッケージを取得するため、インストールは不要です。

{
  "mcpServers": {
    "x207": {
      "command": "npx",
      "args": ["-y", "@x207/mcp"],
      "env": {
        "X207_CIRCLE_CONTRACT": "x207-v013.testnet",
        "X207_BACKEND_URL": "http://127.0.0.1:8080"
      }
    }
  }
}

バージョン 0.0.2 以降を使用してください。0.0.1 は x207-mcp コマンドなしで公開されています。マシンにコピーを保持するには、npm install -g @x207/mcp を実行し、args を使わずに "command": "x207-mcp" を指定します。リポジトリのチェックアウトから実行する場合は、npm run build で一度ビルドし、"args": ["/path/to/sdk/packages/mcp/dist/cli.js"] を指定して、command に node を設定します。Claude Desktop を再起動し、たとえば「x207 サークルの概要を教えて」「メンバー alice.x207-v013.testnet を確認して」「エポック 1 を報告して」と尋ねてください。

書き込みツール（stdio のみ、デフォルトではオフ）

X207_MCP_WRITE=1 を設定し、エージェントのアカウントとキーを環境変数で指定してください。HTTP サーバーでは、環境変数の設定にかかわらず、これらのツールは利用できません。

ツール	機能	署名に使用	利用可能になる条件
x207_pay_request	URL にアクセスします。x207 の 402 が返された場合、クレジットバウチャーに署名してリクエストを再試行します。販売者のファシリテーターがバウチャーを登録します。このツールがチェーンに何かを送信することはありません。	バウチャーキー	バウチャーキー
x207_list_offer	出品内容（エージェントが提供するもの、求めるもの）に署名し、マーケットプレイスのブックに投稿します。	バウチャーキー	バウチャーキーと X207_BACKEND_URL
x207_make_offer	出品に対するオファーまたはカウンターオファー（in_reply_to）に署名し、投稿します。	バウチャーキー	バウチャーキーと X207_BACKEND_URL
x207_accept_offer	バックエンドで承諾内容をプレビューし、エージェントの支払い額を確認してから、バンドルに署名し、承諾を投稿します。	バウチャーキー	バウチャーキーと X207_BACKEND_URL
x207_confirm_milestone	注文のマイルストーン（confirmed、disputed、delivered、cancelled）に関する通知に署名し、投稿します。	バウチャーキー	バウチャーキーと X207_BACKEND_URL
x207_join	サークルに参加し、USDT をステークします。0.35 NEAR のストレージデポジットを伴う join の後、ft_transfer_call を実行します。	NEAR キー	X207_ALLOW_OUTFLOWS=1 と X207_ALLOW_FULL_ACCESS_KEY=1
x207_settle	エポックに対してエージェントが支払う残額（未払い額を上限とします）を支払います。settle メッセージを指定して ft_transfer_call を実行します。	NEAR キー	X207_ALLOW_OUTFLOWS=1 と X207_ALLOW_FULL_ACCESS_KEY=1
x207_claim	エポックに対してエージェントが受け取るべき額を、自身のアカウントまたは Intents の残高に請求します。1 yoctoNEAR を指定して claim を実行します。	NEAR キー	X207_ALLOW_FULL_ACCESS_KEY=1

必要なキーまたはスイッチが設定されていないツールは、一覧に表示されません。バウチャーキーはエージェントのオフチェーン ed25519 キー（ed25519:<base58>）で、NEAR アクセスキーではありません。NEAR キーはエージェントのアカウントのアクセスキーです。

変数	意味
X207_MCP_WRITE	1 にすると書き込みツールが有効になります。デフォルト：オフ。
X207_AGENT_ACCOUNT	サークルのメンバーであるエージェントの NEAR アカウントです。X207_MCP_WRITE=1 の場合に必須です。
X207_AGENT_VOUCHER_KEY	バウチャーの秘密鍵です。バウチャー、出品、オファー、承諾、通知に署名します。
X207_AGENT_NEAR_KEY	エージェントのアカウントの NEAR 秘密鍵です。x207_join、x207_settle、x207_claim のトランザクションにのみ署名します。
X207_MAX_SPEND_SESSION	サーバーの 1 回の実行中にエージェントが確約できる上限額（クレジット単位、小数点以下 6 桁）です。デフォルトは 1000000（1 クレジット）です。
X207_MAX_PRICE_PER_CALL	1 回の支払い、オファー、またはマイルストーンの上限額です。デフォルトは 100000（0.1 クレジット）です。
X207_ALLOWED_COUNTERPARTIES	エージェントが取引できるアカウントをカンマ区切りで指定します。空の場合、サークルの有効なメンバーすべてが対象です。
X207_ALLOW_OUTFLOWS	1 にすると、エージェントからサークルへ USDT を移動する x207_join と x207_settle が許可されます。デフォルト：オフ。
X207_ALLOW_FULL_ACCESS_KEY	1 にすると、NEAR キーにフルアクセスキーを使用できます。デフォルト：オフ。
X207_ALLOW_PRIVATE_URLS	1 にすると、自身で運用する販売者向けに、このマシン上またはプライベートネットワーク内の URL を x207_pay_request で取得できます。デフォルト：オフ。

ガード機能

1. セッション予算。 署名したすべてのバウチャー、acceptance によって行われるすべての支払い、確認したすべてのマイルストーン、支払ったすべてのステークまたは残額が、X207_MAX_SPEND_SESSION に加算されます。予算内に収まらないコミットメントは署名する前に拒否され、署名後に失敗した場合は返金されます。
2. 呼び出しごとの価格。 X207_MAX_PRICE_PER_CALL を超える金額は拒否されます。402 に含まれる価格は販売者が提示したものなので、サーバーはこれを信頼しません。バウチャーに署名する前に、要件に対してチェックを実行します。
3. リスクの高いツールは無効です。 オペレーターが X207_ALLOW_OUTFLOWS=1 を設定するまで、x207_join と x207_settle は無効のままです。
4. 取引相手。 支払い、オファー、受諾、またはマイルストーンの相手方は、サークルの（コントラクトビュー上の）アクティブメンバーであり、X207_ALLOWED_COUNTERPARTIES が設定されている場合はそのリストに含まれている必要があります。また、エージェント自身を相手方にすることはできません。
5. ネットワーク。 x207_pay_request に指定する URL はモデルから渡されるため、プロンプトインジェクションによって指定される可能性があります。このツールは、ホストがループバック、プライベート、リンクローカル（クラウドマシンのメタデータサービス）、キャリアグレード NAT、マルチキャスト、または未指定のアドレスである URL、またはそれらのアドレスに解決される URLを拒否します。また、localhost、*.local、*.internal などの名前も拒否します。リダイレクトには従わず（応答でリダイレクト先を伝えます）、各呼び出しに30秒の制限を設け、応答は最大1 MiBまで読み込みます。自分のマシン上の販売者に対しては、X207_ALLOW_PRIVATE_URLS=1 を設定するとアドレスチェックが無効になります。
6. 鍵。 鍵は環境変数からのみ取得されます。結果、エラー、ログのいずれにも鍵は含まれません。サーバーから外部に出るテキストはすべて、設定された鍵と ed25519 の秘密鍵の形式に一致する文字列を除去します。ツールがトランザクションを送信する前に、サーバーは NEAR 鍵の権限を確認します（view_access_key）。ファンクションコールキーではデポジットを添付できず、join、stake、settle、claim はすべてデポジットを添付します（NEAR プロトコルの規則）。そのため、ファンクションコールキーを使う場合、これらのツールは拒否され、何も送信されません。フルアクセスキーを使う場合、ツールが実行されるのは X207_ALLOW_FULL_ACCESS_KEY=1 が設定されているときだけです。残高の少ない専用のエージェントアカウントを使用してください。バウチャーキーで署名するツールはトランザクションを送信しないため、NEAR 鍵は必要ありません。

また、バックエンドはバンドルの条件とそのハッシュを返します。x207_accept_offer は、ハッシュが条件と一致しない場合に拒否します。x207_make_offer は、book が返すリスティングのハッシュが指定されたハッシュと一致しない場合に拒否します。

セキュリティ上の制限：エージェントアカウントの残高が最大損失額です

ファンクションコールキーでは NEAR デポジットを添付できないため、デポジットを送信するツール（x207_join、x207_settle、x207_claim）には、エージェントアカウントのフルアクセスキーが必要です。フルアクセスキーではアカウントで可能なすべての操作を実行できます。また、上記のガード機能は、このサーバーの外部で盗まれた鍵や悪用された鍵の操作を制限しません。そのため、エージェントが失ってもよい資産だけを保有する専用のエージェントアカウントを使用してください。そのアカウントにある NEAR と USDT が、損失し得る最大額です。セッション予算と価格上限は、モデルの不適切な動作から保護するためのものであり、鍵を持つ人物から保護するものではありません。エージェントが支払い、出品、オファー、受諾、確認だけを行う場合は、X207_ALLOW_FULL_ACCESS_KEY を設定せず、3つのツールを無効にしてください。これらのツールはバウチャーキーで署名し、NEAR 鍵を必要としません。

書き込みツールを使用する Claude Desktop

{
  "mcpServers": {
    "x207-agent": {
      "command": "x207-mcp",
      "env": {
        "X207_CIRCLE_CONTRACT": "x207-v013.testnet",
        "X207_BACKEND_URL": "http://127.0.0.1:8080",
        "X207_MCP_WRITE": "1",
        "X207_AGENT_ACCOUNT": "agent.x207-v013.testnet",
        "X207_AGENT_VOUCHER_KEY": "ed25519:…",
        "X207_MAX_SPEND_SESSION": "500000",
        "X207_MAX_PRICE_PER_CALL": "50000"
      }
    }
  }
}

コミットするファイルに鍵を含めないでください。そのうえで、たとえば「0.05 クレジットで翻訳サービスを出品して」「https://seller.example/api/summarize に支払って」「注文 … のマイルストーン1を確認して」と依頼してください。

Streamable HTTP 経由で使用する

X207_CIRCLE_CONTRACT=x207-v013.testnet X207_BACKEND_URL=http://127.0.0.1:8080 x207-mcp --http --port 3207

エンドポイントは POST http://127.0.0.1:3207/mcp です。ステートレス（セッションなし）で、読み取りツールのみを提供するため、コントラクトと読み取り API をすでに参照できる人なら誰にでも公開できます。GET /healthz は 200 を返します。--host で別の指定がない限り、127.0.0.1 でリッスンします。公開する前に、TLS とレート制限を設定したリバースプロキシを前段に配置してください。ループバックアドレスでは、ループバックの Host 名（127.0.0.1、localhost、[::1]）のみを提供するため、DNS リバインディングを利用してウェブページからアクセスすることはできません。プロキシの背後で実行する場合は、X207_ALLOWED_HOSTS=mcp.example.org（カンマ区切り）を設定すると、指定したホスト名のみを提供します。

MCP Inspector で試すには：

npx @modelcontextprotocol/inspector --cli http://127.0.0.1:3207/mcp --transport http --method tools/list

ライブラリとして使用する

import { configFromEnv, createX207McpServer } from "@x207/mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = createX207McpServer(configFromEnv(), "stdio"); // "http" gives the read tools only
await server.connect(new StdioServerTransport());

出力例（実データ）

サークル x207-v013.testnet（テストネット RPC からのコントラクトビュー）と、そのサークルの読み取りモデルを提供するローカル読み取り API（backend）に対して実行します。このサークルにはデモアカウントが 3 つあります。以下のツール結果は実データです。長いフィールド（署名、注文仕様のハッシュ）は省略し、残っているキーで示しています。

x207_member_inspect を {"account": "x207-demo-seller.testnet"} で実行：

{
  "account": "x207-demo-seller.testnet",
  "member": {
    "account": "x207-demo-seller.testnet",
    "status": "active",
    "stake": "100000000",
    "limit": "80000000",
    "outstandingDebt": "0",
    "headroom": "80000000",
    "joinedAt": "2026-11-04T04:25:29Z"
  },
  "limits": {
    "items": [
      {
        "epoch": null,
        "oldLimit": "0",
        "newLimit": "80000000",
        "status": "active",
        "reason": "stake",
        "blockHeight": 276145725
      }
    ]
  },
  "source": "read API",
  "warnings": []
}

x207_search_listings を {"account": "x207-demo-seller.testnet", "limit": 1} で実行：

{
  "items": [
    {
      "listingHash": "6eb11d3068ba7e5f84503d9d454242e891fedd676ffd1e03324d4889a304fa41",
      "account": "x207-demo-seller.testnet",
      "offer": {
        "assetType": "near-rpc:access",
        "assetClass": "B",
        "quantity": 1,
        "value": "2000000"
      },
      "want": {
        "assetType": "usdc",
        "assetClass": "A",
        "quantity": 1,
        "value": "2000000"
      },
      "expiresAt": "2026-12-31T00:00:00Z",
      "status": "open"
    }
  ],
  "nextCursor": "eyJhIjoxfQ"
}

x207_order_status を x207-demo-buyer.testnet の注文の hash で実行：

{
  "orderHash": "332b9bddcc9e17578ba2e55b1fd7d8c0323f7a8225f4ebc03a83b7c0668840a3",
  "buyer": "x207-demo-buyer.testnet",
  "seller": "x207-demo-seller.testnet",
  "status": "open",
  "budget": "30000000",
  "unit": "credit",
  "decimals": 6,
  "milestones": [
    {
      "index": 1,
      "amount": "10000000",
      "dueAt": 1796947200,
      "status": "open"
    },
    {
      "index": 2,
      "amount": "20000000",
      "dueAt": 1797811200,
      "status": "open"
    }
  ]
}

読み取り API がなくても、同じサーバーはコントラクトのみを使用して x207_circle_overview、x207_member_inspect、x207_epoch_report、x207_simulate_clearing に引き続き応答します。x207-v013.testnet では、x207_circle_overview は member_count が 24、ルールが epoch_length 600、手数料 10 および 5 bps、prune_delay_epochs 2 であると返します。また、エポック 1 の x207_epoch_report は、フェーズが finalized で、エッジが 210、参加者が 15 であることを示します。

安全性

• 読み取りツールはコントラクトビューと GET リクエストのみを呼び出します。署名、送信、変更を行うコードパスはありません。書き込みツールについては上記で説明しており、デフォルトでは無効です。
• 呼び出しの前に入力を検証します。アカウント ID、ハッシュ、整数文字列としての金額、シミュレーションでは最大 300 エッジ、1 ページあたり最大 200 項目です。
• パスセグメントはエンコードされるため、入力によって読み取り API の別のエンドポイントにアクセスすることはできません。
• テストネット上のサークルは、デフォルトでテストネットのエンドポイントから読み取ります。

開発

npm run build          # from the repository root of sdk
npx vitest run packages/mcp

テストではモックの fetch を使って NEAR RPC と読み取り API を再現し、ローカルポートで HTTP トランスポートを実行して、ビルド済みの x207-mcp を stdio 経由で操作します（このテストは dist がビルドされていない場合、自動的にスキップされます）。

ライセンス

Apache-2.0