> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macropay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Macropay MCP Server

> Run your Macropay billing from any AI client — refunds, MRR, churn, plan changes — over one OAuth-secured MCP connection.

Your billing stack is the one system you least want to context-switch into.
The [Model Context Protocol](https://modelcontextprotocol.io) 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.

<Note>
  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.
</Note>

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?"*

<Tip>
  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.
</Tip>

***

## Connect in five minutes

<Tabs>
  <Tab title="Claude Desktop">
    **The true one-click path.**

    1. Open Claude Desktop, go to **Settings** (⌘,) → **Connectors**.
    2. Choose **Add custom connector**.
    3. Enter:
       * **Name**: `Macropay`
       * **Server URL**: `https://mcp.macropay.ai/mcp/macropay-mcp`
    4. Hit **Connect**.
    5. A browser tab opens at `app.macropay.ai/oauth2/authorize`. Sign in, choose
       the organization to grant, and click **Allow**.
    6. 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.
  </Tab>

  <Tab title="Claude Code">
    Run this from any project directory:

    ```bash theme={null}
    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:

    ```bash theme={null}
    claude mcp list
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project):

    ```json theme={null}
    {
      "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**.
  </Tab>

  <Tab title="ChatGPT (Pro / Team / Enterprise)">
    1. In ChatGPT, go to **Settings → Connectors → Add custom connector**.
    2. **Server URL**: `https://mcp.macropay.ai/mcp/macropay-mcp`
    3. **Authentication**: **OAuth**.
    4. **Connect** → authorize → done.

    The tools land in the connector picker under the chat input.
  </Tab>

  <Tab title="Windsurf / Codex / others">
    Any client that speaks remote HTTP transport with OAuth works untouched.

    Generic config:

    ```json theme={null}
    {
      "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](#manual-auth-organization-access-token) below.
  </Tab>
</Tabs>

***

## 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](/features/integrations/mcp-agentic-commerce).

| 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:

<Steps>
  <Step title="Client opens the authorize endpoint">
    Your MCP client (Claude, Cursor, etc.) opens
    `https://mcp.macropay.ai/oauth/authorize?...`.
  </Step>

  <Step title="Macropay prompts you to sign in">
    You're redirected to `app.macropay.ai/oauth2/authorize`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="You approve the scope list and click Allow">
    Macropay shows exactly which scopes the connector requests.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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](#revoking-access)), and structurally **cannot** read another
organization's data.

***

<h2 id="manual-auth-organization-access-token">
  Token-based auth (Organization Access Token)
</h2>

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

<Steps>
  <Step title="Create the token">
    **Dashboard → Settings → Developers → Organization Access Tokens → Create.**
  </Step>

  <Step title="Name and scope it">
    Give it a descriptive name (e.g. `cursor-ci-runner`) and select scopes.
  </Step>

  <Step title="Copy it now">
    The value (starting `macropay_oat_…`) is shown once. Closing the modal hides
    it for good.
  </Step>

  <Step title="Wire it into the client as a bearer">
    ```json theme={null}
    {
      "mcpServers": {
        "macropay": {
          "url": "https://mcp.macropay.ai/mcp/macropay-mcp",
          "transport": "http",
          "headers": {
            "Authorization": "Bearer macropay_oat_YOUR_TOKEN_HERE"
          }
        }
      }
    }
    ```
  </Step>
</Steps>

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

***

<h2 id="revoking-access">
  Revoking access
</h2>

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.         |

<Info>
  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.
</Info>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="OAuth says 'invalid redirect URI'">
    Your client is using a redirect URL we haven't pre-registered. Email
    **[support@macropay.ai](mailto:support@macropay.ai)** with the URL — registering it is a one-line change.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Reads work but mutations don't">
    Same root cause: the client requested read-only scopes. Reconnect with the
    write scopes ticked.
  </Accordion>

  <Accordion title="ChatGPT won't connect">
    ChatGPT custom connectors need a paid plan (Pro / Team / Enterprise). Free
    accounts can't use remote MCP servers yet.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Does it cost extra?">
    No. MCP usage adds nothing beyond your normal Macropay account — no per-call
    surcharge.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## 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.

***

<Card title="Stuck on a use case?" icon="lifebuoy" href="mailto:support@macropay.ai">
  Email **[support@macropay.ai](mailto:support@macropay.ai)** with your prompt and the agent's output. We're
  continuously tuning tool descriptions so agents reach for the right one.
</Card>