> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runledger.co/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runledger.co/_mcp/server. # Set up with a coding agent Coding agents such as Claude Code and Cursor can reach Runledger through two MCP servers. The developer server is for setting up and debugging an integration, and agent-led setup is its main job: an agent in your repo configures the sandbox, checks it, and proposes the live changes for you to approve. It changes the sandbox directly and never changes live billing. ## Before you start * A coding agent that supports MCP over HTTP. * A Runledger account, where you sign in when the agent first connects. Read [Access, actors and audit](/api-reference/access-and-audit#keys-and-scopes) if you plan to give the agent a restricted key. | Server | URL | What it's for | Sign-in | | --------- | --------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------- | | Docs | `https:///_mcp/server` | Answers questions from these docs and the API Reference | None | | Developer | `https://mcp.runledger.co/mcp` | Sets up and debugs your integration in the sandbox, and proposes live configuration | Your Runledger login, or a restricted or agent key | The docs server comes with the docs site. Every page is also available as Markdown, and the site serves `llms.txt` and `llms-full.txt`. ## Connect ```bash claude mcp add --transport http runledger https://mcp.runledger.co/mcp ``` On first use, the server asks you to sign in to Runledger in the browser and approve what the agent may do. Clients without browser sign-in can send a restricted or agent key (`rl_rk_test_...`) as a bearer token; a secret key is refused with `401`. A key reaches only its own environment, so a sandbox key reads and writes the sandbox, and proposing a live change takes a second connection with a live agent key that holds `config:propose`. An Admin can create an **agent key** in the dashboard, and a Collaborator can create one for the sandbox with a preset of scopes and an expiry; the key is marked `agent: true`, and everything it changes is recorded as made by an agent. The server refuses live keys for writes. ## What an agent does with it The server's instructions name these steps in order, so the agent doesn't have to infer them: 1. **Read.** `get_config` shows what is configured, the [clock presets](/concepts/outcome-settlement#presets-not-defaults) and the keys the agent holds. 2. **Ask you.** The agent asks you to confirm the confirmation window, the reversal horizon and the dispute decision window. It isn't meant to guess them. 3. **Validate.** `validate_config` returns the changes a configuration would make and any warnings. The agent shows you each warning. 4. **Apply.** `apply_config` writes the sandbox, and `connect_payment_provider` connects a provider's test mode. 5. **Exercise.** `preview_event`, `create_test_customer`, `set_test_limits`, `run_scenario` and `advance_test_clock` run the setup through its clocks, and `get_usage_summary` shows what a customer's meters would read. 6. **Check.** `check_integration` lists what a live integration is still missing. 7. **Propose.** For live, `propose_live_config`, called through a connection with a live agent key, sends the change to you with a link to the diff. The `search_provider_catalog`, `get_cost_catalog` and `simulate_pricing` tools, and the `pricing` block on `preview_event`, belong to [pricing from cost](/guides/cost-attribution-and-margin#set-it-up-with-an-agent). There the agent matches the models your code calls to the provider price catalog and drafts cost models and price rules. You supply any negotiated or self-hosted rates that aren't in the catalog and confirm the markup, the floor and whether a guardrail may block, and live changes are proposals as above. ## Tools | Tool | Changes anything? | What it does | | -------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `get_sandbox_context` | No | Lists the credit types, plans, outcome definitions and webhook endpoints set up, and the last day's activity | | `get_config` | No | Returns the whole configuration with its hash, the clock presets and their bounds, the payment providers, and the keys held, masked. Can say which provider a customer would use | | `validate_config` | No | Checks a configuration document without writing it, and returns the changes, warnings and errors | | `search_requests` | No | Finds recent requests by status, error code, path, idempotency key, actor or key | | `explain_request` | No | Explains one request: the error, the parameter at fault, the likely fix, and the objects it touched | | `explain_balance` | No | Shows how a balance adds up: holds, pending charges, grants in draw order, recent ledger entries, and the window or limit that denies a check | | `get_usage_summary` | No | Returns a customer's [usage summary](/guides/usage-summary): every window, the pools, spend and limits, and which window will stop them first. Works on sandbox and live data | | `explain_outcome_charge` | No | Tells one charge's story: its terms, each status change and cause, the rules that matched, any dispute, including whether it is holding the lock past the horizon, and any reversal | | `preview_event` | No | Shows what `track()` would do with an event, without recording it. Name a `price_rule` to price it with a rule no plan rate uses yet | | `check_integration` | No | Reviews recent traffic for what a live integration needs, item by item, with fixes. The dashboard's Get started page shows the same result | | `get_audit_log` | No | Lists who or which agent changed what, through which surface | | `search_provider_catalog` | No | Searches the Runledger-maintained provider price catalog by provider, kind or unit, and reads a model's price versions with their sources and effective dates. Read-only: the catalog can't be written | | `get_cost_catalog` | No | Lists your cost models with their source (catalog or custom), overrides and active rate cards, price rules and margin guardrails | | `simulate_pricing` | Records a simulation only | Replays recorded events and costs against a candidate cost model, price rule or cost adjustment, including a scheduled catalog price, and reports the margin it would have had. A long replay comes back `pending`; ask again for the result. Changes no balance, invoice or configuration | | `apply_config` | Sandbox only | Creates or updates every object in a configuration document, all or none | | `connect_payment_provider` | Sandbox only | Connects a provider's test mode. Connecting a provider in live isn't open yet; when it opens, a person finishes it at the provider and an Admin confirms the first one in the dashboard | | `propose_live_config` | A proposal only | Proposes a live change for a person to approve. Changes nothing until they do | | `create_test_customer` | Sandbox only | Creates a customer, subscription, starting credits and test clock in one step | | `set_test_limits` | Sandbox only | Sets a spend limit, an auto top-up or both on a test customer, and can settle the auto top-up purchase | | `run_scenario` | Sandbox only | Runs a scripted scenario, such as the two-agent race, an unhappy customer, a full cap window, a spend limit or an auto top-up, and reports each step | | `advance_test_clock` | Sandbox only | Moves a test clock forward and lists what fell due on the way | | `send_test_webhook` | Sandbox only, and calls your URL | Sends a signed sample event to one of your webhook endpoints and reports the response and the endpoint's delivery health | Each tool calls the public API, so anything an agent does here you can also do with the SDKs. Every tool declares input and output schemas, and is marked read-only or not so your agent can ask before it writes. That is twenty-two tools, including three for [pricing from cost](/concepts/cost-reflective-pricing) and two for [usage windows](/guides/usage-windows) and [spend limits](/guides/spend-limits). ## Scopes An agent's key or session carries [scopes](/api-reference/access-and-audit#keys-and-scopes). A tool that needs a scope the agent lacks fails with `insufficient_scope` and says which scope it needed, so the agent can ask you to widen the grant. The tools above need: | Tool | Scope | | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_config`, `validate_config`, `get_cost_catalog`, `search_provider_catalog` | `config:read` | | `simulate_pricing` | `config:read` and `events:read` | | `apply_config` | `config:write` | | `propose_live_config` | `config:propose` | | `connect_payment_provider` | `providers:connect` | | `get_audit_log` | `audit:read` | | `get_usage_summary` | `usage:read` | | `create_test_customer` | `test_helpers:write`, `customers:write`, `config:read` | | `advance_test_clock` | `test_helpers:write`, `audit:read` | | `send_test_webhook` | `webhooks:write`, `config:read` | | `run_scenario` | `test_helpers:write`, `customers:write`, `config:read`, `events:write`, and per scenario `usage:read`, `spend_limits:write`, `auto_top_up:write`, `charges:read` or `disputes:read` | | `set_test_limits` | `spend_limits:write`, `auto_top_up:write`, `test_helpers:write` | Reversing a charge and deciding a dispute need `charges:write` and `disputes:resolve`. Those are never part of an agent preset and no tool here uses them. Removing a payment provider is `DELETE /v1/payment_providers/{id}` in the API, and there is no tool for it. Only an Admin can remove a live provider. ## Safety * **The sandbox is where agents write.** With the right scopes an agent applies configuration directly, and each write records the client's name and the person it acts for. * **Live changes need a person.** `propose_live_config` returns a proposal with a diff and a `review_url`. An Admin approves it in the dashboard, and the approver is recorded as `approved_by` in the audit log. Proposals expire after 7 days. Reading live configuration is allowed with a read scope. * **Secrets stay out of the chat.** Agents never create or roll keys and never receive live provider credentials. Connecting a live provider, which isn't open yet, will be a link a person opens and an Admin confirms in the dashboard, and a live webhook secret is shown only in the dashboard. * Tool results can contain text your end customers wrote, such as dispute descriptions and evidence. Runledger sanitizes it, but your agent should still treat it as data, never as instructions. * Every tool call is recorded in your request logs with the agent named, and every configuration change in the [audit log](/api-reference/access-and-audit#the-audit-log). No tool on this server writes live data except `propose_live_config`, and that only proposes. Tools that move money in live, such as approving a reversal, are not offered to agents. An agent key can still hold `spend_limits:write` or `auto_top_up:write` and call the API directly, within the limits described in [Access, actors and audit](/api-reference/access-and-audit#keys-and-scopes). Allowances, pools and operator spend limits are configuration, so an agent sets them up the same way as plans: `validate_config`, `apply_config` in the sandbox, then `propose_live_config`. Exporting and importing a whole configuration is `GET` and `PUT /v1/config` in the API; there are no MCP tools for it. ## Next steps * [Configuration](/api-reference/how-configuration-works) describes the document an agent validates, applies and proposes. * [Access, actors and audit](/api-reference/access-and-audit) lists the scopes an agent key can hold. * [Going live](/going-live/overview) uses `check_integration` to list what is missing.