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 if you plan to give the agent a restricted key.

Server	URL	What it’s for	Sign-in
Docs	`https://<docs site>/_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

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:

Read. get_config shows what is configured, the clock presets and the keys the agent holds.
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.
Validate. validate_config returns the changes a configuration would make and any warnings. The agent shows you each warning.
Apply. apply_config writes the sandbox, and connect_payment_provider connects a provider’s test mode.
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.
Check. check_integration lists what a live integration is still missing.
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. 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: 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 and two for usage windows and spend limits.

Scopes

An agent’s key or session carries 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.

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. 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 describes the document an agent validates, applies and proposes.
Access, actors and audit lists the scopes an agent key can hold.
Going live uses check_integration to list what is missing.