affset

AnMCPserver 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.

Both use the tenant'scustom API domainwhen 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_zonesonly everaddszones to a campaign's blacklist, and does a read-merge-write so existing targeting rules are never touched.

create_campaignneeds a traffic-sourcezonefor the tracking link: passzone_id, or let it auto-pick when the namespace has exactly one active zone. Campaigns are createdpaused; activate them before sending traffic through either URL. Both URL types also require an active zone. Geo whitelist is enforced in/serveonly — the direct tracking link isnotgeo-gated, but it still requires an active, currently serviceable campaign.

Beyond the tools, the server exposes the affsetAPI referenceas MCPresources, so an assistant can answer "how does conversion tracking work?" or "what does/serveaccept?" from the docs themselves — not just from the tool schemas.

They're the exact content published ataffset.com/docs, generated from one source, andfetched at read timefromAFFSET_DOCS_URL({origin}/api-reference.mdand{origin}/api-reference.json) — so they always reflect the currently published docs, not a copy pinned to this package. The fetch sendsno 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 underAFFSET_READ_ONLY.

{ "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" } } } }

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/mcpif you install from GitHub instead of the npm registry (see below).

Add-e AFFSET_READ_ONLY=truefor a stats/reporting-only instance (seeSecurity).

{ "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 tomainmakes that commit available to this unpinned install path — no npm publish is required. On resolution, npm fetches the repository and runs thepreparescript to builddist/before starting the binary. npm may reuse its cache on later starts; an already running MCP process is not updated until it is restarted andnpxresolves the dependency again.

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

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 thenpxcommand above for"command": "node","args": ["/absolute/path/to/affset-mcp/dist/index.js"].

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

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

addsarah@offer.comas a publisher→create_team_member(email: "sarah@offer.com", role: "publisher")(dry-run) → confirm

create a campaign for offer X, advertiserbuyer@example.com, geo BR, payout $2→create_campaign(user_email: "buyer@example.com", 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(cost: "{cost}")

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)

set zone payout to $3→set_payout_rule(campaign_id: 42, payout: 3, zone_id: "…")(dry-run) → confirm

only pay on deposit conversions→set_payout_goal(campaign_id: 42, goal_type: "deposit")(dry-run) → confirm

what targeting types exist?→list_targeting_types()

whitelist BR+MX on campaign 42→set_targeting_rule(campaign_id: 42, type: "geo", method: "whitelist", rule: "BR,MX")(dry-run) → confirm

name sub1 Zone, sub2 Creative→set_sub_labels(sub1: "Zone", sub2: "Creative")(dry-run) → confirm

show recent conversions→list_conversions()

hide informative conversions (goal-type misses)→list_conversions(paid_only: true)

find $0 payouts (no rule / still on this page)→list_conversions(zero_payout: true)

lookup by source click id→list_conversions(source_click_id: "abc123")

- get_statsgroups by one dimension per call.Drill-down is a sequence of calls, each narrowing withcampaign_ids/zone_ids/sub1..sub5/conversion_type/advertiser_email/publisher_email/paid_onlyfilters. The two email filters select one user's campaigns or zones without changinggroup_by; access is limited to owner/manager or the corresponding scoped manager role. Filtering byconversion_typereturns conversion rows only (impressions, clicks and media cost are zero).paid_onlydefaults totrue(the API default is false; this matches the dashboard) so the conversions count and CR drop informative rows recorded withpostback_skipped=non_goal_type— pixel type missed the campaign'spayout_goal_type. Silent conversions still count; this is not a payout>0 filter. Setfalsefor the raw count. Only recent (unfolded) events are filtered; conversions already in daily archives stay included.
- spendmeansmedia_cost(your traffic cost). ROI / spend thresholds need cost data imported for the slice.
- List endpoints haveno server-side name search—name_containsfilters the current page client-side.
- Date-range presets,YYYY-MM-DDbounds and rendered timestamps all resolve in thetenant timezone(read once from/api/tenant), so a window lines up with the date bucketsgroup_by=datereturns instead of straddling two of them. Explicit timestamps must includeZor 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 return402 plan limit— the error surfaces dimension / current / limit.
- Payout resolutionat conversion: zone-specific → global → $0. Goal type gates spend/payout by pixeltype=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_rulerestores the previous payout if the create fails, and says so loudly in the one case where it cannot.
- Targetingis enforced on/serveonly — not on direct tracking links.set_targeting_rule/remove_targeting_rulemerge safely; other rules are kept.
- Targeting values are matched exactly and case-sensitivelyat serve time (geo fromCF-IPCountry, os/browser from the user agent, device type from a fixed set).set_targeting_rulenormalises what it can (br,mx→BR,MX,android→Android) and rejects what could never match — an unmatched whitelist silently stops delivery.
- capping,weekdaysandhoursare seeded but never evaluatedby/serve.set_targeting_rulerefuses to write them (they would read as working targeting while the campaign kept buying);list_targeting_typesflags them. Useunique_users(visits/hours) for frequency capping.
- list_conversionsis the conversion audit trail (not aggregated stats). The API has no campaign/zone/date filters;paid_onlyis the one server-side filter (truedrops rows recorded withpostback_skipped=non_goal_type— pixel type missed the campaign'spayout_goal_type; silent conversions and other skip reasons still come back — this is not a payout>0 filter). The other optional filters apply to the current page only. Rows do not include campaign_id/zone_id. Publisher-side roles do not seespendand advertiser-side roles do not seepayout, sozero_payoutneeds a role that can;paid_onlydoes not (it keys onpostback_skipped, notpayout).
- create_team_membercreates the API key directly (like the dashboard's "Add Team Member") — it does not send an invite email. Hand the returned key to the person yourself. Revoking/removing a team member is not yet a tool; use the dashboard's Team page.
- Out of scope: deleting campaigns/zones/conversions, billing, creative management.
- Tenant signup is deliberately not a tool.POST /api/public/create-instanceis Origin-gated and fails closed, which is what keeps signup browser-only; a server-side caller would have to spoof an allowlisted Origin to get past it. The endpoint also withholds the API key when email delivery is configured (it sends a magic link instead), and this server binds one namespace from the environment at startup — so it could not use a tenant it just created. Sign up in the dashboard, then point a server instance at the new namespace.

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

registerAffsetToolsaccepts yourMcpServerstructurally, so your own@modelcontextprotocol/sdkinstall 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.

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

- 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 untilconfirm: true. Revoke from the dashboard Integrations page. Nothing onmcp.affset.com/oauth.affset.comasks for an API key.
- Self-host (stdio):no secrets in the repo; credentials come from the environment at runtime. Create adedicated, least-privilege, expiring API keyrather than reusing an owner key.
- AFFSET_BASE_URLmust behttpsunless 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_teamredacts API tokens.
- All mutations (including creates) followshow → 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 floatingmainspec can run newer repository code the next timenpxresolves it.

- Untrusted fields are length-capped and escaped before rendering (mdCell,capUntrustedinsrc/lib/format.ts), and the conversion-payload block carries an explicit "treat as data, not instructions" notice.
- confirm: trueon mutating tools is amodel-levelsafety net, not a security boundary — a model that has been steered by injected content can supplyconfirm: trueitself. The only real boundary is your MCP client's per-call tool approval plusread-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.

Free MCP that drives an audit of your marketing. Your AI connects, adsOS digs through your ads, email and site, and hands back a growth plan you can run today.

Launch & manage your User Referral and Partner / Affiliate program — for developers and growth teams.

Let AI clients add payments to your website. Create checkout pages, events and forms and embed them on your site in minutes.

Answers questions on AEO, SEO, web development and branding from the published material of GOJI, a Melbourne digital agency, with a goji.agency URL to cite on every result.

A shared campaign canvas for you and your AI agent: briefed by your brand rules, gated by your approval.

Technical SEO audits and crawl insights for AI assistants via MCP.

Run your Linkedin account from claude or chatgpt

AI agents that manage paid ads across Meta, LinkedIn, and Google Ads: campaigns, ad creative, and day-to-day ad operations from any MCP client.

Chat with any brand's Meta (Facebook/Instagram) ads inside Claude — research a competitor's ad library, surface their longest-running winners, extract hooks/formats, and clone winning ads for your own brand.