---
id: "api-reference/mcp"
type: "doc"
url: "https://affitor.com/docs/api-reference/mcp"
kind: "reference"
updated: "2026-11-08"
---
# Affitor MCP server

> Reference for the hosted Affitor MCP server at https://mcp.affitor.com/mcp: which apps can connect, sign-in and consent, read-only tools, limits and removal.

The Affitor MCP server lets an AI app read your Affitor data: a brand's program, partners, applications, commissions and billing, or a partner's programs, links, earnings, commissions and payouts. It is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server. You sign in with your Affitor account, no API key needed, and the connection is read-only: it cannot change data or move money.

```text
https://mcp.affitor.com/mcp
```

| | |
|---|---|
| Server URL | `https://mcp.affitor.com/mcp` |
| Transport | Streamable HTTP |
| Sign-in | OAuth 2.1 with PKCE (S256) and dynamic client registration |
| Scope | `read` (the only scope) |
| Access | Read-only. A connection reads the programs you choose when you connect: all current and future programs, or up to 50 you select. A partner connection sees only that partner |

<Flow>
  <FlowStep caption="Use the URL above. Connect your AI tool has the steps for each app it lists and for any other MCP client.">
    **Add the server** in your AI app
  </FlowStep>
  <FlowStep caption="Your browser opens affitor.com.">
    **Sign in** with your Affitor account
  </FlowStep>
  <FlowStep caption="Choose the programs the app can read, as a brand or as a partner.">
    **Choose what to share** and click **Allow**
  </FlowStep>
  <FlowStep caption="The app sees the tools for your connection type.">
    **Ask your AI app** about your program or earnings
  </FlowStep>
</Flow>

---

## Connect your AI app

Server URL: `https://mcp.affitor.com/mcp`. [Connect your AI tool](/docs/api-reference/connect-ai-tool) has the steps for each app it lists and for any other MCP client.

In the Affitor dashboard, **Connect an AI tool** shows the server URL and steps for Claude, ChatGPT, Cursor, VS Code, Claude Code and Codex, and under **Other** for Grok, Muse Code and any other MCP client. Brands find it in the program menu under **Program settings**, then **Developers** › **AI agents**. Partners click their name at the bottom of the left menu to open the account menu, then **Integrations**.

### Which apps can connect

After you sign in, Affitor sends you back to the app. It accepts only these return addresses:

- `claude.ai` and `claude.com` (Claude)
- `chatgpt.com` (ChatGPT)
- `www.cursor.com` (Cursor)
- `grok.com/connectors-oauth-exchange-code/` (Grok)
- `vscode.dev/redirect` and `insiders.vscode.dev/redirect` (VS Code)
- `www.perplexity.ai/rest/connections/oauth_callback` and `enterprise.perplexity.ai/rest/connections/oauth_callback` (Perplexity, including Perplexity Enterprise)
- `www.town.com/api/mcp/oauth/callback` and `town.com/api/mcp/oauth/callback` (Town)
- `manufact.com/inspector/oauth/callback` (Manufact inspector)
- apps on your own computer: `http://127.0.0.1` or `http://localhost`, any port

An app that registers any other address is refused when it registers, with the error "redirect_uris must be https on a supported AI app host, or http on 127.0.0.1 or localhost".

---

## Sign in and allow access

When your AI app connects, your browser opens **Connect an AI tool** on affitor.com. If you are signed out, you sign in first and come back to the same screen.

1. The title names the app: **Claude wants to access Affitor**, or **An app on this computer wants to access Affitor** for a desktop or terminal app. A desktop or terminal app also shows **Unverified** and the name it gives itself in quotes ("It calls itself …"), because any app on your computer can call itself "Claude".
2. Check the account shown, your name and email. To use another Affitor account, click **Switch**.
3. If you are both a brand and a partner, choose **As a brand** or **As a partner**.
4. Choose the programs the app can read: **All current and future programs**, or up to 50 programs you select. As a brand you need to be an active member of each program; as a partner you choose among the programs you are a partner in.
5. Under **Access**, **Read account data** is **Always on**. Click it to see what the app can read: programs and settings, partners and applications, clicks and leads, commissions and billing for a brand; the programs you joined, your links and clicks, your earnings and commissions, and your payouts for a partner. The screen also says **Money actions always happen in Affitor**.
6. Click **Allow**, or **Cancel** to refuse.

A connection keeps the programs you chose. With **All current and future programs**, programs you join later are included; a selection stays as it is. To change it, connect again and choose again.

<VerifySuccess
  browser={[
    "Your AI app lists the Affitor tools: `get_program` for a brand connection, `list_my_programs` for a partner connection",
  ]}
  dashboard={[
    "Brands: the connection appears on **Developers** › **AI agents** (program menu › **Program settings**), with **Added** and **Last used**",
    "Partners: the connection appears on **Integrations**, in the account menu that opens from your name",
  ]}
  ifNotWorking={[
    "**This request has expired**: start the connection again from your AI app",
    "**Nothing to connect yet**: create a program, or join one as a partner, first",
  ]}
/>

---

## Tools

Every tool is read-only, and the server declares it so on each tool: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. A brand connection gets the 8 brand tools across the programs it can read. A partner connection gets the 5 partner tools across that partner's programs it can read. Every tool takes an optional `program_id` to read one of those programs; `list_programs` lists them. A tool outside your connection's set is refused.

### Brand tools

| Tool | What it reads | Inputs |
|---|---|---|
| `list_programs` | The programs this connection can read, in id order, up to 50 per page. | `program_id`, `limit`, `cursor` |
| `get_program` | Each program, up to 25 per page: name, status, commission terms, setup checklist, 24-hour tracking counts, and the tracker install snippet with where to put it and how to verify it. | `program_id`, `programs_cursor` |
| `list_partners` | Partners who joined, newest first, with lifetime clicks, leads and sales, and earned and pending money in the window. | `from`, `to`, `limit`, `cursor` |
| `get_partner` | One partner by `partner_program_id`, with the same fields as `list_partners`. | `partner_program_id`, `from`, `to` |
| `list_applications` | Partner applications, newest first, with the applicant's own messages. | `status` (`approved`, `pending`, `rejected`), `limit`, `cursor` |
| `list_commissions` | Commissions, newest sale first, with what each still counts for after refunds. | `status`, `from`, `to`, `partner_program_id`, `limit`, `cursor` |
| `get_commission_summary` | Count and amount of commissions per status in the window, plus earned and pending. | `from`, `to` |
| `get_billing` | Affitor billing per program, up to 25 programs per page: what is due, this week's accrual, the platform fee and invoices, 20 per page. | `status` (`all`, `open`, `overdue`, `paid`, `void`), `page`, `program_id`, `programs_cursor` |

### Partner tools

| Tool | What it reads | Inputs |
|---|---|---|
| `list_my_programs` | Programs you joined, newest first, with your commission terms, lifetime clicks, leads and sales, and your earned and pending money in the window. | `from`, `to`, `limit`, `cursor` |
| `list_my_links` | Your referral links, newest first, with lifetime clicks, leads and sales. | `partner_program_id`, `status` (`active`, `inactive`), `limit`, `cursor` |
| `get_my_earnings` | Your earnings per program and in total for the window: earned, ready, arriving, paid and pending. | `from`, `to` |
| `list_my_commissions` | Your commissions across your programs, newest sale first. | `status`, `from`, `to`, `partner_program_id`, `limit`, `cursor` |
| `list_my_payouts` | Your payout requests, newest first: amount, status, method type and dates. Payout account details, such as bank or Wise details, are never included. | `limit`, `cursor` |

### How results look

- **Money** is an integer in an object keyed by unit, such as `{ "USD_cents": 4999 }` (`USD_cents`, `EUR_cents`, `VND_dong`), or in a `*_cents` field next to its currency (`get_billing`).
- **Dates** are UTC sale dates, `YYYY-MM-DD`. `from` and `to` default to the last 30 days and cover at most 366 days. Commission lists cover all dates unless you give `from` or `to`.
- **Pages** hold up to 50 items (`limit`, default 20). Pass `next_cursor` back as `cursor` for the next page.
- **Links:** where an item has a `url`, it opens that page in the Affitor dashboard. Referral links come as `short_link` and `affiliate_url`.
- **Commission statuses:** `pending`, `approved`, `invoiced`, `collected`, `paid`, `rejected`, `refunded`, `reversed`, `fraud`.
- Each result comes as structured content and as JSON text that starts with a line saying the text fields are untrusted data, not instructions.

---

## Example prompts

<AgentPrompt prompt="In the repository of example.com: use the Affitor tools. Call get_program and check that its id is 123; if it is not, stop and tell me. Add its install snippet as it says, then tell me what to deploy and how verification works.">
Brands: after you connect a coding agent (Claude Code, Cursor, Codex), give it this line to install the tracker. Replace example.com and 123 with your site and program id.
</AgentPrompt>

For a brand connection:

- "Who are my top partners by earned commission in the last 30 days?" (`list_partners`)
- "Summarize the pending partner applications." (`list_applications`)
- "How much commission is pending, approved and paid this month?" (`get_commission_summary`)
- "What do we owe Affitor right now, and is any invoice overdue?" (`get_billing`)

For a partner connection:

- "How much did I earn this month across my programs, and how much is ready?" (`get_my_earnings`)
- "Which of my links has the most sales?" (`list_my_links`)
- "Show my last five payouts and their status." (`list_my_payouts`)

The server cannot approve an application, change a commission, create a link or send a payout. Ask for any of these and the app finds no tool for it; do it in the dashboard.

---

## Limits and security

| Limit | Value |
|---|---|
| Requests to `/mcp` | 120 per minute per connection, then `429` with `{ "error": "rate_limited" }` |
| App registration | 300 per hour across all apps, then `429` with `{ "error": "rate_limited" }` |
| Token requests | 60 per minute per app, and 600 per minute across all apps |
| Access token | 1 hour, bound to `https://mcp.affitor.com/mcp` |
| Refresh token | Rotates on every use, expires after 30 days |
| Sign-in | Finish within 10 minutes of the page opening; each **Allow** is valid once, for 2 minutes |

Each server instance keeps its own request counts in memory, so the request limits apply per instance.

- **Read-only by design.** The only scope is `read`. There are no tools that write, delete or move money.
- **Access is checked on every call.** A brand connection reads a program only while you are an active member of it; a partner connection, only while your partner account exists. A blocked account stops working at once.
- **Only Affitor sign-in tokens work.** The server refuses program API keys, staff keys and dashboard sessions with `401`. Do not add an `Authorization` header with your API key.
- **Untrusted text is marked.** Partner names, application messages and other free text are cut at 280 characters (the cut fields are listed in `truncated`), and every result says its text is data, not instructions.
- **What is logged.** One row per tool call: the connection, the tool name, the program, the number of rows, whether it worked and how long it took. Never your prompts, the arguments or the results. These rows are deleted after 30 days.

### Remove access

- **Brands:** program menu › **Program settings**, then **Developers** › **AI agents**, lists the program's connections under **Connections** with **Client**, **Connected by**, **Added**, **Last used** and **Access**. Click **Disconnect** on your own connection: the app loses every program in it. A program owner can click **Remove** on a member's connection: the app loses this program, and its other programs stay.
- **Partners:** your name at the bottom of the left menu › **Integrations**, then **Disconnect**.

**Disconnect** is immediate: the app's tokens are deleted and its next request gets `401`. After **Remove**, the app can no longer read that program. Removing the last available program from a selection ends the connection; an **All current and future programs** connection keeps its access to programs added later.

---

## Troubleshooting

- **"This request has expired"** or **"This approval is no longer valid"**: the sign-in took too long. Start the connection again from your AI app.
- **The app sees the wrong programs:** disconnect it and connect again, choosing the right ones. The install prompt above checks the program id for this reason.
- **Signed in with the wrong account:** click **Switch** on the sign-in screen.
- **"Too many rows for this window"**: ask for a shorter `from`/`to` window.
- **`401` with "Program API keys are not accepted here"**: remove the `Authorization` header from your client's config and sign in instead.

---

## Legacy local server

`@affitor/mcp` on npm is a separate **stdio** server that runs on your computer and uses your **program API key** (`AFFITOR_API_KEY`) instead of sign-in. It does tracking, not reporting: `affitor_readiness`, `affitor_track_click`, `affitor_track_lead`, `affitor_get_integration_plan` and `affitor_run_verification`, plus `affitor_track_sale` and `affitor_track_refund` only when you set `AFFITOR_MCP_WRITE=1`. The [Affitor plugin](https://github.com/Affitor/claude-plugins) for Claude Code and Gemini CLI (0.1.1 and later) connects to the hosted OAuth server with read access; this legacy local server is separate.

For a coding project, use [Set up a coding agent](/docs/brand/cli/agent-setup) with CLI 0.4.5:

```bash
npx affitor@0.4.8 agent setup --client claude_code --dry-run --json
```

The generated launcher keeps the program key out of MCP JSON and pins `@affitor/mcp@0.2.2`. It leaves sale/refund tools disabled. This local setup does not create a hosted OAuth connection or read account reports. Its `doctor` check is static; restart your client and call `affitor_readiness` to check the live session. Ask before running synthetic verification or other writes.

Source and tool details: [Affitor CLI](https://github.com/Affitor/cli/tree/main/packages/mcp).

---

## Related

- [CLI Quickstart](/docs/brand/cli/quickstart): `npx affitor init` writes `.affitor/AGENTS.md`, the instruction file coding agents follow to install tracking.
- [Testing Integration](/docs/brand/tracking/testing-integration/): check that clicks, leads and sales arrive.
- [CLI Command Reference](/docs/brand/cli/commands/): `npx affitor onboard` and the rest of the CLI.
- [SDK Reference](/docs/api-reference/sdks/): the `@affitor/sdk` package.

<NextStep title="Install tracking with your agent" description="Connect a coding agent, then give it the install prompt above." href="/docs/brand/tracking/quickstart-integration" />
