Getting started

Connect an AI assistant (MCP)

Let Claude, Cursor or any MCP client read your billing data: customers, subscriptions, invoices, payments and metrics, with a read-only API key.

Two Minute Billing has a built-in MCP server. An AI assistant that supports the Model Context Protocol can use it to answer questions about one business: "Which customers have unpaid invoices?", "Why did this payment fail?", "Why did MRR drop last month?", "What would an upgrade to Pro cost this customer today?"

Every tool is read-only. The assistant can look things up and ask the engine for estimates. It cannot change anything. (To get answers inside the dashboard, and to have changes prepared for you to confirm, use Billy.)

The server address

Two Minute Billing Cloud: https://mcp.twominutebilling.com/mcp
Your own installation: your API host followed by /mcp, for example https://api.example.com/mcp. To serve it from a host of its own, point that host at the API and set MCP_PUBLIC_URL (for example https://mcp.example.com) in the engine's environment, so every address the server gives to a client uses that host.

Connect by signing in

Clients that connect by signing in (OAuth), such as the Claude and ChatGPT apps, need only the server address. Add the server address above as a custom connector. The client then sends you to Two Minute Billing:

Sign in, if you are not signed in.
Select the business the assistant can read, and select Connect.
You return to the assistant, which is now connected.

The connection reads only what you can read in that business, and it is read-only. Every connected app shows in Settings → Developer → Connected apps, where you can disconnect it. Disconnecting stops its access at once.

Connect with an API key

For developer tools that send a header (Claude Code, editors, scripts), use a read-only API key.

In the dashboard, go to Settings → Developer.
Create an API key. Set Access to Read only, and select test or live mode.
Copy the key. You see it one time only.

The server refuses a key that can change data. A key with per-resource access needs MCP set to Read, and the assistant then sees only the tools for the resources the key can read.

Add the server

With a key, add / and the business id to the server address:

https://mcp.twominutebilling.com/mcp/biz_XXXXXXXXXXXX01

If the key reaches only one business, the address without the business id also works. On your own installation, use your own server address in place of https://mcp.twominutebilling.com.

Claude Code

terminal

claude mcp add --transport http billing https://mcp.twominutebilling.com/mcp/biz_XXXXXXXXXXXX01 \
  --header "Authorization: Bearer <read-only key>"

Other clients take the same two things: the server URL and an Authorization header. In a client that keeps its servers in an mcpServers JSON file, the entry looks like this:

mcp.json

{
  "mcpServers": {
    "billing": {
      "url": "https://mcp.twominutebilling.com/mcp/biz_XXXXXXXXXXXX01",
      "headers": { "Authorization": "Bearer <read-only key>" }
    }
  }
}

Tools

Tool	What it does
`get_business`	The business: name, currency, timezone, mode and billing settings
`search_customers`	Find customers by text or filters (unpaid invoices, expiring cards, MRR…)
`get_customer`	One customer with subscriptions, recent invoices and payment methods
`list_subscriptions` / `get_subscription`	Subscriptions, scheduled changes and the next renewal estimate
`list_invoices` / `get_invoice`	Invoices with lines, taxes and the dunning journey
`list_payments` / `get_payment_attempts`	Payments and refunds, and each attempt with its decline reason
`get_metrics`	MRR, ARR and the revenue series from the metric store
`explain_invoice`	Why an invoice is what it is: the totals, each line's facts, and what changed from the previous invoice
`explain_payment`	Why an invoice is unpaid: each attempt with its decline reason, and what dunning does next
`explain_mrr_change`	How MRR moved over a range: opening, the change by reason with the largest movements, closing
`explain_balance`	A customer's promotional credits, excess payments, credit grants and wallet
`preview_subscription_change`	What a plan or quantity change would cost, without making it
`preview_cancellation`	What a cancellation would do to money, without cancelling
`search_docs`	Search the help and the API reference, with a link to each page
`get_api_reference`	The exact definition of one API operation
`find_screen`	Where something is in the dashboard: the screen, its menu path, a link, and its buttons and fields
`read_api`	Any other read endpoint of the business, by path

List tools take filters in the same field[op] form as the API's list endpoints, and page with starting_after.

What the assistant can see

One business, in the mode of the key. A test key never reaches live data.
Only what the key can read. Each tool call goes through the same API route, permission check and rate limit as any other call with that key, and is in Developer → Logs.
Not documents (invoice PDFs), bulk exports, or connection settings for email and gateways.

The data a tool returns goes to the AI provider your client uses. Customer names, notes and metadata come back with invisible formatting characters removed, and the server tells the assistant to treat them as data, not instructions.

Edit this pageorReport an issue

Self-host with Docker

Run Two Minute Billing on your own server with Docker Compose: Postgres, the API, the billing worker and the dashboard, with automatic HTTPS, a first admin and upgrades by version tag.

Account hierarchy

Learn how organizations, businesses, customers and subscriptions nest, when to add a second business, and why catalog ids look different from other ids.