> ## 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 over Model Context Protocol (MCP)

> Give your AI agents and assistants live access to your Macropay account through a hosted MCP server.

<img src="https://mintcdn.com/macrodeepinc/Uu6hOe0dMZnKqgkh/assets/integrate/mcp/mcp.png?fit=max&auto=format&n=Uu6hOe0dMZnKqgkh&q=85&s=5210ccbfe5db0e89b80884428709aec0" width="2676" height="1592" data-path="assets/integrate/mcp/mcp.png" />

Macropay ships a hosted **Model Context Protocol (MCP)** server, so any MCP-capable assistant or agent can read and act on your account in plain language — "what did we bill last week?", "create a sandbox product", "list customers with an active subscription" — without you writing a line of glue code.

Because Macropay is the **merchant of record**, those same agents operate on top of tax-compliant, dispute-managed billing data. The numbers an agent reads back are already net of the sales tax and VAT we remit on your behalf.

## Why connect over MCP

<CardGroup cols={3}>
  <Card title="Conversational ops" icon="comments">
    Query orders, customers, and revenue from inside your AI client — no dashboard tab-switching.
  </Card>

  <Card title="Agent tooling" icon="robot">
    Expose Macropay as a first-class tool so autonomous agents can manage products and read billing context.
  </Card>

  <Card title="Safe to experiment" icon="flask">
    Point at the sandbox server to try destructive actions against test data before touching production.
  </Card>
</CardGroup>

## What you'll need

* An **MCP-capable client** — Claude Desktop, Claude Code, Cursor, Windsurf, Codex, or ChatGPT (Developer Mode).
* A Macropay account. The server authenticates you through your client's standard MCP login flow on first connect.

## Choose your server

Macropay exposes two remote endpoints. Pick the one that matches the environment you want the agent to touch.

| Environment    | URL                                            | Use it for                                   |
| -------------- | ---------------------------------------------- | -------------------------------------------- |
| **Production** | `https://mcp.macropay.ai/mcp/macropay-mcp`     | Your live organization and real billing data |
| **Sandbox**    | `https://mcp.macropay.ai/mcp/macropay-sandbox` | Testing against disposable data              |

<Warning>
  The production server acts on real customers, orders, and payouts. When you're prototyping agent behavior, connect to the **sandbox** endpoint first.
</Warning>

Anywhere a client lets you paste a raw MCP URL, use one of the two above. If a client instead wants a launch **command**, wrap the URL with `mcp-remote`:

<CodeGroup>
  ```json Production theme={null}
  {
    "mcpServers": {
      "Macropay": {
        "command": "npx",
        "args": ["mcp-remote", "https://mcp.macropay.ai/mcp/macropay-mcp"]
      }
    }
  }
  ```

  ```json Sandbox theme={null}
  {
    "mcpServers": {
      "Macropay Sandbox": {
        "command": "npx",
        "args": ["mcp-remote", "https://mcp.macropay.ai/mcp/macropay-sandbox"]
      }
    }
  }
  ```
</CodeGroup>

## Client setup

Configuration differs slightly per client. Find yours below — each tab shows the production setup, with the sandbox variant alongside it.

<Tabs>
  <Tab title="Cursor">
    Add the server to `.cursor/mcp.json`:

    <CodeGroup>
      ```json Production theme={null}
      {
        "mcpServers": {
          "Macropay": {
            "url": "https://mcp.macropay.ai/mcp/macropay-mcp"
          }
        }
      }
      ```

      ```json Sandbox theme={null}
      {
        "mcpServers": {
          "Macropay Sandbox": {
            "url": "https://mcp.macropay.ai/mcp/macropay-sandbox"
          }
        }
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Windsurf">
    Add the server to `mcp_config.json`:

    <CodeGroup>
      ```json Production theme={null}
      {
        "mcpServers": {
          "Macropay": {
            "command": "npx",
            "args": ["mcp-remote", "https://mcp.macropay.ai/mcp/macropay-mcp"]
          }
        }
      }
      ```

      ```json Sandbox theme={null}
      {
        "mcpServers": {
          "Macropay Sandbox": {
            "command": "npx",
            "args": ["mcp-remote", "https://mcp.macropay.ai/mcp/macropay-sandbox"]
          }
        }
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Codex">
    Add the server to `~/.codex/config.toml`, then run the login command.

    <CodeGroup>
      ```toml Production theme={null}
      [features]
      rmcp_client = true

      [mcp_servers.macropay]
      type = "http"
      url = "https://mcp.macropay.ai/mcp/macropay-mcp"
      ```

      ```toml Sandbox theme={null}
      [features]
      rmcp_client = true

      [mcp_servers.macropay_sandbox]
      type = "http"
      url = "https://mcp.macropay.ai/mcp/macropay-sandbox"
      ```
    </CodeGroup>

    ```sh theme={null}
    codex mcp login macropay
    ```

    For sandbox, log in with `codex mcp login macropay_sandbox` instead.
  </Tab>

  <Tab title="Claude Code">
    Register the server over HTTP transport:

    ```bash theme={null}
    claude mcp add --transport http "Macropay" "https://mcp.macropay.ai/mcp/macropay-mcp"
    ```

    For sandbox:

    ```bash theme={null}
    claude mcp add --transport http "Macropay-Sandbox" "https://mcp.macropay.ai/mcp/macropay-sandbox"
    ```
  </Tab>

  <Tab title="ChatGPT">
    <Note>
      MCP support is in beta and limited to paid ChatGPT web accounts with **Developer Mode** turned on.
    </Note>

    <Steps>
      <Step title="Enable Developer Mode">
        Turn on Developer Mode in your ChatGPT settings.
      </Step>

      <Step title="Add the connector">
        Open **Settings → Connectors** and add the MCP server `https://mcp.macropay.ai/mcp/macropay-mcp`. For testing, use `https://mcp.macropay.ai/mcp/macropay-sandbox` instead.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Desktop">
    <Steps>
      <Step title="Open connector settings">
        Go to **Settings → Connectors** and click **Add custom connector**.
      </Step>

      <Step title="Add the server">
        Name it `Macropay` and set the server URL to `https://mcp.macropay.ai/mcp/macropay-mcp`. For sandbox, use `https://mcp.macropay.ai/mcp/macropay-sandbox`.
      </Step>

      <Step title="Connect">
        Save, then click **Connect** to authenticate against your Macropay organization.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Tip>
  Once connected, try a read-only prompt first — for example "summarize this month's orders" — to confirm the agent is reaching the right environment before you let it create or modify anything.
</Tip>