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

# HitPay MCP Server

> Connect Claude, Codex, Cursor, and other MCP clients to your HitPay business data. Query sales, transactions, payouts, and balances, or create payment links and invoices from an AI assistant. Authenticates with your HitPay login over OAuth.

The HitPay MCP Server is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server at `https://mcp.hit-pay.com`. It gives AI assistants such as Claude access to your HitPay business data: you can query sales, transactions, payouts, and balances in natural language, and create payment links, invoices, products, and recurring plans.

Authentication uses OAuth. You sign in with your HitPay dashboard login and authorize the connection for one business. API keys are not involved, and each connection is scoped to the business it was authorized for.

<Info>
  Looking to **build a payment integration** with AI instead? That's the [Claude Code Plugin](/apis/guide/claude-code-plugin), a developer tool that connects Claude to the HitPay **API** using your API key. The MCP Server on this page connects an AI assistant to your **business data** using your HitPay login.
</Info>

## Setup

All clients connect to the same endpoint:

```
https://mcp.hit-pay.com/
```

Whichever client you use, connecting opens the HitPay login page in your browser. Sign in, pick which business to connect under **Connect as**, and approve.

<Frame>
  <img src="https://mintcdn.com/hitpay/Ed-KWI7XpH4maDrk/images/mcp-server-authorize.png?fit=max&auto=format&n=Ed-KWI7XpH4maDrk&q=85&s=c69c6d2049c18f1774ae3d4949d3d0b6" alt="HitPay authorization screen showing the requested permission and the business picker" width="3130" height="1910" data-path="images/mcp-server-authorize.png" />
</Frame>

<Warning>
  Only users with the **owner** or **admin** role on a business can authorize a connection. Other team-member roles (such as staff or cashier) cannot connect.
</Warning>

### Claude

1. Open **Settings → Connectors** in [claude.ai](https://claude.ai) or the Claude desktop app
2. Click **Add custom connector**
3. Enter the URL `https://mcp.hit-pay.com/` and save
4. Click **Connect**, sign in, and approve access

The HitPay tools are then available in Claude's tool menu.

### Claude Code

```bash theme={"system"}
claude mcp add --transport http hitpay https://mcp.hit-pay.com/
```

Then run `/mcp` inside Claude Code, select **hitpay**, and choose **Authenticate** to complete the browser sign-in.

<Frame>
  <img src="https://mintcdn.com/hitpay/Ed-KWI7XpH4maDrk/images/mcp-server-auth-success.png?fit=max&auto=format&n=Ed-KWI7XpH4maDrk&q=85&s=60bd0fe7a8459c20871a4b8dc42f6522" alt="Authentication successful page after approving access in the browser" width="3130" height="1910" data-path="images/mcp-server-auth-success.png" />
</Frame>

### Codex

```bash theme={"system"}
codex mcp add hitpay --url https://mcp.hit-pay.com/
```

Complete the browser sign-in when Codex prompts you.

### Cursor

Add the server to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project), then complete the sign-in when Cursor prompts you:

```json theme={"system"}
{
  "mcpServers": {
    "hitpay": {
      "url": "https://mcp.hit-pay.com/"
    }
  }
}
```

### Other clients

Any MCP client that supports the **streamable HTTP** transport and **OAuth 2.0 with PKCE and dynamic client registration** can connect. Discovery metadata is published at `https://mcp.hit-pay.com/.well-known/oauth-authorization-server`. Native and desktop clients that use loopback (`localhost`) redirect URIs work without extra configuration; web-based clients other than claude.ai are not currently allowlisted for registration.

## Example prompts

Once connected, the assistant can answer questions and perform tasks like:

* "What were my total sales last month, and how do they compare to the month before?"
* "Show my top-selling products this quarter"
* "List my recent transactions above SGD 100"
* "When is my next payout, and what's my current balance?"
* "Which payment methods do I have enabled?"
* "Create a payment link for SGD 49.90 for a consultation session"
* "Invoice [acme@example.com](mailto:acme@example.com) SGD 1,200 for March services and email it to them"

## Available tools

The server exposes 24 tools: 20 read tools and 4 create tools.

| Category               | Tools                                                                                                                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Sales & analytics**  | `get_sales_summary`, `get_top_products`, `get_sales_by_payment_method`, `get_sales_by_category`, `get_transactions_volume`, `get_channel_distribution`, `get_growth_indicator` |
| **Transactions**       | `list_charges`, `get_charge_details`, `get_charge_refunds`                                                                                                                     |
| **Payouts & balances** | `list_payouts`, `get_payout_schedule`, `get_balances`                                                                                                                          |
| **Commerce records**   | `list_orders`, `list_invoices`, `list_payment_links`, `get_payment_link`                                                                                                       |
| **Create**             | `create_payment_link`, `create_invoice`, `create_product`, `create_recurring_plan`                                                                                             |
| **Account**            | `get_payment_methods`, `get_verification_status`, `get_integrations`                                                                                                           |

The assistant selects tools automatically based on your prompt. You don't call them directly.

### Excluded operations

The server does not expose:

* Refunds, or cancelling and modifying transactions
* Payout or transfer operations
* Changes to account settings, payment methods, or team members

The only write operations are the four `create_*` tools listed above; everything else is read-only.

## Security

* **OAuth 2.0** authorization code flow with PKCE. You approve access on `dashboard.hit-pay.com`, and your password is never shared with the AI assistant or client
* **Business-scoped tokens**: a connection can only see the business it was authorized for
* **Owner and admin only**: other team-member roles cannot authorize a connection
* **Rate limited** to 30 requests per minute per business
* **Revocable**: remove the connector from your MCP client to stop it making new requests

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Do I need an API key?">
    No. The MCP Server authenticates with your HitPay account login via OAuth. API keys are only used by the developer tools ([Claude Code Plugin](/apis/guide/claude-code-plugin), [Agent Skills](/apis/guide/ai-skills), and the [CLI](/apis/guide/cli)).
  </Accordion>

  <Accordion title="How is this different from the Claude Code Plugin's MCP server?">
    Both use the Model Context Protocol, but they serve different audiences. The **MCP Server** (this page) is hosted by HitPay, authenticates with your account login, and is for querying and operating your business from an AI assistant. The **Claude Code Plugin** runs locally inside Claude Code, authenticates with an API key, and is for developers building payment integrations. It exposes integration-focused API tools and code-generation skills.
  </Accordion>

  <Accordion title="Is it safe to connect to my live business?">
    The server exposes no destructive operations: it cannot refund, cancel, transfer money, or change settings. The only writes are creating payment links, invoices, products, and recurring plans, all of which are visible in your dashboard and can be deactivated there.
  </Accordion>

  <Accordion title="Can my team members connect?">
    Team members with the **admin** role can connect, in addition to the account owner. Other roles cannot authorize a connection. Tokens are always scoped to the single business that was authorized.
  </Accordion>

  <Accordion title="Does it work with the sandbox environment?">
    Not yet. The MCP Server is currently available for live accounts at `mcp.hit-pay.com` only.
  </Accordion>

  <Accordion title="Which AI assistants can I use?">
    Claude (web and desktop), Claude Code, Codex, and Cursor are covered above. Any other native MCP client that supports the streamable HTTP transport with OAuth and loopback redirects also works.
  </Accordion>
</AccordionGroup>

## Resources

<CardGroup cols={2}>
  <Card title="Claude Code Plugin" icon="microchip-ai" href="/apis/guide/claude-code-plugin">
    Build payment integrations with live API access
  </Card>

  <Card title="Agent Skills" icon="wand-magic-sparkles" href="/apis/guide/ai-skills">
    Code generation for Cursor, Copilot, and Windsurf
  </Card>

  <Card title="HitPay CLI" icon="terminal" href="/apis/guide/cli">
    Drive the API from your terminal and CI pipelines
  </Card>

  <Card title="Model Context Protocol" icon="plug" href="https://modelcontextprotocol.io">
    Learn more about MCP
  </Card>
</CardGroup>