reciprocal-ruler-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@reciprocal-ruler-mcp Reconcile a 220,000 KRW trade that only settled 180,000 with a 22,000 holdback"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
reciprocal-ruler-mcp
An MCP (Model Context Protocol) server that gives any MCP-capable agent — Claude Desktop, Claude Code, Cursor, or your own client — a settlement oracle for agent-to-agent transactions.
When two AI agents fail to agree on what must be proven before money moves, Reciprocal Ruler
acts as the third party: it locks the agreed terms into a deterministic quote_hash, then judges
the settlement afterwards (SETTLED_OK, COMPENSATED, PENDING_RECONCILIATION) and compensates
shortfalls out of the agreed holdback. The service is paid per call with
x402 in USDC on Base — no account, no API key, no invoice.
API: https://reciprocla-ruler-x402.onrender.com · OpenAPI docs:
/docsFree trial: 3 evaluation calls per client, no payment, no signup
Standard library only — the server has no third-party dependencies
Tools
Tool | Price | What it does |
| free (3 calls/client) | Runs the real reconciliation engine and returns the judgment, so you can evaluate it before paying. Not written to the audit ledger. |
| $0.05 | Locks the terms both agents agreed on and returns a deterministic |
| $0.25 | Idempotent settlement judgment recorded in an append-only audit ledger; retries with the same |
Amounts are KRW integers. A reconciliation compares expected_amount_krw with
actual_settled_krw and uses holdback_krw as the compensation pool:
{
"expected_amount_krw": 220000,
"actual_settled_krw": 180000,
"holdback_krw": 22000,
"event_type": "POST_TRADE_REFUND"
}→ {"status": "COMPENSATED", "compensated_krw": 22000, "uncovered_krw": 18000, "credit_delta": -17}
event_type is POST_TRADE_REFUND (a refund or shortfall after the trade) or
HALF_OPEN_TIMEOUT (an unfinished settlement at timer expiry — such a shortfall is left
PENDING_RECONCILIATION, never auto-compensated).
Related MCP server: hive-mcp-barter
How the paid calls work
This MCP server holds no wallet and signs nothing. On a paid tool the call happens in two steps:
First call (no
payment_header) returns the HTTP 402 x402 challenge, decoded for you: scheme, network, USDC asset, amount in atomic units and USDC,payTo, timeout, plus what to do next.Pay and retry: produce the signed payment payload with an x402-capable client (the
x402Python SDK,x402-fetch/x402-axiosfor Node, or a Coinbase CDP / AgentKit wallet) and pass it back in the tool'spayment_headerargument. The same call then returns HTTP 200.
Example payment summary from a 402 response:
{
"status": "PAYMENT_REQUIRED",
"payment_summary": {
"x402_version": 2,
"scheme": "exact",
"network": "eip155:8453",
"network_name": "Base mainnet (eip155:8453)",
"asset_name": "USDC",
"amount_atomic": "50000",
"amount_usdc": "0.050000",
"pay_to": "0x…",
"resource_url": "https://reciprocla-ruler-x402.onrender.com/v1/quote-lock"
},
"how_to_pay": ["…"]
}Install
The package is not published on PyPI yet, so install it from this folder:
pip install . # console script `reciprocal-ruler-mcp`
pip install -e ".[dev]" # editable, with pytest, for developmentNothing outside the Python standard library is pulled in. Either install path gives you the
reciprocal-ruler-mcp console script, and python -m reciprocal_ruler_mcp works as well. The
server speaks MCP over stdio.
Connect a client
Claude Desktop
claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows:
%APPDATA%\Claude\):
{
"mcpServers": {
"reciprocal-ruler": {
"command": "python3",
"args": ["-m", "reciprocal_ruler_mcp"],
"env": {
"RULER_API_BASE": "https://reciprocla-ruler-x402.onrender.com",
"RULER_TRIAL_CLIENT_ID": "my-agent-01"
}
}
}
}Claude Code
claude mcp add reciprocal-ruler -- python3 -m reciprocal_ruler_mcpCursor
~/.cursor/mcp.json — same mcpServers shape as the Claude Desktop example above.
See examples/ for ready-to-copy files.
Run without installing
The server is a single standard-library module, so a checkout works directly:
{
"mcpServers": {
"reciprocal-ruler": {
"command": "python3",
"args": ["/absolute/path/to/src/reciprocal_ruler_mcp/server.py"]
}
}
}Configuration
Environment variable | Default | Purpose |
|
| API base URL (point it at a local or self-hosted instance if you run one). |
| unset | Sent as |
|
| Per-request timeout. The free hosting tier sleeps when idle, so the first call of a session may need a warm-up; the client retries once on a network failure. |
Every tool also accepts trial_client_id (ruler_trial_reconcile) and payment_header
(the paid tools) as arguments, which override the environment defaults for that call.
Protocol
initialize (protocol versions 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07),
tools/list, tools/call, ping, and the standard notifications. Diagnostics go to stderr;
stdout carries JSON-RPC frames only.
Tool failures come back as a normal result with isError: true and a JSON body explaining the
case (PAYMENT_REQUIRED, TRIAL_EXHAUSTED, VERSION_MISMATCH, INVALID_ARGUMENTS,
API_UNREACHABLE), so an agent can recover instead of crashing.
Test
pip install -e ".[dev]"
pytest -qtests/test_protocol.py starts the real server as a subprocess against a local mock of the API
and drives a full JSON-RPC exchange — initialize → tools/list → tools/call — including the
402 payment path, the trial quota, and error handling, all offline.
scripts/live_smoke.py calls the live public API with the tools (free trial only; it never
spends money) to check a deployment end to end. scripts/sdk_interop_check.py connects with the
official MCP Python SDK client (pip install mcp) to confirm the stdio server works with a real
client implementation, not only with raw frames.
License
MIT. The service behind it is operated as Reciprocal Ruler; the API terms are whatever the endpoint itself reports at request time.
Available Tools
3 toolsruler_quote_lockReciprocal Ruler - quote lock (x402 paid)AIdempotent
Lock the trade terms the two agents agreed on and get a deterministic quote_hash both sides can cite later. Costs $0.05 USDC on Base, paid with x402. Without a payment this tool returns the HTTP 402 payment challenge decoded into Base USDC instructions; pay it with an x402 wallet and pass the signed payload back as payment_header to complete the call. If the two agents run different rule versions the call is refused with VERSION_MISMATCH (409) and nothing is charged.
Inputs: terms (required), buyer_id (required), supplier_id (required), buyer_version (required), +2 more.
ruler_reconcileReciprocal Ruler - settlement reconciliation (x402 paid)AIdempotent
Idempotent settlement reconciliation recorded in an append-only audit ledger. Costs $0.25 USDC on Base via x402; without payment it returns the decoded payment challenge and Base USDC instructions. Reusing the same idempotency_key makes a retry return the original judgment instead of charging again, so always pass the key your first attempt used. Judgment is one of SETTLED_OK, COMPENSATED, PENDING_RECONCILIATION.
Inputs: idempotency_key (required), actual_settled_krw (required), expected_amount_krw (required), tx_id, +4 more.
ruler_trial_reconcileReciprocal Ruler - free trial reconciliationARead-only
Run a settlement reconciliation between two AI agents for free (up to 3 calls per client). Compares the expected amount with what actually settled and returns a deterministic judgment: SETTLED_OK, COMPENSATED (shortfall covered from the holdback), or PENDING_RECONCILIATION (half-open timeout, left pending). Use it to evaluate whether Reciprocal Ruler fits your agent-to-agent transaction flow before paying. Amounts are KRW integers.
Inputs: actual_settled_krw (required), expected_amount_krw (required), tx_id, event_type, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The tools are largely distinct, separating the initial quoting process from two different types of reconciliation. The primary overlap is between the two reconciliation functions, but their purpose (trial vs. official settlement) is clearly differentiated by their descriptions.
The tools follow a highly consistent naming convention using snake_case and a clear prefix (ruler_). The structure (action_focus) is maintained across all three entries.
For a specialized system managing the settlement lifecycle between AI agents, three tools are well-scoped and provides excellent coverage of the core necessary actions. It is neither too sparse nor overly bloated.
The set covers the core workflow: locking terms, testing the settlement process, and performing the final settlement. While it lacks tools for initiating the initial trade, it covers the necessary transactional milestones.
Maintenance
Related MCP Connectors
Neutral acceptance and signed agent-delivery verification over MCP + x402 USDC on Base.
x402 pay-per-call APIs over MCP, settled in USDC on Base for autonomous agents and developers.
Deterministic MCP utilities, validation, evidence verification, and x402 commerce on Base.
USDC/x402 agent marketplace. Verified Base mainnet pilot, testnet and public enrollment.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceSettlement rails for AI labor — USDC escrow on Base Mainnet, 1% protocol fee, designed for autonomous agents. 10 MCP tools covering the full escrow lifecycle: * Quoting calldata for create-intent, submit-proof, release-funds (broadcast gated) * Single-call x402 payment binding (replaces the 5-step x402 dance with one HMAC-signed POST) * Server-side reputation from on-chain event scan * LiMIT
- AlicenseNot gradedqualityDmaintenanceAn outbound arbitrage agent for 402-enabled MCP endpoints that probes, counter-offers, and settles USDC on Base L2, automating margin arbitrage without human intervention.MIT
- AlicenseNot gradedqualityDmaintenanceMulti-party escrow and settlement for autonomous agent transactions with x402 micropayments and dispute resolution on Base, Ethereum, or Solana.MIT
- AlicenseNot gradedqualityCmaintenanceEnables agents to access production-grade paid MCP tools with real on-chain x402 v2 settlement, including EVM wallet risk scoring, payload normalization, and facilitator discovery, all discoverable via Bazaar-compatible metadata.MIT