> For the complete documentation index, see [llms.txt](https://docs.uppercut.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uppercut.co/integration/merchant-mcp.md).

# Merchant MCP

OAuth-secured Model Context Protocol for Uppercut merchants. Connect Claude, Cursor, or any MCP client to one team so agents can validate tracking, manage campaigns, review sales, list leads, and read

In-app setup: [app.uppercut.co/agents/mcp](https://app.uppercut.co/agents/mcp) · Agents overview: [app.uppercut.co/agents](https://app.uppercut.co/agents)

Related: [Track Sales (API)](https://docs.uppercut.co/integration/track-sales-api) · [Track Sales (Stripe)](https://docs.uppercut.co/integration/track-sales-stripe) · [Test your integration](https://docs.uppercut.co/guides/test-your-integration)

### Connect (Cursor / Claude)

1. Point the client at `https://app.uppercut.co` (one-click via `[.well-known/mcp.json](https://app.uppercut.co/.well-known/mcp.json)`) or add remote MCP URL `https://app.uppercut.co/mcp`.
2. The client registers via `/oauth/register` (Dynamic Client Registration), or discovers OAuth from `.well-known`.
3. Sign in to Uppercut, pick a team on the consent screen, then Allow access.
4. Example prompts: “Read my status board”, “List leads with email and affiliate”, “Validate tracking”, “Create a 20% campaign for Acme”.

Marketing discovery card (same shape) lives on [uppercut.co](https://uppercut.co/mcp). Canonical OAuth + MCP runtime is always `app.uppercut.co`.

#### Endpoints

| Purpose                       | URL                                                              |
| ----------------------------- | ---------------------------------------------------------------- |
| MCP server card (app origin)  | `https://app.uppercut.co/.well-known/mcp.json`                   |
| MCP                           | `https://app.uppercut.co/mcp`                                    |
| Authorize                     | `https://app.uppercut.co/oauth/authorize`                        |
| Token                         | `https://app.uppercut.co/oauth/token`                            |
| Register (DCR)                | `https://app.uppercut.co/oauth/register`                         |
| Authorization server metadata | `https://app.uppercut.co/.well-known/oauth-authorization-server` |
| Protected resource metadata   | `https://app.uppercut.co/.well-known/oauth-protected-resource`   |

#### Auth model

* OAuth 2.1 with PKCE (`S256`)
* Public clients (`token_endpoint_auth_method: none`) via Dynamic Client Registration
* Access tokens are **team-scoped** (one team per consent)
* Bearer token on `POST /mcp` (JSON-RPC)

#### Scopes

| Scope            | Access                                                                                               |
| ---------------- | ---------------------------------------------------------------------------------------------------- |
| `merchant:read`  | List and read tools                                                                                  |
| `merchant:write` | Create/update campaigns, remove affiliates, approve/reject sales, upload assets, payout funding link |

### Tools

#### Setup and status

| Tool                | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| `validate_tracking` | Check click / signup / sale tracking status for the team   |
| `read_status_board` | Read merchant status-board tasks                           |
| `lookup_docs`       | Look up Uppercut docs (`docs.uppercut.co`, see `llms.txt`) |

#### Campaigns

| Tool              | Scope | Description                                                                                                                                     |
| ----------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_campaign` | write | Create a campaign (`name`, `reward_type` = `percentage` \| `fixed`, `reward_value`; optional cookie/commission/holding windows and destination) |
| `get_campaign`    | read  | Campaign details including destinations                                                                                                         |
| `update_campaign` | write | Update editable campaign fields (including `archived`)                                                                                          |
| `add_destination` | write | Add a landing-page destination to a campaign                                                                                                    |

#### Affiliates

| Tool                | Scope | Description                                                                                      |
| ------------------- | ----- | ------------------------------------------------------------------------------------------------ |
| `list_affiliates`   | read  | List affiliates on the team’s programs                                                           |
| `search_affiliates` | read  | Search by name or email                                                                          |
| `get_affiliate`     | read  | Profile and metrics                                                                              |
| `remove_affiliate`  | write | Remove from all team programs, reject open sales, **permanently ban rejoin** (requires `reason`) |

#### Sales and leads

| Tool           | Scope | Description                                               |
| -------------- | ----- | --------------------------------------------------------- |
| `list_sales`   | read  | List commissions (optional `status`, `limit`)             |
| `approve_sale` | write | Approve a commission for payout                           |
| `reject_sale`  | write | Reject a commission                                       |
| `list_leads`   | read  | Signup leads (email / user ID) with affiliate attribution |

#### Assets and payouts

| Tool                | Scope | Description                                                  |
| ------------------- | ----- | ------------------------------------------------------------ |
| `list_assets`       | read  | List creative assets                                         |
| `upload_asset`      | write | Upload an asset from a public URL                            |
| `add_payout_method` | write | Create a Stripe Checkout link to add a payout funding method |

### Protocol notes

* Server name: `uppercut-merchant` (MCP protocol `2024-11-05`)
* Supported methods: `initialize`, `notifications/initialized`, `tools/list`, `tools/call`, `ping`
* Tool results return JSON text in MCP `content` blocks
* Write tools without `merchant:write` return a clear scope error

### Safety

* Prefer `validate_tracking` and `read_status_board` before suggesting setup work
* `remove_affiliate` needs a clear reason and permanently blocks that affiliate from rejoining
* Never invent affiliate, campaign, or commission IDs; call list/get tools first

### What MCP does not do

* Record sales or refunds (use the REST API or Stripe Connect)
* Span multiple teams in one OAuth grant
* Allow unauthenticated access