Skip to main content
Glama
reciprocal-ruler-mcp
by hwcho310

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.

Tools

Tool

Price

What it does

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).

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:

  1. 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.

  2. Pay and retry: produce the signed payment payload with an x402-capable client (the x402 Python SDK, x402-fetch / x402-axios for Node, or a Coinbase CDP / AgentKit wallet) and pass it back in the tool's payment_header argument. 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 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://reciprocla-ruler-x402.onrender.com",
        "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"]
    }
  }
}

Configuration

Environment variable

Default

Purpose

RULER_API_BASE

https://reciprocla-ruler-x402.onrender.com

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.

Available Tools

3 tools
ruler_quote_lockReciprocal Ruler - quote lock (x402 paid)A
Idempotent

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)A
Idempotent

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 reconciliationA
Read-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

    A4.1/5.0

    Scored across 3 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Settlement 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 * Li
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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