routstr-mcp

Give your AI agent every model sold on Routstr, paid in sats.

routstr-mcp is an MCP server. Add it to Claude Code, Codex, Cursor, Claude Desktop or any other MCP app, and the agent gets these tools:

Use it to put the right model on each job: a second opinion from a different model, several models compared side by side, or a review or a self-contained change handed to a cheaper one such as Kimi, GLM, DeepSeek or Qwen. There is no account and no card: you prepay a few sats over Lightning, and that prepaid balance is the most the agent can ever spend.

ask, council and quote

Pass files (project paths) to send files along with the prompt, and images (project paths or https URLs) for a model that takes images. find_models with vision: true lists those. Secret files such as .env and keys are refused, and key-shaped strings in a file are removed before it leaves your machine.

Call quote with the same model, prompt, optional system, and max_sats you plan to pass to ask. It returns the selected model and node, advertised rates, and the estimated cost of the initial request. Pass the returned model and node to ask to keep the request on that node. The quote uses catalog prices, and the node can select its own upstream route and settle a different amount.

ask returns its receipt in structuredContent.receipt. It includes the estimate, output limit, and node charge when available. The receipt also records the request ID, upstream provider, token counts (including reasoning and cache counts), and finish reason when reported. costSource distinguishes node-reported charges, estimates based on token usage, and unavailable costs. overTarget flags a reported charge above the requested target, and extraFees flags a model whose node also bills web search or reasoning.

For reasoning models, pass reasoning_effort (for example "low") to request less thinking. The serving route determines which efforts it supports.

delegate

delegate runs a subagent: the model you name gets the task and tools to list, read, glob and grep files and to look at git (status, diff, log, show), and works through it step by step until it reports back. You get its report, the files it changed as a diff, the commands it ran and the cost.

• access: "read" (the default) only looks. When the model edits a file, the change is kept as a proposal and comes back as a patch you can apply with git apply. Up to 3 models can do the same task at once, to compare their work.

• access: "edit" also writes files in the project.

• access: "shell" also runs commands, such as tests, in a sandbox with no network. Reads stay inside the project, system folders and your toolchains; writes stay inside the project, and .git, git hooks and shell settings stay read-only, so a command cannot plant code that runs later. It uses sandbox-runtime: macOS needs nothing extra, Linux needs bubblewrap, socat and ripgrep.

Use edit or shell on a clean git tree, so you can see and undo every change. The subagent works in the folders your MCP app has open, else ROUTSTR_WORKSPACE, else the folder the app started the server in; cwd narrows it to a subfolder. It never reads secret files or folders (.env, keys, .git internals, ~/.ssh, wallets).

max_sats is the budget for the whole run (default 300, at most 2000) and max_steps the most model calls (default 30). Each step is paid as it goes, and the model is told to wrap up when the budget runs low. The report ends with a session id: pass it as session with a follow-up task within 30 minutes to continue the same run. Long runs send progress notes, and cancelling the tool call stops the run.

Set up

1. Add it to your MCP app. For Claude Code:

   claude mcp add routstr -- npx -y routstr-mcp

   For Codex, in ~/.codex/config.toml (a longer tool timeout lets delegate finish):

   [mcp_servers.routstr]
   command = "npx"
   args = ["-y", "routstr-mcp"]
   tool_timeout_sec = 900

   For Cursor (.cursor/mcp.json), Claude Desktop and other apps:

   { "mcpServers": { "routstr": { "command": "npx", "args": ["-y", "routstr-mcp"] } } }

   In Claude Code, MCP_TOOL_TIMEOUT=900000 gives long delegate runs room too.

2. Add sats. In a terminal:

   npx routstr-mcp fund 2000

   It shows a Lightning invoice as a QR code. Pay it from any Lightning wallet and you are done. To fund the node that sells a model cheapest, add --model <id>.

3. Ask your agent something like "ask gpt-5 for a second opinion on this function", "run a council of three models on this question" or "delegate a security review of src/ to kimi".

Related MCP server: Maximum Sats MCP

Commands

routstr-mcp                         start the MCP server (what your MCP app runs)
routstr-mcp fund <sats>             pay a Lightning invoice to add sats
    --model <id>                    on the cheapest node that sells this model
    --node <url>                    on this node
routstr-mcp balance                 sats left, per node
routstr-mcp refund                  take all unspent sats back as a Cashu token
    --to <lightning address>        or send them to a Lightning address
    --node <url>                    only from this node
routstr-mcp spend                   what calls cost: today, per day and per model
    --days <n>                      look back this many days (default 7)
routstr-mcp nodes                   approved nodes and how many models each sells
routstr-mcp import --node <url>     add a Routstr key you already have (read from stdin)

How your sats stay safe

• The prepaid balance is a hard cap. Your sats sit on the node as the balance of a Routstr API key. Nothing can spend more than you paid in.

• Each call has a spend target. The agent can pass max_sats (default 100, at most 500). This sizes the output token limit using the catalog estimate. The node settles the charge, which can exceed the target. A delegate run has a budget for all its steps.

• You can set a daily limit. With ROUTSTR_DAILY_SATS, calls stop for the day once that much is spent. Every paid call is logged to ~/.routstr-mcp/spend.jsonl; routstr-mcp spend sums it up.

• The agent never sees a secret. API keys, invoices and Cashu tokens stay in the wallet file and the terminal, and are removed from anything a node sends back. There is no tool that funds or refunds, so the MCP tools alone cannot move your sats. An agent that also has a shell (Claude Code, Cursor) could still run the CLI or read the wallet file, so keep your app asking before it runs commands. A delegate subagent cannot reach the wallet: it is outside the project, and the shell sandbox blocks the home folder.

• The wallet is private. It lives in ~/.routstr-mcp/wallet.json, readable only by you. A refund token is also saved in ~/.routstr-mcp/refunds/ before the key is dropped, so a crash cannot lose it.

• A stopped payment is not lost. If you pay after closing the fund command, the sats are picked up the next time the wallet is used.

Which nodes it uses

Nodes announce themselves on Nostr. routstr-mcp uses the same rule as the Routstr SDK: a node is used only when the Routstr curator's latest review of it is positive (trusted, verified, lgtm) and no review is negative. Only public HTTPS addresses are used, never a local network, localhost or onion address. If a node is down, out of sats for you or cannot serve the model right now, a call moves to the next node where you have sats. It never moves on once a node may have charged for the call.

Settings

Development

Node 22 or newer.

npm install
npm test          # logic tests

The end to end tests run a real stack on your machine: two routstr-core nodes, a real Cashu mint (nutshell, with fake Lightning so invoices pay at once) and a fake AI. They need uv, Python 3.12 and a routstr-core checkout with its venv:

git clone https://github.com/Routstr/routstr-core && (cd routstr-core && uv sync --frozen --no-dev --python 3.12)
KIT_CORE_DIR=$PWD/routstr-core npm run test:e2e

Set E2E_PYTHON if your Python 3.12 is not at /usr/bin/python3.12.

License

MIT