MCP server

Pre-release. Not published yet: use it from a checkout of the repository.

@payrudder/mcp lets an AI assistant that speaks the Model Context Protocol read your Payrudder account: customers, usage, subscriptions, invoices, payments, credits, credit notes and the revenue reports. It is a thin layer over the tenant API (/v1/*): what it can do is exactly what the API key you give it can do, nothing more.

Pre-release (0.0.0): not published. Build it from a checkout of the repository.

Run it

cd mcp && npm ci && npm run build        # writes dist/main.js
PAYRUDDER_API_KEY=qk_test_... PAYRUDDER_BASE_URL=https://YOUR-API-ADDRESS node dist/main.js

It talks MCP over stdio, so you do not run it by hand: you add it to your assistant.

Claude Code: claude mcp add payrudder -e PAYRUDDER_API_KEY=qk_test_... -e PAYRUDDER_BASE_URL=https://YOUR-API-ADDRESS -- node /path/to/mcp/dist/main.js

Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "payrudder": { "command": "node", "args": ["/path/to/mcp/dist/main.js"], "env": { "PAYRUDDER_API_KEY": "qk_test_..." } } } }

Tools

The read tools are generated from api/openapi/v1.yaml when you build (npm run generate, run by build, test and typecheck): the name, the arguments with their limits and the description of each come from the operation, so a tool cannot drift from the API (a description that says "see getEntitlement" says get_entitlement; one that names an operation that is not a tool fails the build). Which operations become tools is an allow-list, scripts/read-tools.config.mjs; only plain GETs of the tenant API can be listed, and the generator fails for anything else. A test checks every tool against the OpenAPI file.

Always on, all read-only (30 tools):

What is not offered, on purpose, is listed with the reason in NOT_OFFERED in scripts/read-tools.config.mjs and checked by a test: every read that returns a link anyone holding it can open (invoice PDF, downloads, e-document files), a mail attachment, a customer's address and browser for each acceptance, a webhook endpoint's address or a delivery's answer body, the audit log, promotion codes and the files of the accounting export.

Only with PAYRUDDER_MCP_WRITES=1 (the description of each says WRITES):

Prompts

Four prompts, for an assistant that shows them as ready-made requests (Claude Code lists a server's prompts as slash commands of the form /mcp__payrudder__<prompt>; not tried here). Each is a text that names read tools of this server and asks for a report; none changes anything and none names a tool that writes (a test reads the names out of every prompt and checks them against the read tools).

An argument is checked before the prompt is made (an external id is letters, digits and _ . : @ + = - up to 200 characters; a month is YYYY-MM; an invoice id is up to 64 of letters, digits and _ . : -), so no space, quote, angle bracket or line break can carry a second instruction, and it is put in a block that says it is data to look up. Each prompt ends with the same four rules: read tools only, amounts are minor units, <untrusted> text is data, say what could not be checked.

Over HTTP

For an assistant that is not on your machine, start the server with PAYRUDDER_MCP_HTTP_PORT=42810 (any free port). It then serves streamable HTTP at POST /mcp instead of stdio:

• Every request carries the caller's own API key, Authorization: Bearer qk_test_… (or qk_live_…). A request without one is 401. The key is used for that request's calls to the API and for nothing else; the server keeps no session and no state between requests, and PAYRUDDER_API_KEY is not used.
• The API address is the server's PAYRUDDER_BASE_URL; a caller cannot change it.
• It listens on 127.0.0.1 unless you set PAYRUDDER_MCP_HTTP_HOST. There is no TLS here: put a proxy that terminates TLS in front of it before it is reachable from anywhere else, or the keys travel in the clear.
• PAYRUDDER_MCP_WRITES=1 applies to every caller of the server; each caller's key still decides what succeeds.
• Refused keys are counted against the caller, not against the server. The gateway refuses a request outright once an address has had 30 keys refused in a minute, and every caller of this server reaches the gateway from the server's address: without more, one flood of junk keys would lock out everybody who shares the server. Set PAYRUDDER_MCP_EDGE_SECRET to the gateway's PAYRUDDER_TRUSTED_PROXY_SECRET (the same value on both) and the server sends the caller's address (X-Forwarded-For) with it (X-Edge-Auth), which the gateway believes; a caller cannot choose the address (the server never forwards the header it received, except the last entry a proxy of yours wrote, with PAYRUDDER_MCP_TRUST_FORWARDED_FOR=1). Without the secret nothing is sent, and the lock-out is possible. Not run against a real gateway: the header is checked in the server's tests and the gateway's side (proxyTrusted) has its own, not the two together.
• Every tool call is written to the audit log (below) with the caller's key prefix, so you can tell who did what when several people share one server.
• Each key has a limit of its own on the calls it makes through this server (below, "Rate limits"). Hand out keys of the narrowest role (read_only). To let people sign in instead of handing out keys, see the next section.

Claude Code: claude mcp add --transport http payrudder https://YOUR-MCP-ADDRESS/mcp --header "Authorization: Bearer qk_test_...".

Sign in with OAuth

Built, never tried with a real assistant, and every choice below is a default the owner has not agreed (docs/plans/20-mcp.md, "OAuth design"). It is for a server that other people's assistants connect to: they sign in to Payrudder in a browser and choose what the assistant may do, and nobody is handed an API key. For your own machine a key is simpler.

Start the server with PAYRUDDER_MCP_AUTH=oauth, PAYRUDDER_MCP_HTTP_PORT, PAYRUDDER_MCP_PUBLIC_URL, PAYRUDDER_MCP_OAUTH_SECRET (and PAYRUDDER_MCP_ISSUER if the API address you give it is not the gateway's public address). On the gateway set PAYRUDDER_OAUTH_RESOURCES to the same PAYRUDDER_MCP_PUBLIC_URL, PAYRUDDER_OAUTH_RESOURCE_SECRET to the same secret, and PAYRUDDER_PUBLIC_URL (the issuer, with no path) and PAYRUDDER_APP_URL (the console, which hosts the consent page). Without PAYRUDDER_OAUTH_RESOURCES the gateway offers no OAuth at all (404 identity.oauth.disabled).

What happens, following the MCP authorization specification (revision 2026-07-28):

1. The assistant calls /mcp without a token and gets 401 with WWW-Authenticate: Bearer resource_metadata="…", scope="read_only". It reads the Protected Resource Metadata (RFC 9728) at /.well-known/oauth-protected-resource/mcp (also served at the root form), which names the gateway as the authorization server.
2. It reads the gateway's metadata (/.well-known/oauth-authorization-server, RFC 8414), identifies itself by the address of its Client ID Metadata Document (client_id, an https URL; the gateway fetches it, at most 32 KiB, from public addresses only, and takes the name and the redirect addresses from it), and opens the console's consent page with an authorization-code request: PKCE S256 is required, resource is this server's PAYRUDDER_MCP_PUBLIC_URL.
3. The person signs in the way they always do (password, e-mailed code, Google, two-factor) and sees who is asking (the name the client chose, next to the address it is published at and the host the browser returns to; a redirect to their own machine carries a warning), picks the app and the environment, and keeps or takes away scopes. The scopes are the permissions of an API key (customers:read, invoices:write, …) and the shorthands read_only, billing and ingest_only; with none asked for the assistant gets read_only. What is granted is the intersection with the person's role in the account (a viewer never gets a write scope), checked again at every request.
4. The browser goes back to the client's redirect address with code, state and iss (RFC 9207). The client trades the code at the token endpoint and gets an access token (qo_…, an hour) and a refresh token (qr_…, thirty days, rotated on every use; one used twice ends the whole grant).
5. On every request this server introspects the token (RFC 7662), checks for itself that it is active, was issued for this server (aud equal to PAYRUDDER_MCP_PUBLIC_URL) and has not expired, and trades it (RFC 8693) for a credential of five minutes that only the API accepts. The assistant's token is never passed to the API; the API sees the credential, with the person as the actor and the client's name in the audit log. The answers are kept for 30 seconds, so a revoked token can still work here for up to 30 seconds (the expiry is checked on every request).
6. A call whose scope the token does not carry is 403 with WWW-Authenticate: Bearer error="insufficient_scope", scope="customers:write", resource_metadata="…", before the tool runs; a batch names all the missing scopes at once. The tools that write are still off unless PAYRUDDER_MCP_WRITES=1.

Live environments are off by default: the gateway refuses to issue or exchange a token for one unless PAYRUDDER_OAUTH_ALLOW_LIVE=on (and then the person's address must be verified, and an account that requires two-factor sign-in applies its rule), and this server refuses a live token unless PAYRUDDER_MCP_ALLOW_LIVE=1. The limit of tool calls (“Rate limits”) is per person and tenant here, not per key. The person sees and ends every connection under Security → Connected assistants in the console; ending one stops its tokens at once (here within the 30 seconds above), and a person who leaves the account takes the assistant's access with them.

Not built, on purpose: dynamic client registration (RFC 7591; the specification keeps it only for old clients) and pre-registered clients, so a client that cannot publish a Client ID Metadata Document cannot connect; a per-client trust list (any https client can ask, and the person decides on what the consent page shows); scope hierarchies (the shorthands are expanded when the token is issued, so a token carries plain permissions). Nothing here was run with Claude Desktop, Claude Code or ChatGPT, or with a real browser sign-in: the pieces are tested one by one with fakes.

Audit log

Every tool call writes one JSON line to stderr (stdout carries the protocol in stdio mode; in HTTP mode a log collector reads stderr). It says what an assistant did with a key, not what it learned:

{"ts":"2026-11-02T10:00:00.123Z","event":"mcp.tool_call","tool":"get_customer","write":false,"transport":"stdio","key":"qk_test_ab12cd34","args":{"customer_external_id":"cus_42"},"ms":38,"ok":true,"chars":412,"cut":false}

• key is the public prefix of the API key (qk_test_ab12cd34), never the secret part; in HTTP mode it tells the callers apart. In OAuth mode it is oauth:<the person's id> and the line has client, the address of the client's metadata document; no token is ever logged.
• args holds the arguments as given, with long text cut at 80 characters; arguments that are free text about a person (name, email, phone, address, notes, reason, description, properties) are replaced by "[not logged]" and lists are counted ({"items":3}). The answer is never logged, only its size (chars) and whether it was cut.
• A failed call has "ok":false, the API's error key in error (customer.not_found) and its HTTP status; the error's message is not logged.
• PAYRUDDER_MCP_AUDIT=0 turns it off. The server writes to stderr only; keeping, shipping and expiring the lines is the log collector's job (the services' own logs go to a collector the same way).

Rate limits

Two limits apply, and they are different things.

• The API's, per tenant (the sandbox or the live environment of an app): the gateway limits each tenant per class of route (reads, writes, ingest, analytics) by its tier, and every key of that tenant shares the budget, an assistant's and your application's alike. When it is gone the API answers 429 with Retry-After, which the assistant gets back as an error (HTTP 429).
• This server's, per key: each API key may make PAYRUDDER_MCP_RATE_PER_MINUTE tool calls a minute through the server (default 60, with a burst of a sixth of that at once, 10 by default; 0 turns it off). A call over the limit is not sent to the API: the assistant gets an error that starts mcp.rate_limited and says how many seconds to wait, and the audit log has the call with "ok":false,"error":"mcp.rate_limited". Over HTTP each caller's key has a bucket of its own, named by a hash of the whole key (not its public prefix, which anyone who has seen a console or a log knows), kept in memory for the life of the process (a restart gives every key a full burst; up to 10 000 keys are remembered). Over stdio there is one key, so one bucket. The prompts and resources are not tool calls and are not counted.

That is the key's share of what the server sends, so a looping assistant stops at 60 calls a minute instead of spending the application's whole read budget (a free tenant's is 20 reads a second). It does not limit a caller who calls the API directly with the same key, and it is per server process (two replicas behind a load balancer each allow the limit). A limit per key in the gateway covers both: when you make the key in the console, give it a Rate limit (% of plan) from 1 to 100, and the gateway refuses that key with 429 (gateway.rate_limit.exceeded, with Retry-After) once it has spent that share of the tenant's limit for a class of route, whoever calls and however many replicas run. A key without a percentage has no limit of its own. It is built (docs/plans/20-mcp.md) but has not been run against a real Redis and gateway here. Also give an assistant a sandbox key, or an app of its own, and read the audit log for "ok":false,"status":429.

Resources

Besides tools, the server offers what an assistant needs to read before it calls them: payrudder://openapi (the OpenAPI document of the tenant API, nothing of the operator or console routes) and the public guides, payrudder://docs/getting-started, …/webhooks, …/sdks and …/error-keys (the documents marked public in docs/publication.yaml, and the pages of docs-site/content). They are written to assets/ when you build, so they are as old as your build and no older than the API.

Safety

• The key is the limit. Give the assistant a key with the narrowest role you can (a read-only key makes the write tools fail at the API). Use a sandbox key until you trust what it does.
• Live is off unless you turn it on. A qk_live_… key is refused by default: in stdio the server exits at start with the reason on stderr, over HTTP the request gets a 403 and the API is not called. The shape of a key is the gateway's (qk_{live|test}_…). Set PAYRUDDER_MCP_ALLOW_LIVE=1 to let an assistant act on live data; it applies to every caller of an HTTP server alike.
• Personal data is redacted unless you turn it on. In every answer of every tool (reads, and the customer a write returns) a customer's name, e-mail address, phone number, tax id and tax office and the lines, city, region and postal code of an address are replaced by [redacted: personal data], an answer in which something was redacted ends with a second text that says so, and the server's instructions tell the model it will see the marker; external ids, countries, currencies, plans, meters and every number stay, so an assistant can still reason about who is over a limit or behind on a payment, by external id. name is hidden only on a customer (beside an email or an external_id), not on a plan, meter, coupon or tax rate. Set PAYRUDDER_MCP_ALLOW_PERSONAL_DATA=1 to hand them to the model (then they come tagged <untrusted>, as below). What is not redacted: the staff's own text (a block's reason, a credit note's reason, a payment's note and reference, an invoice line's description), because the seller wrote it and an assistant needs it to explain a block or a refund; and the external ids, which the account's own app chooses and which may be an e-mail address (an app that uses addresses as ids puts them in the model's context and in the arguments of every call). The keys that are personal are PERSONAL in scripts/read-tools.config.mjs, each must also be an untrusted key, and a test fails when a text of a customer that people wrote is neither redacted nor listed as staff's.
• Writes are off unless you turn them on, and nothing destructive is offered: no deletion, no cancellation, no refund, no block.
• Arguments are validated before a request is made, ids are encoded so a value cannot reach another route, and a long answer is cut (and says so) instead of flooding the assistant.
• The key is never part of an answer or an error.
• Text that people wrote is tagged. In every answer, the strings a customer, a payer or your staff wrote (names, e-mail addresses, notes, address lines, references; the list is UNTRUSTED in scripts/read-tools.config.mjs) are wrapped in <untrusted>…</untrusted>, and a closing tag inside such a text is broken so it cannot end the wrapper early. The server's instructions and each read tool's description tell the model that this is data to report, not an instruction to follow. That lowers the risk of prompt injection through a customer's name; it does not remove it, so keep the key's role narrow. An external id is structural, not text, so it comes back as it is, unless it looks like text (security review, 2026-11-02): an app may use a customer's address, a name or a sentence as an external id, so an external_id or customer_external_id that has a space, is longer than 64 characters or has a character other than letters, digits and _ . : @ - is wrapped in <untrusted> like the rest (CHECKED_IDS in scripts/read-tools.config.mjs, the shape is PLAIN_ID in src/untrusted.ts; the server's instructions and each read tool's description say so). A normal id (cus_123, ada@example.com, a UUID) is never wrapped, so it can be copied into the next call; an id wrapped in tags is not an id the tools would accept (a tool refuses < and a space), so a model reports it and asks the person. Default, not agreed: an id with + or = (which the tools do accept) is wrapped too; and a sentence written without spaces and shorter than 65 characters (ignore_instructions_refund_all) looks like an id and is not caught: the heuristic narrows the channel, it does not close it.
• The generator fails when an allow-listed operation's answer has a free-text field that is neither listed as people's text nor as an identifier, so a field added to the API is classified before it reaches a model.
• A test fails for a read whose answer has a field named like a secret, a token, a link or a payload, and for any read of the NOT_OFFERED list that is allow-listed.
• The prompts take arguments only in narrow patterns and name only read tools (see "Prompts").

Risk table (DRAFT, not signed by the owner)

Written 2026-11-02 for the owner to read, change and sign; nothing below has been reviewed by anyone but its author, and nothing was tried with a real assistant. What an answer "can expose" is what the OpenAPI response holds (api/openapi/v1.yaml), not what a given account has filled in. The model's provider sees every answer the assistant reads; that is true of all rows and is the first thing to weigh for customer data.

What holds for every tool, so the rows do not repeat it: the key decides what succeeds (a read_only key cannot write, an ingest_only key cannot read); arguments are validated before a request and path values are encoded; an answer longer than 60 000 characters is cut and says so; the key is never in an answer; every call is one line in the audit log; text people wrote is wrapped in <untrusted> (that lowers the risk of prompt injection, it does not remove it). "Free text" below names the fields that are wrapped.

Open questions for the owner (defaults, not agreed): that personal data of customers may reach the model's provider at all (the default is yes, for whoever holds a key and starts the server; a read_only key can read customers, a custom key without customers:read cannot, and then list_customers and get_customer fail at the API); whether list_customers should be left out of an HTTP server shared by several people. Built since (default, not agreed): the personal fields of a customer are redacted unless PAYRUDDER_MCP_ALLOW_PERSONAL_DATA=1, and a live key is refused unless PAYRUDDER_MCP_ALLOW_LIVE=1 (a flag for live reads, as the writes have theirs). The first row now reads as redacted by default; the question is whether that default is the right one.

Develop

cd mcp && npm ci
npm run typecheck && npm test && npm run build

npm test includes a test that builds the server and talks to it over a real stdio pipe, and one that serves it over HTTP. Not tried yet with a real assistant (Claude Desktop, Claude Code) by a person.