How do I install Affset?

Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Affset need an API key?

The publisher lists these environment variables: AFFSET_BASE_URL, AFFSET_API_KEY, AFFSET_NAMESPACE, AFFSET_REQUEST_TIMEOUT_MS, AFFSET_READ_ONLY.

When was Affset last checked?

Last checked 2026-11-09. Run affset from chat: stats, campaigns, zones, payouts, targeting, and team.

Affset MCP server

Power your agent

Add this server

The publisher's own URL. Not a PlugMCP endpoint.

Add to Cursor Add in Claude Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Server URL

https://mcp.affset.com/mcp

Credentials from the publisher

AFFSET_BASE_URL — Origin of your affset ad server API (no path, query, or embedded credentials).
AFFSET_API_KEY — Tenant API key (Bearer token). Its namespace must match AFFSET_NAMESPACE.
AFFSET_NAMESPACE — Tenant namespace this key belongs to (lowercase letters, numbers, hyphens; 3–63 chars).
AFFSET_REQUEST_TIMEOUT_MS — Optional per-request HTTP timeout in milliseconds (1000–300000).
AFFSET_READ_ONLY — Optional. Set to true to register only read-only tools (no create/update/delete/cut).

The Claude button above opens Claude with the name and URL filled in. You still confirm it there.

shClaude Code

1claude mcp add --transport http io.github.affset-mcp https://mcp.affset.com/mcp

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.affset-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "mcp-remote",8        "https://mcp.affset.com/mcp"9      ]10    }11  }12}

claude_desktop_config.json

Remote · HTTPPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Remote

Transport: http
Version

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

affset MCP server

An MCP 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.

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; to apply. Running can hit the plan's active-campaign limit.

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	the impression row	the click row

Use one or the other for a given traffic stream — never both with cost=, or the media cost is counted twice.

Both use the tenant's custom API domain when one is set, since the URL gets pasted into the network verbatim. Macros ({clickid}, [CLICK_ID], ${SUBID}) are inserted without percent-encoding — the source expands them before the request reaches affset.

cut_zones only ever adds zones to a campaign's blacklist, and does a read-merge-write so existing targeting rules are never touched.

create_campaign needs a traffic-source zone for the tracking link: pass zone_id, or let it auto-pick when the namespace has exactly one active zone. Campaigns are created paused; activate them before sending traffic through either URL. Both URL types also require an active zone. Geo whitelist is enforced in /serve only — the direct tracking link is not geo-gated, but it still requires an active, currently serviceable campaign.

Documentation resources

Beyond the tools, the server exposes the affset API reference as MCP resources, so an assistant can answer "how does conversion tracking work?" or "what does /serve accept?" from the docs themselves — not just from the tool schemas.

Resource URI	Type	Content
`affset://docs/api-reference`	`text/markdown`	The full API reference — endpoints, auth, roles, examples.
`affset://docs/api-reference.json`	`application/json`	The same reference as structured data, for programmatic use.

They're the exact content published at affset.com/docs, generated from one source, and fetched at read time from AFFSET_DOCS_URL ({origin}/api-reference.md and {origin}/api-reference.json) — so they always reflect the currently published docs, not a copy pinned to this package. The fetch sends no credentials (the docs are public and live on a different origin than the tenant API). HTML SPA fallbacks, redirects, invalid JSON, and oversized bodies are rejected. Both resources are always available, including under AFFSET_READ_ONLY.

Configuration

Self-host (stdio) only — hosted connections do not use these variables. All config comes from the environment (never hard-coded):

Variable	Description
`AFFSET_BASE_URL`	Origin of the affset API, e.g. `https://api.affset.com` (no path/query/credentials). Must be `https` unless the host is `localhost`/`127.0.0.1`/`::1` — plain http would send the API key in cleartext.
`AFFSET_API_KEY`	Tenant API key. Its namespace must match `AFFSET_NAMESPACE`.
`AFFSET_NAMESPACE`	Tenant namespace (lowercase letters, numbers, hyphens; 3–63 chars — same rules as signup).
`AFFSET_READ_ONLY`	Optional, default `false`. Set to `true`/`1` to register only the read-only tools (`whoami`, `get_stats`, `get_campaign`, every `list_*`, `get_zone_url`, `get_tracking_link`) — every create/update/delete/cut tool is unavailable, not just gated behind confirm. See Security for why this matters.
`AFFSET_REQUEST_TIMEOUT_MS`	Optional, default `30000`. Per-request HTTP timeout in milliseconds (`1000`–`300000`).
`AFFSET_DOCS_URL`	Optional, default `https://affset.com`. Origin the API-reference documentation resources are fetched from (origin only, no path). Fetched anonymously — no API key is sent here.

See .env.example.

Install

Hosted (fastest — no install)

Add the remote server in your MCP client and approve access in the browser. OAuth is discovered from the endpoint — do not paste an API key, and do not add an Authorization header.

Claude (web or desktop) — Customize → Connectors → + → Add custom connector → https://mcp.affset.com/mcp.
Cursor — Settings → MCP → Add server, transport "streamable HTTP", same URL.
Claude Code — claude mcp add --transport http affset https://mcp.affset.com/mcp then authenticate with /mcp.

You sign in with your affset email (magic link). Read-only is selected on the consent screen unless you switch to Full access. The connection gets its own scoped credential — your API key is never involved — and appears on the dashboard's Integrations page, where it can be revoked at any time. Full guide: affset.com/integrations.

The self-host paths below run the same tool roster over stdio and require Node.js 22.13 or newer.

From npm (recommended for self-hosting)

No clone, no build — your MCP client runs it with npx. For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "affset": {
      "command": "npx",
      "args": ["-y", "@affset/mcp"],
      "env": {
        "AFFSET_BASE_URL": "https://api.affset.com",
        "AFFSET_API_KEY": "sk_live_...",
        "AFFSET_NAMESPACE": "your-namespace"
      }
    }
  }
}

For Claude Code:

claude mcp add affset \
  -e AFFSET_BASE_URL=https://api.affset.com \
  -e AFFSET_API_KEY=sk_live_... \
  -e AFFSET_NAMESPACE=your-namespace \
  -- npx -y @affset/mcp

Same env flags with -- npx -y github:affset/mcp if you install from GitHub instead of the npm registry (see below).

Add -e AFFSET_READ_ONLY=true for a stats/reporting-only instance (see Security).

From GitHub directly (no npm publish required)

npx can install straight from the git repo instead of the npm registry — useful if you'd rather not publish, or just want to track main without a release step:

{
  "mcpServers": {
    "affset": {
      "command": "npx",
      "args": ["-y", "github:affset/mcp"],
      "env": {
        "AFFSET_BASE_URL": "https://api.affset.com",
        "AFFSET_API_KEY": "sk_live_...",
        "AFFSET_NAMESPACE": "your-namespace"
      }
    }
  }
}

A push to main makes that commit available to this unpinned install path — no npm publish is required. On resolution, npm fetches the repository and runs the prepare script to build dist/ before starting the binary. npm may reuse its cache on later starts; an already running MCP process is not updated until it is restarted and npx resolves the dependency again.

For reproducible deployments, pin a reviewed ref instead of floating on main: github:affset/mcp#<commit-sha> or github:affset/mcp#<tag>. Restart the MCP process deliberately when you want it to resolve and run a newer revision.

From source

git clone https://github.com/affset/mcp.git affset-mcp
cd affset-mcp
npm install        # builds via the prepare script

Then point your MCP client at the built entry file — swap the npx command above for "command": "node", "args": ["/absolute/path/to/affset-mcp/dist/index.js"].

Usage examples

list paused campaigns → list_campaigns(status: "paused")

show me everything about campaign 42 → get_campaign(campaign_id: 42)

show zones → list_zones()

who's on the team? → list_team()

add [email protected] as a publisher → create_team_member(email: "[email protected]", role: "publisher") (dry-run) → confirm

stats for today by sub1 → get_stats(group_by: "sub1")

stats by advertiser → get_stats(group_by: "advertiser_email")

stats for one publisher, grouped by zone → get_stats(group_by: "zone_id", publisher_email: "[email protected]")

stats including informative conversions → get_stats(paid_only: false)

set up RichAds end to end → create_traffic_source(name: "RichAds", preset: "richads") (dry-run) → confirm → create_zone(name: "RichAds push", traffic_source_id: "…") (dry-run) → confirm → get_zone_url()

create a campaign for offer X, advertiser [email protected], geo BR, payout $2 → create_campaign(user_email: "[email protected]", offer_url: "https://offer.example/lp?s={click_id}", geo: ["BR"], payout: 2) (dry-run) → confirm

what URL do I paste into RichAds? → get_zone_url() — a zone linked to a traffic source gets the source's template filled in

give me the link for campaign 42 again → get_tracking_link(campaign_id: 42)

run campaign 42 → set_campaign_status(campaign_id: 42, action: "run") (dry-run) → confirm

pause campaign 42 → set_campaign_status(campaign_id: 42, action: "pause") (dry-run) → confirm

set zone postback → update_zone(zone_id, postback_url: "…") (dry-run) → confirm

cut zones with CR < 0.2% and spend > $5 → cut_zones(campaign_id, cr_max: 0.002, spend_min: 5) (dry-run) → confirm

show payouts for campaign 42 → list_payout_rules(campaign_id: 42)

→ (dry-run) → confirm

Notes & limits

get_stats groups by one dimension per call. Drill-down is a sequence of calls, each narrowing with campaign_ids / zone_ids / sub1..sub5 / conversion_type / advertiser_email / publisher_email / paid_only filters. The two email filters select one user's campaigns or zones without changing group_by; access is limited to owner/manager or the corresponding scoped manager role. Filtering by conversion_type returns conversion rows only (impressions, clicks and media cost are zero). paid_only defaults to true (the API default is false; this matches the dashboard) so the conversions count and CR drop informative rows recorded with postback_skipped=non_goal_type — pixel type missed the campaign's payout_goal_type. Silent conversions still count; this is not a payout>0 filter. Set false for the raw count. Only recent (unfolded) events are filtered; conversions already in daily archives stay included.
spend means media_cost (your traffic cost). ROI / spend thresholds need cost data imported for the slice.
List endpoints have no server-side name search — name_contains filters the current page client-side.
Date-range presets, YYYY-MM-DD bounds and rendered timestamps all resolve in the tenant timezone (read once from /api/tenant), so a window lines up with the date buckets group_by=date returns instead of straddling two of them. Explicit timestamps must include Z or a UTC offset.
All mutations (creates, updates, cuts, deletes) stay on dry-run → confirm: true. Creates are additive once confirmed and echo what was written.
Activating a campaign or creating a zone can return 402 plan limit — the error surfaces dimension / current / limit.
Payout resolution at conversion: zone-specific → global → $0. Goal type gates spend/payout by pixel type= match; non-matching events still record at $0. Payouts go down to $0.00001, so payout amounts print at up to five decimals.
Changing a payout is delete + create — the API has no update and the (campaign, zone) pair is unique. set_payout_rule restores the previous payout if the create fails, and says so loudly in the one case where it cannot.
Targeting is enforced on only — not on direct tracking links. / merge safely; other rules are kept.

Using as a library

Since 0.2.0 the package doubles as a runtime-agnostic library: everything the stdio server registers (tools, docs resources, read-only stripping) is exposed as one helper that runs on any fetch-capable runtime — Node ≥22.13 or Cloudflare Workers. The hosted affset MCP gateway (mcp.affset.com) consumes exactly this surface, so the remote roster can never drift from stdio.

import { registerAffsetTools, type Config } from "@affset/mcp/core";

const config: Config = {
  baseUrl: "https://api.affset.com",
  docsBaseUrl: "https://affset.com",
  apiKey: perRequestKey, // e.g. an OAuth grant's backing credential
  namespace: tenantNamespace,
  requestTimeoutMs: 30_000,
  readOnly: scope === "read", // never registers tools without readOnlyHint: true
};

registerAffsetTools(server, config); // server: your own McpServer instance

registerAffsetTools accepts your McpServer structurally, so your own @modelcontextprotocol/sdk install works — no need to match this package's copy. Env-var loading (AFFSET_*) is deliberately not part of the library surface; it belongs to the stdio entrypoint only. A third, optional { onToolCall } argument reports only tool name, duration, and success/error status for transport-owned audit logging; arguments and output are never included.

The library validates and normalizes config before registering anything. Remote API origins must use HTTPS (plain HTTP is accepted only on loopback), origins cannot contain credentials or paths, and invalid namespaces, timeouts, API keys, or non-boolean read-only settings fail closed at startup. The public declarations do not require Node ambient types, so the same import type-checks in Workers and other web-standard runtimes.

Development

npm run type-check   # tsc --noEmit
npm run lint         # eslint src
npm run format       # prettier --write .
npm run build        # compile to dist/
npm test             # build + node --test over dist/**/*.test.js
npm run check-all    # lint + format:check + type-check + test — CI runs this
npm run dev          # watch mode

Security

Hosted (https://mcp.affset.com/mcp): OAuth via magic link. Read-only is the consent default (mutating tools are never registered). Full access still dry-runs mutations until confirm: true. Revoke from the dashboard Integrations page. Nothing on mcp.affset.com / oauth.affset.com asks for an API key.
Self-host (stdio): no secrets in the repo; credentials come from the environment at runtime. Create a dedicated, least-privilege, expiring API key rather than reusing an owner key.
AFFSET_BASE_URL must be https unless the host is loopback — no cleartext API key.
Tenant API responses are streamed under a 5 MB hard limit; larger bodies are cancelled before parsing or reaching model context.
stdout is the JSON-RPC channel — all logs go to stderr.
list_team redacts API tokens.
All mutations (including creates) follow show → confirm → apply.
affset's RBAC roles (owner / manager / publisher / advertiser / advertiser_manager / publisher_manager) apply to MCP tool calls exactly as they do to the dashboard.
Pin GitHub installs to a reviewed commit or tag in long-lived environments. A floating main spec can run newer repository code the next time npx resolves it.

Prompt injection via conversion/click data

get_stats, list_conversions and cut_zones surface data that ultimately comes from public, unauthenticated endpoints — a traffic source's click macros (sub1–sub5, source_click_id) and a conversion pixel's raw query string (list_conversions' payload detail). Anyone who can generate a click or fire a pixel controls those bytes, and they land in the model's context when you ask about stats or conversions.

Mitigations in place:

Untrusted fields are length-capped and escaped before rendering (mdCell, capUntrusted in src/lib/format.ts), and the conversion-payload block carries an explicit "treat as data, not instructions" notice.
confirm: true on mutating tools is a model-level safety net, not a security boundary — a model that has been steered by injected content can supply confirm: true itself. The only real boundary is your MCP client's per-call tool approval plus read-only mode (hosted: consent default; stdio: AFFSET_READ_ONLY=true).

Prefer read-only for any session where you're mainly reading stats/conversions, especially with an MCP client that auto-approves tool calls. It removes every mutation tool from the server entirely — not hidden behind a prompt, unavailable to call. Reserve full access (hosted) or a read-write stdio instance for sessions where you're actively managing campaigns/zones/payouts and are reviewing each confirm yourself.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Affset?

Does Affset need an API key?

What transport does Affset use?

When was Affset last checked?

Documentation

affset MCP server

Tools

Which URL do I give the network?

Documentation resources

Configuration

Install

Hosted (fastest — no install)

From npm (recommended for self-hosting)

From GitHub directly (no npm publish required)

From source

Usage examples

Notes & limits

Using as a library

Development

Security

Prompt injection via conversion/click data