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.

It's a thin wrapper over the existing affset tenant API (`Bearer` token +
`X-Namespace`). One server instance serves one tenant.

## 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, …). Returns clicks, conversions, CR, payout, media cost and ROI as a table. Sub columns use the tenant's sub labels when configured.                                                                                     |
| `list_campaigns`        | List campaigns (status / name filter, pagination).                                                                                                                                                                                                                                                    |
| `list_zones`            | List traffic-source zones (status / name filter, pagination).                                                                                                                                                                                                                                         |
| `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, ready tracking link with `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). Always created `active`. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                            |
| `update_zone`           | Partial update (name, status, URLs). **Dry-run by default**; `confirm: true` to apply. Pass `null` to clear a URL.                                                                                                                                                                                    |
| `get_zone_url`          | The `/serve` URL to paste into a network's campaign settings — rotates across the zone's **active** campaigns. Prefilled sub convention, optional `cost` macro. Warns when no active campaigns are visible.                                                                                           |
| `get_tracking_link`     | The `/track/click` link for an existing campaign + zone — straight to one active campaign, with no rotation or targeting checks. Re-derives what `create_campaign` echoed on create.                                                                                                                  |
| `cut_zones`             | Blacklist underperforming zones on a campaign by threshold (CR / spend / ROI). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                      |
| `list_payout_rules`     | List a campaign's global + per-zone payout rules and its `payout_goal_type`.                                                                                                                                                                                                                          |
| `set_payout_rule`       | Upsert a global or zone-specific payout. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                            |
| `delete_payout_rule`    | Delete a global or zone-specific payout rule. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                       |
| `set_payout_goal`       | Set or clear `payout_goal_type` (goal-based conversions). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                           |
| `list_targeting_types`  | Catalog of targeting rule types, flagging the seeded ones `/serve` never evaluates.                                                                                                                                                                                                                   |
| `list_targeting_rules`  | List a campaign's targeting rules, flagging any that have no effect.                                                                                                                                                                                                                                  |
| `set_targeting_rule`    | Upsert one targeting rule (safe merge), normalised to what `/serve` matches. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                        |
| `remove_targeting_rule` | Remove one targeting rule by id or type+method. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                     |
| `list_sub_labels`       | List tenant display names for sub1–sub5.                                                                                                                                                                                                                                                              |
| `set_sub_labels`        | Set or clear sub labels (partial; `null` clears). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                   |
| `list_conversions`      | List conversion audit records (payout, spend, pixel type, payload, postback). Optional client-side filters on the current page.                                                                                                                                                                       |

### Which URL do I give the network?

|                          | `get_zone_url` (`/serve/{zone}`)          | `get_tracking_link` (`/track/click/{campaign}/{zone}`) |
| ------------------------ | ----------------------------------------- | ------------------------------------------------------ |
| Picks the campaign       | affset, from the zone's rotation          | you, one fixed campaign                                |
| Needs an active campaign | **yes** — otherwise traffic back / unsold | **yes** — otherwise 404                                |
| Needs an active zone     | **yes**                                   | **yes**                                                |
| Geo & targeting rules    | enforced                                  | **not** enforced                                       |
| `cost=` lands on         | t