Skip to content
Back to search

reciprocal-ruler-mcp

MCP server for Reciprocal Ruler deterministic settlement oracle (x402 / Base USDC)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/hwcho310/reciprocal-ruler-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/hwcho310/reciprocal-ruler-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hwcho310--reciprocal-ruler-mcp/badge.svg)](/listings/hwcho310--reciprocal-ruler-mcp)

HTML

<a href="/listings/hwcho310--reciprocal-ruler-mcp"><img src="/api/listings/hwcho310--reciprocal-ruler-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 198 lines
  1. # reciprocal-ruler-mcp
  2. > Using n8n instead of an MCP client? [`examples/n8n/`](examples/n8n/) has an importable
  3. > quote-lock → reconcile workflow.
  4. An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server that gives any
  5. MCP-capable agent — Claude Desktop, Claude Code, Cursor, or your own client — a settlement
  6. oracle for agent-to-agent transactions.
  7. When two AI agents fail to agree on *what must be proven before money moves*, Reciprocal Ruler
  8. acts as the third party: it locks the agreed terms into a deterministic `quote_hash`, then judges
  9. the settlement afterwards (`SETTLED_OK`, `COMPENSATED`, `PENDING_RECONCILIATION`) and compensates
  10. shortfalls out of the agreed holdback. The service is paid per call with
  11. [x402](https://www.x402.org) in USDC on Base — no account, no API key, no invoice.
  12. - API: <https://reciprocal-ruler-x402.vercel.app> · OpenAPI docs: `/docs`
  13. - Free trial: **3 evaluation calls per client**, no payment, no signup
  14. - Standard library only — the server has **no third-party dependencies**
  15. ## Tools
  16. | Tool | Price | What it does |
  17. |---|---|---|
  18. | `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. |
  19. | `ruler_quote_lock` | $0.05 | Locks the terms both agents agreed on and returns a deterministic `quote_hash` they can cite later. |
  20. | `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. |
  21. Amounts are **KRW integers**. A reconciliation compares `expected_amount_krw` with
  22. `actual_settled_krw` and uses `holdback_krw` as the compensation pool:
  23. ```json
  24. {
  25. "expected_amount_krw": 220000,
  26. "actual_settled_krw": 180000,
  27. "holdback_krw": 22000,
  28. "event_type": "POST_TRADE_REFUND"
  29. }
  30. ```
  31. → `{"status": "COMPENSATED", "compensated_krw": 22000, "uncovered_krw": 18000, "credit_delta": -17}`
  32. `event_type` is `POST_TRADE_REFUND` (a refund or shortfall after the trade) or
  33. `HALF_OPEN_TIMEOUT` (an unfinished settlement at timer expiry — such a shortfall is left
  34. `PENDING_RECONCILIATION`, never auto-compensated).
  35. ## How the paid calls work
  36. This MCP server holds no wallet and signs nothing. On a paid tool the call happens in two steps:
  37. 1. **First call** (no `payment_header`) returns the HTTP 402 x402 challenge, decoded for you:
  38. scheme, network, USDC asset, amount in atomic units and USDC, `payTo`, timeout, plus what to do next.
  39. 2. **Pay and retry**: produce the signed payment payload with an x402-capable client
  40. (the `x402` Python SDK, `x402-fetch` / `x402-axios` for Node, or a Coinbase CDP / AgentKit
  41. wallet) and pass it back in the tool's `payment_header` argument. The same call then returns HTTP 200.
  42. Example payment summary from a 402 response:
  43. ```json
  44. {
  45. "status": "PAYMENT_REQUIRED",
  46. "payment_summary": {
  47. "x402_version": 2,
  48. "scheme": "exact",
  49. "network": "eip155:8453",
  50. "network_name": "Base mainnet (eip155:8453)",
  51. "asset_name": "USDC",
  52. "amount_atomic": "50000",
  53. "amount_usdc": "0.050000",
  54. "pay_to": "0x…",
  55. "resource_url": "https://reciprocal-ruler-x402.vercel.app/v1/quote-lock"
  56. },
  57. "how_to_pay": ["…"]
  58. }
  59. ```
  60. ## Install
  61. The package is not published on PyPI yet, so install it from this folder:
  62. ```bash
  63. pip install . # console script `reciprocal-ruler-mcp`
  64. pip install -e ".[dev]" # editable, with pytest, for development
  65. ```
  66. Nothing outside the Python standard library is pulled in. Either install path gives you the
  67. `reciprocal-ruler-mcp` console script, and `python -m reciprocal_ruler_mcp` works as well. The
  68. server speaks MCP over **stdio**.
  69. ## Connect a client
  70. ### Claude Desktop
  71. `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows:
  72. `%APPDATA%\Claude\`):
  73. ```json
  74. {
  75. "mcpServers": {
  76. "reciprocal-ruler": {
  77. "command": "python3",
  78. "args": ["-m", "reciprocal_ruler_mcp"],
  79. "env": {
  80. "RULER_API_BASE": "https://reciprocal-ruler-x402.vercel.app",
  81. "RULER_TRIAL_CLIENT_ID": "my-agent-01"
  82. }
  83. }
  84. }
  85. }
  86. ```
  87. ### Claude Code
  88. ```bash
  89. claude mcp add reciprocal-ruler -- python3 -m reciprocal_ruler_mcp
  90. ```
  91. ### Cursor
  92. `~/.cursor/mcp.json` — same `mcpServers` shape as the Claude Desktop example above.
  93. See [`examples/`](examples/) for ready-to-copy files.
  94. ### Run without installing
  95. The server is a single standard-library module, so a checkout works directly:
  96. ```json
  97. {
  98. "mcpServers": {
  99. "reciprocal-ruler": {
  100. "command": "python3",
  101. "args": ["/absolute/path/to/src/reciprocal_ruler_mcp/server.py"]
  102. }
  103. }
  104. }
  105. ```
  106. ### One-click install (MCPB bundle)
  107. Every release also ships a `.mcpb` bundle, the package format Claude Desktop and other
  108. hosts open in one click (Linux, macOS, Windows):
  109. ```bash
  110. python3 scripts/build_mcpb.py # -> dist/reciprocal-ruler-mcp.mcpb
  111. ```
  112. Or take the bundle from the latest release:
  113. <https://github.com/hwcho310/reciprocal-ruler-mcp/releases/latest/download/reciprocal-ruler-mcp.mcpb>
  114. The bundle needs `python3` on the machine and nothing else — the server has no dependencies.
  115. ## Registries
  116. | Registry | Entry |
  117. |---|---|
  118. | Official MCP Registry | `io.github.hwcho310/reciprocal-ruler-mcp` (published from `server.json` by `.github/workflows/publish-mcp.yml` on a `v*` tag) |
  119. | Glama | <https://glama.ai/mcp/servers/hwcho310/reciprocal-ruler-mcp> |
  120. ## Configuration
  121. | Environment variable | Default | Purpose |
  122. |---|---|---|
  123. | `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). |
  124. | `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. |
  125. | `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. |
  126. Every tool also accepts `trial_client_id` (`ruler_trial_reconcile`) and `payment_header`
  127. (the paid tools) as arguments, which override the environment defaults for that call.
  128. ## Protocol
  129. `initialize` (protocol versions `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07`),
  130. `tools/list`, `tools/call`, `ping`, and the standard notifications. Diagnostics go to **stderr**;
  131. stdout carries JSON-RPC frames only.
  132. Tool failures come back as a normal result with `isError: true` and a JSON body explaining the
  133. case (`PAYMENT_REQUIRED`, `TRIAL_EXHAUSTED`, `VERSION_MISMATCH`, `INVALID_ARGUMENTS`,
  134. `API_UNREACHABLE`), so an agent can recover instead of crashing.
  135. ## Test
  136. ```bash
  137. pip install -e ".[dev]"
  138. pytest -q
  139. ```
  140. `tests/test_protocol.py` starts the real server as a subprocess against a local mock of the API
  141. and drives a full JSON-RPC exchange — `initialize` → `tools/list` → `tools/call` — including the
  142. 402 payment path, the trial quota, and error handling, all offline.
  143. `scripts/live_smoke.py` calls the live public API with the tools (free trial only; it never
  144. spends money) to check a deployment end to end. `scripts/sdk_interop_check.py` connects with the
  145. official MCP Python SDK client (`pip install mcp`) to confirm the stdio server works with a real
  146. client implementation, not only with raw frames.
  147. ## License
  148. MIT. The service behind it is operated as Reciprocal Ruler; the API terms are whatever the
  149. endpoint itself reports at request time.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.