mcp

# affset MCP server

An [MCP](https://modelcontextprotocol.io) server that lets a media buyer run affset
from a chat client — pull stats, manage campaigns/zones/team, payouts, targeting,
sub labels, and cut underperforming zones in plain language, no dashboard.

The tools wrap the existing affset tenant API. Connect through the hosted
endpoint (OAuth, no API key) or run this package locally (`Bearer` token +
`X-Namespace`). One connection serves one tenant.

**Fastest way to connect — the hosted endpoint.** Add
`https://mcp.affset.com/mcp` as a remote MCP server in Claude (web or desktop),
Cursor, Claude Code, or any client that supports streamable HTTP with OAuth:
paste the URL, sign in with your affset email, keep **Read-only** (the consent
default) or grant full access. Every connection shows up on the dashboard
Integrations page and can be revoked individually. Setup guide:
[affset.com/integrations](https://affset.com/integrations).

The npm package below is the self-host path: same tool roster, runs on your
machine with an API key you manage yourself. Stdio defaults to full access
unless you set `AFFSET_READ_ONLY=true`.

## Tools

| Tool                    | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `whoami`                | Show the tenant this server is bound to: namespace, API base, derived dashboard URL, and (when readable) company / timezone / custom API domain. Read-only.                                                                                                                                                                                                                                                                                                                                                                   |
| `get_stats`             | Traffic stats grouped by a dimension (date, campaign, zone, country, sub1–5, advertiser, publisher, …), optionally narrowed with `advertiser_email`/`publisher_email` filters (one user, any group_by). Returns clicks, conversions, CR, payout, media cost and ROI as a table. `paid_only` defaults to true (same as the dashboard) so CR excludes informative conversions. Sub columns use the tenant's sub labels when configured. Per-user groupings and filters are owner/manager plus the matching side's manager role. |
| `list_campaigns`        | List campaigns (status / name filter, pagination).                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `get_campaign`          | One campaign's full record — every field (untruncated offer URL, exact schedule, budgets/pacing, silent flag, payout goal type) plus its targeting rules and payout rules, in one call.                                                                                                                                                                                                                                                                                                                                       |
| `list_zones`            | List traffic-source zones (status / name filter, pagination, linked source).                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `list_team`             | List team members (email, role, manager). **Never returns API tokens.**                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `create_team_member`    | Invite a team member (owner, manager, publisher, advertiser, publisher_manager, advertiser_manager). A scoped manager key can only create its own managed role, self-assigned. Returns the new API key **once** — `list_team` never shows it again. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                         |
| `create_campaign`       | Create a campaign from an advertiser email, offer URL, geo, payout and name. Defaults: CPA / rate 0, **paused**, global payout rule, and a ready tracking link (linked source template when configured; otherwise `source_click_id={clickid}` + sub placeholders). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                          |
| `set_campaign_status`   | **Run** or **pause** a campaign (`action: "run" \| "pause"`). **Dry-run by default**; `confirm: true` to apply. Running can hit the plan's active-campaign limit.                                                                                                                                                                                                                                                                                                                                                             |
| `update_campaign`       | Partial update (name, offer URL, status, rate, budgets, dates, …). **Dry-run by default**; `confirm: true` to apply. Prefer `set_campaign_status` for run/pause.                                                                                                                                                                                                                                                                                                                                                              |
| `create_zone`           | Create a traffic-source zone (name + optional postback/site/traffic-back URLs, optional `traffic_source_id` link). Always created `active`. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                                                 |
| `update_zone`           | Partial update (name, status, URLs, `traffic_source_id`). **Dry-run by default**; `confirm: true` to apply. Pass `null` to clear a URL or unlink the source.                                                                                                                                                                                                                                                                                                                                                                  |
| `list_traffic_sources`  | List traffic sources — the networks bought from, each with the tracking/postback templates its linked zones use. API token shown only as set/none.                                                                                                                                                                                                                                                                                                                                                                            |
| `create_traffic_source` | Create a traffic source, optionally from a network preset (`exoclick`, `trafficstars`, `propellerads`, `adsterra`, `richads`) that copies verified templates into an editable row. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                          |
| `update_traffic_source` | Partial update (name, templates, api_token, status). Linked zones pick the new tracking template up immediately. **Dry-run by default**; `confirm: true` to apply.