# Merchant MCP — connect guide

> OAuth-secured Model Context Protocol so Claude, Cursor, or any MCP client can operate a merchant’s Uppercut team: campaigns, affiliates, leads, sales review, tracking checks, assets, payouts setup.

Status: shipped (not a waitlist). Interactive setup: https://app.uppercut.co/agents/mcp

## MCP endpoint

- Transport: streamable HTTP
- URL: `https://app.uppercut.co/mcp` (POST)
- Auth: Bearer access token (`uca_…`) after OAuth

## Discovery files

- Server card: https://uppercut.co/.well-known/mcp.json
- Legacy card path: https://uppercut.co/.well-known/mcp/server-card.json
- Agent catalog: https://uppercut.co/.well-known/agents.json
- Site context: https://uppercut.co/llms.txt
- Full context: https://uppercut.co/llms-full.txt

Canonical OAuth metadata lives on the app origin (same origin as `/mcp`):

- AS metadata: https://app.uppercut.co/.well-known/oauth-authorization-server
- Resource metadata: https://app.uppercut.co/.well-known/oauth-protected-resource

## Connect flow

1. Point the MCP client at `POST https://app.uppercut.co/mcp`
2. Discover OAuth via `.well-known`, or register with Dynamic Client Registration: `POST https://app.uppercut.co/oauth/register`
3. User signs in, picks **one team** on the consent screen, Allow
4. Client calls `/mcp` with `Authorization: Bearer uca_…`

## OAuth endpoints

| Purpose | URL |
| --- | --- |
| Authorize | https://app.uppercut.co/oauth/authorize |
| Token | https://app.uppercut.co/oauth/token |
| Register (DCR) | https://app.uppercut.co/oauth/register |

Requirements: OAuth 2.1, PKCE (S256), public clients (`token_endpoint_auth_method: none`). Tokens are team-scoped.

## Scopes

| Scope | What it allows |
| --- | --- |
| merchant:read | List/read tools |
| merchant:write | Create/update campaigns, destinations, remove affiliates, approve/reject sales, upload assets, payout funding link |

## Tools (18)

### Setup / status

- `validate_tracking` — click / signup / sale tracking health
- `read_status_board` — merchant status-board tasks
- `lookup_docs` — docs.uppercut.co pointers

### Programs

- `create_campaign` — name, reward_type (`percentage`|`fixed`), reward_value, optional windows + destination
- `get_campaign` / `update_campaign`
- `add_destination` — landing page on a campaign

### Affiliates

- `list_affiliates` / `search_affiliates` / `get_affiliate`
- `remove_affiliate` — requires reason; rejects open sales; permanent ban from rejoining

### Sales & leads

- `list_sales` / `approve_sale` / `reject_sale`
- `list_leads` — signup email / user ID + affiliate attribution

### Assets & payouts

- `list_assets` / `upload_asset` (from public URL)
- `add_payout_method` — Stripe Checkout link to add funding method

### Write tools (require `merchant:write`)

`create_campaign`, `update_campaign`, `add_destination`, `remove_affiliate`, `approve_sale`, `reject_sale`, `upload_asset`, `add_payout_method`

## Example prompts

- Read my status board
- List leads with email and affiliate
- Validate tracking
- Create a 20% campaign for Acme

## MCP vs REST

- MCP = program ops for one signed-in team
- REST/Stripe (including `/api/track-sale`) = recording payments
- Docs: https://docs.uppercut.co/ — append `.md` to page URLs; `lookup_docs` surfaces them

## Do not claim

- MCP sale-recording tools (no `track_sale` on this server)
- Multi-team tokens in one connection
- Unauthenticated access

## Human pages

- Marketing: https://uppercut.co/mcp
- App setup: https://app.uppercut.co/agents and https://app.uppercut.co/agents/mcp