
reciprocal-ruler-mcp
io.github.hwcho310/reciprocal-ruler-mcp
Settlement oracle for AI-agent trades: lock a quote, reconcile shortfalls via holdback.
Documentation
reciprocal-ruler-mcp
Using n8n instead of an MCP client?
examples/n8n/has an importable quote-lock → reconcile workflow. Using Claude Code?examples/claude-code/has a ready-to-copySKILL.mdandPreToolUseverification hook. Need a quick human CSV/TSV check? Open https://reciprocal-ruler-x402.vercel.app/app.
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://reciprocal-ruler-x402.vercel.app · OpenAPI docs:
/docs - Free 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 |
|---|---|---|
ruler_trial_verify_math | free (3 calls/client) | Free trial of the deterministic arithmetic check (MATCHED, SHORTFALL, OVERPAID). |
ruler_verify_math | $0.01 | Ultra-low-cost deterministic arithmetic check (expected_amount vs actual_amount with optional tolerance). |
ruler_trial_reconcile | 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. |
ruler_quote_lock | $0.05 | Locks the terms both agents agreed on and returns a deterministic quote_hash they can cite later. |
ruler_reconcile | $0.25 | Idempotent settlement judgment recorded in an append-only audit ledger; retries with the same idempotency_key return the original result instead of charging again. |
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).
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://reciprocal-ruler-x402.vercel.app/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 development
Nothing 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://reciprocal-ruler-x402.vercel.app",
"RULER_TRIAL_CLIENT_ID": "my-agent-01"
}
}
}
}
Claude Code
claude mcp add reciprocal-ruler -- python3 -m reciprocal_ruler_mcp
Cursor
~/.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"]
}
}
}
One-click install (MCPB bundle)
Every release also ships a .mcpb bundle, the package format Claude Desktop and other
hosts open in one click (Linux, macOS, Windows):
python3 scripts/build_mcpb.py # -> dist/reciprocal-ruler-mcp.mcpb
Or take the bundle from the latest release: https://github.com/hwcho310/reciprocal-ruler-mcp/releases/latest/download/reciprocal-ruler-mcp.mcpb
The bundle needs python3 on the machine and nothing else — the server has no dependencies.
Registries
| Registry | Entry |
|---|---|
| Official MCP Registry | io.github.hwcho310/reciprocal-ruler-mcp (published from server.json by .github/workflows/publish-mcp.yml on a v* tag) |
| Glama | https://glama.ai/mcp/servers/hwcho310/reciprocal-ruler-mcp |
Configuration
| Environment variable | Default | Purpose |
|---|---|---|
RULER_API_BASE | https://reciprocal-ruler-x402.vercel.app | API base URL (point it at a local or self-hosted instance if you run one). |
RULER_TRIAL_CLIENT_ID | unset | Sent as X-Trial-Client so your 3 free calls follow this agent id instead of the shared IP address. Recommended behind a NAT or shared proxy. |
RULER_TIMEOUT_SECONDS | 90 | 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 -q
tests/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.
https://github.com/hwcho310/reciprocal-ruler-mcp/releases/download/v0.1.0/reciprocal-ruler-mcp.mcpb# mcpb: https://github.com/hwcho310/reciprocal-ruler-mcp/releases/download/v0.1.0/reciprocal-ruler-mcp.mcpb