ratchet-mcp

MCP server for Ratchet — an effect gate for AI agents.

Agents retry. LLM control flow is non-deterministic, network calls fail ambiguously, and processes die mid-action, so the same logical action gets attempted zero, one, or several times and nothing knows which. Ratchet is a gate you ask before acting, and it answers durably.

Setup

Get a key at https://ratchetgate.com/console (free, no card), then:

{
  "mcpServers": {
    "ratchet": {
      "command": "npx",
      "args": ["-y", "ratchet-mcp"],
      "env": { "RATCHET_API_KEY": "rk_live_..." }
    }
  }
}

Put the key in env, never in args — arguments are visible in process listings.

Works with Claude Desktop, Claude Code, Cursor, and any MCP client that spawns a stdio server.

Runs on macOS, Linux, Windows and BSD — anywhere Node 18+ runs. The bridge is a single dependency-free file with no native modules, no shell-outs and no platform-specific paths, so there is nothing to compile and nothing that behaves differently between operating systems. Ratchet itself is a hosted service, so the gate is never something you install or operate.

Tools

| Tool | What it does | |---|---| | ratchet_begin_effect | Ask permission before a side effect. Returns execute, duplicate, in_flight, blocked, approval_required, or denied | | ratchet_report_effect | Report the outcome after acting | | ratchet_get_effect | Ask "did I already do this?" without reserving anything | | ratchet_resolve_effect | Settle an effect whose outcome was unknown, after verifying | | ratchet_list_effects | Review recent effects; filter by indeterminate to find unresolved work | | ratchet_get_policy | Read the retry and budget policy for an effect type | | ratchet_get_usage | Plan, allowance, credit balance, and today's spend |

Only execute authorises the model to act. Every other decision returns a next_step beginning with STOP.

The part that matters

If your agent dies between "go" and "done", Ratchet does not quietly let the next caller retry. The lease expires, the effect becomes indeterminate — a known unknown — and your configured policy for that effect type decides what happens: block (the default), retry, or verify first.

Exactly-once delivery is not achievable and is not claimed. What is guaranteed is at-most-once initiation, a recorded outcome that later callers replay, and an explicit state for the case most systems bury.

Configuration

| Variable | Default | Purpose | |---|---|---| | RATCHET_API_KEY | (required) | Your scoped API key | | RATCHET_BASE_URL | https://ratchetgate.com | Point at your own instance | | RATCHET_TIMEOUT_MS | 15000 | Request timeout |

This package holds no database connection and no server secret — only your key, which is scoped and revocable. It is a thin bridge to the HTTP API, with zero dependencies.

If the gate is unreachable it returns a JSON-RPC error rather than crashing, so your agent can apply its fail-open or fail-closed policy. Decide which before integrating: https://ratchetgate.com/docs

License

Apache-2.0