Macropay MCP Server

Your billing stack is the one system you least want to context-switch into. The Model Context Protocol lets you skip the dashboard entirely: connect Claude, Cursor, ChatGPT, or any MCP-capable client and just ask. Macropay runs a hosted MCP server at https://mcp.macropay.ai that any of those clients can reach after a single OAuth click — no API key to paste, no SDK to install, no glue code.

MCP hands an AI agent auth-aware, structured tool access to the exact data the dashboard renders — read live from your organization, never cached. The rule of thumb: anything you can do by clicking in the dashboard, you can do by asking the agent.

Because Macropay is the Merchant of Record, the numbers the agent reads back are already net of the work most platforms leave to you — sales tax and VAT are remitted on your behalf, disputes are handled, and your tax liability is capped. The agent reports on settled, MoR-clean revenue, not a raw gateway feed.

Things to ask once you’re connected

Connect, then talk to your assistant in plain English. Every prompt below maps to real tools and works today. Revenue & growth

“What’s my MRR right now, and how does it compare to last week?”
“Total settled revenue this month vs. last month — show the delta.”
“Rank my top 10 customers by spend over the last 30 days.”
“What’s my 30-day churn rate? How many subscriptions did I lose?”
“Pull every order above $500 placed today.”

Customer operations

“Refund order ord_9f2c in full, then draft a confirmation email.”
“Pause cus_h4k2’s subscription indefinitely and note why.”
“Payment pay_3Ta1 was declined — what happened and what do I tell them?”
“Cancel every subscription that’s been past due longer than 14 days.”

Catalog & pricing

“Spin up a ‘Scale’ plan at $99/month with a 14-day trial.”
“Attach a $990 annual price to the Scale product.”
“List every product I sell with its active prices.”

Forensics

“Group every failed payment in the last 7 days by decline reason.”
“Find my newest dispute and tell me which evidence to file.”
“Which webhook endpoints failed delivery in the last 24 hours?”

Agentic teams: the same OAuth flow that authorizes Claude works for an autonomous agent you build. Mint a scoped token, point your agent’s MCP client at mcp.macropay.ai, and it can reconcile revenue or process refunds the same way a human operator would — every call captured in the audit log.

Connect in five minutes

Claude Desktop
Claude Code
Cursor
ChatGPT (Pro / Team / Enterprise)
Windsurf / Codex / others

The true one-click path.

Open Claude Desktop, go to Settings (⌘,) → Connectors.
Choose Add custom connector.
Enter:
- Name: Macropay
- Server URL: https://mcp.macropay.ai/mcp/macropay-mcp
Hit Connect.
A browser tab opens at app.macropay.ai/oauth2/authorize. Sign in, choose the organization to grant, and click Allow.
The tab closes on its own. Macropay’s tools now appear in Claude, ready to use.

Sanity check it with “What’s my MRR right now?” — Claude will show mrr_snapshot in its tool-use panel and answer.

Run this from any project directory:

claude mcp add --transport http macropay https://mcp.macropay.ai/mcp/macropay-mcp

The next session you start triggers browser-based OAuth — identical to the desktop flow.Confirm it registered:

claude mcp list

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "macropay": {
      "url": "https://mcp.macropay.ai/mcp/macropay-mcp"
    }
  }
}

Restart Cursor, open the MCP tab in the Composer side panel, and you’ll be prompted to authorize. Pick the org and click Allow.

In ChatGPT, go to Settings → Connectors → Add custom connector.
Server URL: https://mcp.macropay.ai/mcp/macropay-mcp
Authentication: OAuth.
Connect → authorize → done.

The tools land in the connector picker under the chat input.

Any client that speaks remote HTTP transport with OAuth works untouched.Generic config:

{
  "mcpServers": {
    "macropay": {
      "transport": "http",
      "url": "https://mcp.macropay.ai/mcp/macropay-mcp"
    }
  }
}

No native OAuth? Use a long-lived Organization Access Token instead — see token-based auth below.

Your first multi-tool prompt

With the connector live, open Claude (Desktop or Web) and paste this:

“Give me a snapshot of my Macropay account: today’s revenue, current MRR, 30-day churn, and my top 5 customers by 30-day spend.”

Claude chains four tools — revenue_today, mrr_snapshot, churn_30d, top_customers — and stitches the results into one answer. A “Calling Macropay…” indicator flashes per call. The first tool call surfaces a one-time consent dialog in your client. After that, reads run silently. Anything that mutates — refunds, plan creation, cancellations — always asks for explicit confirmation, every time.

The toolbox

55 tools, grouped by what they touch.

Read-only

Category	Tools
Customers	`list_customers`, `get_customer`, `list_customer_meters`
Orders	`list_orders`, `get_order`
Subscriptions	`list_subscriptions`, `get_subscription`
Products & prices	`list_products`, `get_product`, `list_prices`, `get_price`
Payments	`list_payments`, `get_payment`
Members	`list_members`, `get_member`
Metering	`list_customer_meters`, `get_customer_meter`
Tokens	`list_organization_access_tokens`

The metering tools matter for usage-based and AI billing: ask “how many metered events has cus_h4k2 logged this cycle?” and the agent reads the customer’s meters straight from the same pipeline that aggregates ingested events into billable usage.

Mutations (client confirms each one)

Category	Tools
Customers	`create_customer`, `update_customer`
Products	`create_product`, `update_product`, `create_price`
Subscriptions	`update_subscription`, `cancel_subscription`, `uncancel_subscription`
Refunds	`create_refund`
Orders	`update_order`
Members	`create_member`, `update_member`, `delete_member`
Tokens	`create_organization_access_token`, `delete_organization_access_token`

Composed analytics

Each of these fans out to several primitives and returns one synthesized answer — faster and more reliable than asking the agent to assemble the calls itself.

Tool	Returns
`revenue_today`	Today’s settled revenue in your default currency
`mrr_snapshot`	Current MRR, week-over-week delta, per-product breakdown
`churn_30d`	30-day churn % plus churned-vs-total subscription counts
`top_customers`	Top N by 30-day spend or lifetime value
`explain_payment_failure`	Decoded decline reason and a suggested next step
`search_resources`	Fuzzy search across customers, orders, and subscriptions
`search_documentation`	Searches `handbook.macropay.com` and returns top hits

Agentic commerce (opt-in)

Let the agent act, not just read — create payment links and meter usage on your behalf. These two are off by default; an org admin enables them under Settings → Integrations → MCP, and the connecting token must carry the write scope. Full guide: Agentic Commerce via MCP.

Tool	Signature	Returns	Scope
`create_checkout`	`create_checkout(product_id, customer_email?, success_url?, amount?)`	Hosted checkout `url`, `id`, `status`	`checkouts:write`
`record_usage`	`record_usage(event_name, customer_id?, external_customer_id?, agent_id?, metadata?)`	`{ inserted, duplicates }`	`events:write`

If either gate is missing, the tool returns a clear agentic_commerce_disabled message instead of silently failing.

Health

Tool	Returns
`health_check`	Confirms auth and reports your org slug + granted scopes

How authorization works

Clicking Connect runs this flow:

Client opens the authorize endpoint

Your MCP client (Claude, Cursor, etc.) opens https://mcp.macropay.ai/oauth/authorize?....

Macropay prompts you to sign in

You’re redirected to app.macropay.ai/oauth2/authorize.

You pick one organization

The grant is scoped to a single org — if you run several, the token only ever sees the one you choose here.

You approve the scope list and click Allow

Macropay shows exactly which scopes the connector requests.

The client stores an Organization Access Token

It receives an Organization Access Token (macropay_oat_…) and sends it as a bearer on every subsequent tool call.

Scopes requested at install:

openid profile email
customers:read     customers:write
products:read      products:write
subscriptions:read subscriptions:write
orders:read        payments:read
refunds:read       refunds:write
metrics:read       webhooks:read
organizations:read

Tokens are org-scoped, revocable from the dashboard at any time (see revoking access), and structurally cannot read another organization’s data.

Token-based auth (Organization Access Token)

If your client can’t do OAuth, mint a long-lived Organization Access Token (OAT) and drop it into the client config.

Create the token

Dashboard → Settings → Developers → Organization Access Tokens → Create.

Name and scope it

Give it a descriptive name (e.g. cursor-ci-runner) and select scopes.

Copy it now

The value (starting macropay_oat_…) is shown once. Closing the modal hides it for good.

Wire it into the client as a bearer

{
  "mcpServers": {
    "macropay": {
      "url": "https://mcp.macropay.ai/mcp/macropay-mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer macropay_oat_YOUR_TOKEN_HERE"
      }
    }
  }
}

OATs don’t expire by default and can be revoked from the dashboard whenever you want.

Revoking access

Three interchangeable routes, all immediate:

Dashboard — Settings → Developers → Organization Access Tokens → Revoke on the row.
Client — Claude Desktop → Connectors → Macropay → Disconnect (revokes server-side too).
API — DELETE /v1/organization-access-tokens/{id} with any valid auth.

The token dies on the spot. The next call from any client still holding it gets 401 invalid_token.

Security model

Property	Behavior
Token scope	One organization. A second org needs a separate install.
Token storage	OS keychain (Claude Desktop), system credential store (Cursor), or whatever your client uses.
Transport	HTTPS only, TLS 1.2+. CORS is open by design — browser-based MCP clients require it.
Mutations	Your client prompts for approval on every mutating call. Macropay never bypasses that gate.
Audit log	Each call is logged server-side with `organization_access_token_id`, tool name, and status. Settings → Developers → Audit Log.
Rate limits	Same per-org limits as the REST API — currently `100 tool-calls/minute/org`.
Compromise	Revoke a leaked token instantly. Minting a new one requires a fresh OAuth round-trip, which requires a Macropay login.

Macropay is PCI DSS Level 1 compliant. Card data is tokenized in our PCI-compliant vault and never reaches the MCP layer — tools operate on customers, orders, and subscriptions, never raw card numbers.

Troubleshooting

Connected, but no tools show up

Give it 10 seconds and refresh. The first connect provisions the tool catalog from the server — usually instant, occasionally slower on a bad network. Still empty after 30s? Disconnect and reconnect.

OAuth says 'invalid redirect URI'

Your client is using a redirect URL we haven’t pre-registered. Email support@macropay.ai with the URL — registering it is a one-line change.

A call returns 401 invalid_token

The token was revoked — by you, an admin, or the dashboard’s rotation policy. Disconnect and reconnect in your client.

A call returns 403 insufficient_scope

The connector holds a narrower scope set than the tool needs — usually because it was granted before a newer write scope existed. Reconnect; the OAuth screen will list the updated scopes.

Reads work but mutations don't

Same root cause: the client requested read-only scopes. Reconnect with the write scopes ticked.

ChatGPT won't connect

ChatGPT custom connectors need a paid plan (Pro / Team / Enterprise). Free accounts can’t use remote MCP servers yet.

The agent picks the wrong tool or invents results

Get specific. “Run revenue_today” forces the composed tool. If a generated tool’s description reads ambiguously, file an issue — we can hand-author a clearer override.

FAQ

Is this safe for production agents?

Yes. The MCP server shares infrastructure with the Macropay dashboard — same SLA, same audit trail. Use a dedicated OAT per environment (not a Claude Desktop OAuth token) so you can rotate each one independently.

Is there a sandbox?

Yes. Connect with a sandbox-mode OAT (Dashboard → Sandbox → Settings → Developers → OATs) rather than the OAuth flow. The same mcp.macropay.ai URL serves it — your auth determines which org and mode you hit.

Does it cost extra?

No. MCP usage adds nothing beyond your normal Macropay account — no per-call surcharge.

Can I give finance read-only access?

Mint an OAT scoped to *:read only and share it through your secrets manager. Finance pastes it into their MCP client, asks revenue / churn / customer questions all day, and can never mutate a thing.

Can I add custom tools?

Not in v1. Merchant-defined tools (e.g. “fetch the customer’s HubSpot record”) are on the table for v2 — tell us if you’d use it.

What happens to my data?

Tool calls run through the same FastAPI routes the dashboard uses. The MCP server stores, caches, and logs nothing about the responses — only that a call happened. Your AI client holds the response locally; it leaves your machine only if that client forwards it to its own backend (Anthropic, OpenAI, and Cursor do this for inference, per their privacy policies).

Where do I see which tools ran?

Dashboard → Settings → Developers → Audit Log. Filter by OAT name to scope it. Each row shows timestamp, tool, HTTP status, and response time.

Patterns worth keeping

Once connected, your assistant reaches as far into operations as a dashboard-fluent engineer. A few setups that pay off:

Daily digest — pin “Give me a morning Macropay digest” in your client and run it each morning. The agent calls revenue_today + mrr_snapshot + churn_30d + list_payments (filtered to failures) and writes you a brief.
Support triage — when a customer flags a failed charge, paste the payment id and say “explain this failure and draft a reply.” The agent runs explain_payment_failure + get_customer and produces the email.
Board-ready QBR — “Build a QBR for Q3: revenue, MRR trajectory, top customers, churn, biggest disputes — output markdown.” The agent fans out a dozen calls and assembles the doc.

Stuck on a use case?

Email support@macropay.ai with your prompt and the agent’s output. We’re continuously tuning tool descriptions so agents reach for the right one.

Bootup

Features

Integrate

Merchant of Record (MoR)

Macropay MCP Server

Things to ask once you’re connected

Connect in five minutes

Your first multi-tool prompt

The toolbox

Read-only

Mutations (client confirms each one)

Composed analytics

Agentic commerce (opt-in)

Health

How authorization works

Token-based auth (Organization Access Token)

Revoking access

Security model

Troubleshooting

FAQ

Patterns worth keeping

Stuck on a use case?

​Things to ask once you’re connected

​Connect in five minutes

​Your first multi-tool prompt

​The toolbox

​Read-only

​Mutations (client confirms each one)

​Composed analytics

​Agentic commerce (opt-in)

​Health

​How authorization works

​Token-based auth (Organization Access Token)

​Revoking access

​Security model

​Troubleshooting

​FAQ

​Patterns worth keeping

Stuck on a use case?

Things to ask once you’re connected

Connect in five minutes

Your first multi-tool prompt

The toolbox

Read-only

Mutations (client confirms each one)

Composed analytics

Agentic commerce (opt-in)

Health

How authorization works

Token-based auth (Organization Access Token)

Revoking access

Security model

Troubleshooting

FAQ

Patterns worth keeping