x207

io.github.x207-labsPublished by GitHub account x207-labsv0.0.6Updated Nov 5, 2026

Read-only tools for x207 circles on NEAR: members, epochs, clearing simulation, listings.

VerifiedStreamable HTTPWeb executableDatabasesFinanceBusiness & Commerce

Overview

AI-generated overview

Read-only MCP server for x207 mutual-credit circles on NEAR: circle rules and members, member positions, epoch results, clearing simulations, marketplace…

What you can do
  • Read a circle's record, rules and member list
  • Inspect one member's status, stake, debt and credit limit
  • Report an epoch's phase, deadlines, cleared ratio and settlements
  • Dry-run a netting proposal against the contract
  • Search marketplace listings and look up one order or a filtered list of orders
When to use it
Useful when an assistant needs to inspect an x207 circle on NEAR — checking who is a member, what a member owes or may borrow, how an epoch settled, or what is offered on the circle's marketplace — without any signing capability.
Requirements
Runs as a local npm package (Node 22.22.2 or newer) over stdio, or as a Streamable HTTP endpoint. Requires the X207_CIRCLE_CONTRACT environment variable; optional X207_CIRCLE_ID, X207_RPC_URL, X207_BACKEND_URL and X207_TIMEOUT_MS. Network access to a NEAR RPC endpoint is needed, and the read API base URL is required for the listing and order tools.
Before you install
By default only read tools are exposed and no key is held. Write tools exist only on stdio and only when X207_MCP_WRITE=1 is set; they can sign vouchers and send transactions, spending credit and USDT, and the join, settle and claim tools need a full-access NEAR key (X207_AGENT_NEAR_KEY) with X207_ALLOW_FULL_ACCESS_KEY=1, so use a dedicated account with a small balance. Keys come from environment variables such as X207_AGENT_VOUCHER_KEY and must not be committed.

Installation

In SourceWeft

  1. Open x207 in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.x207-labs%2Fx207-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "x207": {
      "type": "http",
      "url": "https://mcp.x207.boxd.sh/mcp"
    }
  }
}

README

@x207/mcp

An MCP server for x207, the mutual-credit settlement layer for x402 agent payments on NEAR. It lets a model such as Claude read a circle: its rules and members, one member's position and limit, the result of an epoch, a clearing proposal checked by the contract, the marketplace, and one order.

Status: version 0.0.1, pre-release. By default the server has read tools only: it signs nothing, sends nothing and holds no key. The eight write tools exist only on stdio, only when you turn them on, and only behind the guards below. Node 22.22.2 or newer.

The six read tools

ToolWhat it answersReads
x207_circle_overviewThe circle and its rules, and its memberscontract views get_circle, get_params; read API GET /members (the view list_members when there is no read API)
x207_member_inspectOne member: status, stake, position, credit limitread API GET /members/{account} and GET /members/{account}/limits (the views member and limit when there is no read API)
x207_epoch_reportOne clearing epoch, the current one by default: phase, deadlines, cleared ratio and settlementscontract view get_epoch; read API GET /epochs/{n}, GET /epochs/{n}/metrics, GET /epochs/{n}/settlements (the view list_positions when there is no read API)
x207_simulate_clearingWhether a proposed clearing is valid, and what it would clearcontract view simulate_clearing
x207_search_listingsMarketplace listings, filtered by account, asset type and classread API GET /listings (needs the read API)
x207_order_statusOne service order, or a list of orders by party and statusread API GET /orders/{hash} and GET /orders (needs the read API)

All six are marked readOnlyHint: true. Credit amounts are decimal strings in the smallest unit (6 decimals). A tool that fails returns an error result with a short reason, and a part of an answer that could not be read (for example a read API that is down) is reported in warnings while the rest is returned. A result longer than 100,000 characters is cut and says so.

Configuration

Everything comes from the environment. No variable holds a secret.

VariableMeaning
X207_CIRCLE_CONTRACTRequired. The circle contract account, for example x207-v013.testnet.
X207_CIRCLE_IDThe circle id in the read API paths. Default agents-main.
X207_RPC_URLNEAR JSON-RPC endpoints, comma separated, tried in order. Default: https://rpc.testnet.fastnear.com then https://rpc.testnet.near.org for a .testnet contract, otherwise the mainnet endpoints of @x207/core. An endpoint that fails or answers 429 hands over to the next.
X207_BACKEND_URLBase URL of the x207 read API, for example http://127.0.0.1:8080. Optional; without it x207_search_listings and x207_order_status explain what is missing and the other tools answer from the contract.
X207_TIMEOUT_MSTimeout of one RPC or read API call. Default 10000.

Use with Claude Desktop (stdio)

Add the server to claude_desktop_config.json (Claude Desktop) or .cursor/mcp.json (Cursor). npx fetches the package the first time, so there is nothing to install:

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

Use version 0.0.2 or newer: 0.0.1 was published without its x207-mcp command. To keep a copy on your machine, npm install -g @x207/mcp and use "command": "x207-mcp" without args. From a checkout of the repository, build once with npm run build and point command at node with "args": ["/path/to/sdk/packages/mcp/dist/cli.js"]. Restart Claude Desktop, then ask for example: "Give me the overview of the x207 circle", "Inspect the member alice.x207-v013.testnet", or "Report epoch 1".

Write tools (stdio only, off by default)

Set X207_MCP_WRITE=1 and give the agent's account and keys in the environment. The HTTP server never has these tools, whatever the environment says.

ToolWhat it doesSigns withOff unless
x207_pay_requestFetches a URL; on an x207 402 it signs a credit voucher and repeats the request. The facilitator of the seller registers the voucher; this tool sends nothing to the chain.voucher keya voucher key
x207_list_offerSigns a listing (what the agent offers, what it seeks) and posts it to the marketplace book.voucher keya voucher key and X207_BACKEND_URL
x207_make_offerSigns an offer or a counter-offer (in_reply_to) on a listing and posts it.voucher keya voucher key and X207_BACKEND_URL
x207_accept_offerPreviews the acceptance at the backend, checks what the agent would pay, signs the bundle and posts the acceptance.voucher keya voucher key and X207_BACKEND_URL
x207_confirm_milestoneSigns a notice for a milestone of an order (confirmed, disputed, delivered, cancelled) and posts it.voucher keya voucher key and X207_BACKEND_URL
x207_joinJoins the circle and stakes USDT: join with the 0.35 NEAR storage deposit, then ft_transfer_call.NEAR keyX207_ALLOW_OUTFLOWS=1 and X207_ALLOW_FULL_ACCESS_KEY=1
x207_settlePays the residual the agent owes for an epoch (at most the amount due): ft_transfer_call with the settle message.NEAR keyX207_ALLOW_OUTFLOWS=1 and X207_ALLOW_FULL_ACCESS_KEY=1
x207_claimClaims what the agent is owed for an epoch, to its own account or its Intents balance: claim with 1 yoctoNEAR.NEAR keyX207_ALLOW_FULL_ACCESS_KEY=1

A tool whose key or switch is missing is not listed at all. The voucher key is an off-chain ed25519 key of the agent (ed25519:<base58>); it is not a NEAR access key. The NEAR key is an access key of the agent's account.

VariableMeaning
X207_MCP_WRITE1 turns the write tools on. Default: off.
X207_AGENT_ACCOUNTThe NEAR account of the agent, a member of the circle. Required with X207_MCP_WRITE=1.
X207_AGENT_VOUCHER_KEYVoucher secret key. Signs vouchers, listings, offers, acceptances and notices.
X207_AGENT_NEAR_KEYNEAR secret key of the agent account. Signs the transactions of x207_join, x207_settle and x207_claim only.
X207_MAX_SPEND_SESSIONMost the agent may commit in one run of the server, in credit units (6 decimals). Default 1000000 (1 credit).
X207_MAX_PRICE_PER_CALLMost one payment, offer or milestone may be. Default 100000 (0.1 credit).
X207_ALLOWED_COUNTERPARTIESComma separated accounts the agent may deal with. Empty: any active member of the circle.
X207_ALLOW_OUTFLOWS1 allows x207_join and x207_settle, which move USDT from the agent into the circle. Default off.
X207_ALLOW_FULL_ACCESS_KEY1 allows the NEAR key to be a full-access key. Default off.
X207_ALLOW_PRIVATE_URLS1 lets x207_pay_request fetch a URL on this machine or in a private network, for a seller you run yourself. Default off.

The guards

  1. Budget of the session. Every voucher signed, every payment an acceptance would make, every milestone confirmed and every stake or residual paid counts against X207_MAX_SPEND_SESSION. A commitment that does not fit is refused before it is signed; one that fails afterwards is given back.
  2. Price per call. An amount above X207_MAX_PRICE_PER_CALL is refused. The price in a 402 comes from the seller, so the server does not trust it: the check runs on the requirement before the voucher is signed.
  3. Risky tools are off. x207_join and x207_settle stay off until the operator sets X207_ALLOW_OUTFLOWS=1.
  4. Counterparties. The other party of a payment, offer, acceptance or milestone must be an active member of the circle (a contract view), must be in X207_ALLOWED_COUNTERPARTIES when that list is set, and is never the agent itself.
  5. Network. The URL given to x207_pay_request comes from a model, so it can come from a prompt injection. The tool refuses a URL whose host is, or resolves to, a loopback, private, link-local (the metadata service of a cloud machine), carrier-grade NAT, multicast or unspecified address, and names such as localhost, *.local and *.internal. It does not follow redirects (the answer says where a redirect points), gives each call 30 seconds, and reads at most 1 MiB of an answer. X207_ALLOW_PRIVATE_URLS=1 turns the address check off for a seller on your own machine.
  6. Keys. Keys come from the environment only. No result, error or log line contains a key: every text that leaves the server is scrubbed of the configured keys and of anything shaped like an ed25519 secret key. Before a tool sends a transaction the server reads the permission of the NEAR key (view_access_key). A function-call key cannot attach a deposit, and join, stake, settle and claim all attach one (NEAR protocol rule), so with a function-call key those tools refuse and send nothing. With a full-access key they run only if X207_ALLOW_FULL_ACCESS_KEY=1; use a dedicated agent account with a small balance. The tools that sign with the voucher key send no transaction, so they do not need a NEAR key at all.

Also: the backend returns the terms of a bundle together with their hash, and x207_accept_offer refuses when the hash does not match the terms; x207_make_offer refuses when the listing the book returns does not hash to the hash that was asked for.

Security limit: the balance of the agent account is the largest possible loss

A NEAR deposit cannot be attached by a function-call key, so the tools that send one (x207_join, x207_settle, x207_claim) need a full-access key of the agent account. A full-access key can do anything the account can do, and none of the guards above limits what a stolen or misused key does outside this server. So use a dedicated agent account that holds only what the agent may lose: whatever NEAR and USDT sit on that account is the most that can be lost. The session budget and the price cap protect against a model that misbehaves; they do not protect against someone who has the key. Leave X207_ALLOW_FULL_ACCESS_KEY unset, and the three tools off, if the agent only needs to pay, list, offer, accept and confirm: those tools sign with the voucher key and never need a NEAR key.

Claude Desktop with the write tools

json
{  "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"      }    }  }}

Keep the keys out of any file you commit. Then ask for example: "List a translation service for 0.05 credit", "Pay https://seller.example/api/summarize", or "Confirm milestone 1 of order …".

Use over Streamable HTTP

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

The endpoint is POST http://127.0.0.1:3207/mcp. It is stateless (no session) and serves only the read tools, so it can be shown to anybody who can already read the contract and the read API. GET /healthz answers 200. It listens on 127.0.0.1 unless --host says otherwise; put a reverse proxy with TLS and a rate limit in front of it before you expose it. On a loopback address it serves only the Host names of the loopback (127.0.0.1, localhost, [::1]), so a web page cannot reach it through DNS rebinding; behind a proxy set X207_ALLOWED_HOSTS=mcp.example.org (comma separated) to serve exactly those names.

To try it with the MCP Inspector:

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

Use as a library

ts
import { configFromEnv, createX207McpServer } from "@x207/mcp";import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const server = createX207McpServer(configFromEnv(), "stdio"); // "http" gives the read tools onlyawait server.connect(new StdioServerTransport());

Example output (real data)

Run against the circle x207-v013.testnet (contract views from the testnet RPC) and a local read API (backend) that served the read model of that circle with its three demo accounts. The tool results below are real; long fields (signatures, hashes of the order spec) are left out and marked by the keys that remain.

x207_member_inspect with {"account": "x207-demo-seller.testnet"}:

json
{  "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 with {"account": "x207-demo-seller.testnet", "limit": 1}:

json
{  "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 with the hash of the order of x207-demo-buyer.testnet:

json
{  "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"    }  ]}

Without a read API the same server still answers x207_circle_overview, x207_member_inspect, x207_epoch_report and x207_simulate_clearing from the contract alone: on x207-v013.testnet x207_circle_overview returns member_count 24 and the rules (epoch_length 600, fees 10 and 5 bps, prune_delay_epochs 2), and x207_epoch_report for epoch 1 shows the phase finalized with 210 edges and 15 participants.

Safety

  • The read tools call contract views and GET requests only; there is no code path in them that signs, sends or changes anything. The write tools are described above and are off by default.
  • Inputs are checked before any call: account ids, hashes, amounts as integer strings, at most 300 edges for a simulation, at most 200 items per page.
  • Path segments are encoded, so an input cannot reach another endpoint of the read API.
  • A circle on testnet reads from a testnet endpoint by default.

Develop

bash
npm run build          # from the repository root of sdknpx vitest run packages/mcp

The tests play the NEAR RPC and the read API with a mock fetch, run the HTTP transport on a local port, and drive the built x207-mcp over stdio (that test skips itself when dist is not built).

License

Apache-2.0

Source: packages/mcp/README.md at commit ea71aab

Tools

6

x207_circle_overview

x207 circle overview

Start here: the circle itself, i.e. its record and rules (get_circle, get_params) plus a page of its members (read API GET /members, or the contract view list_members when no read API is set). Use x207_member_inspect for one member in detail and x207_epoch_report for one epoch. Returns {contract, circleId, circle, params, members, membersSource, warnings}; amounts are strings in the smallest unit (6 decimals). If the members part fails it shows up in `warnings` and the rest is still returned; an unreachable contract RPC is an error.

Parametersmembers_limitmembers_status

x207_member_inspect

Inspect a circle member

One member of the circle: status, stake, outstanding debt and credit limit (read API GET /members/{account} and /limits, or the contract views member and limit when no read API is set). Use it after x207_circle_overview has shown the account ids, or before paying a member; for epoch-level amounts use x207_epoch_report. Returns {account, member, limits|limit, source, warnings}. An account that is not a member is an error ("not a member" or a 404 from the read API); a failed limits lookup is only a warning.

Parametersaccountrequired

x207_epoch_report

Epoch report (report 207)

One epoch of the circle: its phase and deadlines from the contract (get_epoch), and from the read API the summary, the metrics (cleared ratio: the share of debt that netting removed, so only the net cash moves) and the settlements, i.e. who owes whom what in cash. Use it after an epoch closed; use x207_simulate_clearing to test a proposal before it is submitted. Returns {epoch, contract, summary, metrics, settlements, source, warnings}. An epoch that does not exist is an error; if the read API is down the contract record is still returned, with the failures in `warnings`.

Parametersepochsettlements_limit

x207_simulate_clearing

Simulate a clearing proposal

Dry run of a netting proposal: asks the contract (view simulate_clearing) whether the edges would be accepted for an epoch and how much debt they would cancel. Use it to check a proposal before a solver submits it; to see what a finished epoch actually netted use x207_epoch_report. Returns {epoch, edgeCount, result}. An invalid proposal (unknown member, amount above the debt, wrong epoch phase) comes back as an error text from the contract. Read-only, sends nothing.

Parametersedgesrequiredepochrequired

x207_search_listings

Search marketplace listings

Find offers on the circle's marketplace (read API GET /listings): what an account offers and what it wants. Use it to discover who sells a service; for an order that already exists use x207_order_status. Returns {items, nextCursor}; pass nextCursor as `cursor` for the next page. No match gives an empty list, not an error. Needs the read API (X207_BACKEND_URL) and fails with a clear message without it.

ParameterslimitcursorstatusaccountwantTypeofferTypewantClassofferClass

x207_order_status

Order status

Orders of the circle's marketplace (read API GET /orders). With a hash: one order with its parties, budget, milestones and status. Without a hash: a page of orders, filtered by party and status. Use x207_search_listings to find offers before an order exists. An unknown hash is an error ("no order ... in circle"); an empty list is a normal result. Needs the read API (X207_BACKEND_URL).

Parametershashlimitpartycursorstatus

Version history

3
  1. v0.0.6LatestNov 5, 2026
  2. v0.0.5Nov 5, 2026
  3. v0.0.3Nov 4, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts