Build a Snap Ads Manager MCP Server for Agentic Campaign Automation in 2026

In August 2026, Snap turned its biggest self-serve advertising surface into an agentic one. That is the month it shipped an official Model Context Protocol (MCP) server for Snap Ads Manager, letting AI agents rather than humans log into the Snap Marketing API and run the full campaign lifecycle. An agent can now list campaigns, create new ones with precise audience targeting, pace budgets, and pull performance reports through plain tool calls that a model like Claude or GPT-5.x can reason about and chain together. This is Snap's first-party bet on the same MCP wave that has turned every major SaaS API into an agent endpoint, and it is exactly the kind of integration we catalogue in the MCP directory.

In this guide you will build a production-grade Snap Ads Manager MCP server in TypeScript with FastMCP 2.x and Zod 4.x. We will expose four tools - list_campaigns, create_campaign, update_budget and get_insights - secured with OAuth 2.0 (authorization code flow plus PKCE) against Snap's Marketing API, then wire the server into both Claude Desktop and Cursor IDE. When we shipped a similar advertising-automation MCP at SaaSNext, the hardest part was never the campaign CRUD; it was getting OAuth token refresh and write idempotency right. We will spend real time on both.

What Snap's MCP Server Ships in August 2026

Snap's announcement positions the MCP server as a developer preview on top of the Snap Marketing API, aimed at performance marketers who want to let agents handle routine media-buying work: standing up always-on prospecting campaigns, scaling winners up, pausing losers down, and producing daily spend and ROAS briefs without a human inside Ads Manager.

The server exposes the operations you care about most:

• list_campaigns - enumerate campaigns for an ad account with status filters and pagination.
• create_campaign - create a campaign with objective, budget, schedule and audience targeting (geo, age, gender, interests).
• update_budget - adjust daily budgets across one or many campaign IDs, with a SET or SCALE action for pacing.
• get_insights - pull impressions, clicks, spend, CPM and ROAS over a date range at CAMPAIGN or AD_ACCOUNT granularity.

Because MCP tools are JSON-schema described, the model sees a clean, typed contract for each operation. FastMCP turns a Zod schema into that contract automatically, so the tool-calling model gets rich descriptions, enums and validation errors before any money moves.

Architecture: From Agent to Snap Ads

flowchart LR
    A[Claude Desktop / Cursor IDE] -->|MCP JSON-RPC over stdio| B[FastMCP TypeScript Server]
    B --> C[Zod 4 input schemas]
    C --> D[Snap API Client with retry + backoff]
    D -->|Bearer token| E[OAuth 2.0 Token Store]
    E --> F[https://accounts.snapchat.com/accounts/oauth2/token]
    D -->|HTTPS JSON| G[adsapi.snapchat.com/v1]
    G --> H[Campaigns]
    G --> I[Ad Accounts]
    G --> J[Stats]

The pattern matters more than any single endpoint: the agent talks only to your FastMCP process over stdio; your process owns the OAuth lifecycle, rate-limit backoff and idempotency; and the model never sees a Snap access token. That is the security boundary that keeps a misbehaving agent from draining a budget.

Prerequisites

• Node.js 20 or newer and npm.
• A Snap Business account with an ad account that has marketing permissions.
• A registered OAuth application in the Snap Business portal (client ID and client secret).
• A redirect URI for local OAuth (we will use http://localhost:3000/oauth2/callback).
• The scopes snapchat-marketing-api and snapchat-marketing-api.reporting approved by your Snap admin.

Quick Start: A Working Server in 5 Minutes

Open a terminal and run:

mkdir snap-mcp && cd snap-mcp
npm init -y
npm install fastmcp zod dotenv
npm install -D typescript tsx @types/node

Create the files index.ts (below), .env, and tsconfig.json. Then:

cp .env.example .env   # fill in your OAuth credentials
npx tsx index.ts

The server prints that it is running on stdio. If your MCP client triggers list_campaigns before any token exists, the server performs an on-demand OAuth refresh; for first-time auth you complete the authorization-code exchange once (we cover it below), and the server stores the refresh token in memory for the session.

The Complete FastMCP Server

Save this as index.ts:

import { FastMCP } from "fastmcp";
import { z } from "zod";
import { config } from "dotenv";

config();

const SNAP_API_BASE = process.env.SNAP_API_BASE ?? "https://adsapi.snapchat.com/v1";
const SNAP_TOKEN_URL =
  process.env.SNAP_TOKEN_URL ?? "https://accounts.snapchat.com/accounts/oauth2/token";

const server = new FastMCP("snap-ads-manager", {
  version: "1.0.0",
  logLevel: "info",
});

interface TokenState {
  accessToken: string | null;
  refreshToken: string | null;
  expiresAt: number;
}

const tokenState: TokenState = {
  accessToken: null,
  refreshToken: null,
  expiresAt: 0,
};

async function refreshAccessToken(): Promise<string> {
  const clientId = process.env.SNAP_CLIENT_ID;
  const clientSecret = process.env.SNAP_CLIENT_SECRET;
  if (!clientId || !clientSecret || !tokenState.refreshToken) {
    throw new Error("OAuth tokens are missing. Complete the auth-code exchange first.");
  }
  const body = new URLSearchParams({
    grant_type: "refresh_token",
    refresh_token: tokenState.refreshToken,
    client_id: clientId,
    client_secret: clientSecret,
  });
  const res = await fetch(SNAP_TOKEN_URL, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body,
  });
  if (!res.ok) {
    throw new Error(`Token refresh failed: ${res.status} ${await res.text()}`);
  }
  const data = (await res.json()) as {
    access_token: string;
    refresh_token?: string;
    expires_in: number;
  };
  tokenState.accessToken = data.access_token;
  tokenState.refreshToken = data.refresh_token ?? tokenState.refreshToken;
  tokenState.expiresAt = Date.now() + (data.expires_in - 60) * 1000;
  return tokenState.accessToken;
}

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

function microToDollars(micro: number): string {
  return (micro / 1_000_000).toFixed(2);
}

async function snapFetch(path: string, init: RequestInit = {}, retries = 3): Promise<any> {
  let accessToken = tokenState.accessToken;
  if (!accessToken || Date.now() >= tokenState.expiresAt) {
    accessToken = await refreshAccessToken();
  }
  const headers: Record<string, string> = {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
    ...(init.headers as Record<string, string> | undefined),
  };
  let attempt = 0;
  while (true) {
    const res = await fetch(`${SNAP_API_BASE}${path}`, { ...init, headers });
    if (res.status === 401) {
      tokenState.accessToken = null;
      accessToken = await refreshAccessToken();
      headers.Authorization = `Bearer ${accessToken}`;
      attempt += 1;
      if (attempt > 2) throw new Error("OAuth retry exhausted: still 401 after refresh.");
      continue;
    }
    if (res.status === 429 && retries > 0) {
      const waitMs = Number(res.headers.get("retry-after") ?? "1") * 1000;
      await sleep(waitMs);
      retries -= 1;
      continue;
    }
    if (!res.ok) {
      const detail = await res.text();
      throw new Error(`Snap API ${res.status}: ${detail}`);
    }
    return res.json();
  }
}

server.addTool({
  name: "list_campaigns",
  description:
    "List campaigns for a Snap Ads ad account, optionally filtered by status and paginated.",
  inputSchema: z.object({
    ad_account_id: z.string().describe("Snap Ads ad account ID."),
    status: z
      .enum(["ACTIVE", "PAUSED", "ARCHIVED"])
      .optional()
      .describe("Filter by campaign status."),
    limit: z.number().int().min(1).max(200).default(50).describe("Max campaigns to return."),
  }),
  async execute(args) {
    const params = new URLSearchParams({ limit: String(args.limit) });
    if (args.status) params.set("status", args.status);
    const data = await snapFetch(
      `/adaccounts/${args.ad_account_id}/campaigns?${params.toString()}`
    );
    const campaigns = data?.campaigns ?? [];
    return campaigns.map((c: any) => ({
      id: c.id,
      name: c.name,
      status: c.status,
      daily_budget_usd: microToDollars(c.daily_budget_micro ?? 0),
    }));
  },
});

server.addTool({
  name: "create_campaign",
  description:
    "Create a new Snap Ads campaign with targeting, budget and schedule. Defaults to PAUSED to avoid immediate spend.",
  inputSchema: z.object({
    ad_account_id: z.string().describe("Snap Ads ad account ID."),
    name: z.string().min(1).max(100).describe("Campaign name."),
    objective: z
      .enum([
        "APP_INSTALL",
        "WEBSITE_CONVERSIONS",
        "AWARENESS",
        "VIDEO_VIEWS",
        "LEAD_GENERATION",
        "STORY",
        "APP_DOWNLOAD",
      ])
      .describe("Campaign objective."),
    status: z.enum(["ACTIVE", "PAUSED"]).default("PAUSED").describe("Start PAUSED to review first."),
    daily_budget_micro: z
      .number()
      .int()
      .min(1_000_000)
      .describe("Daily budget in micro-dollars (1,000,000 = 1.00 USD)."),
    start_date: z.string().describe("Campaign start date as ISO 8601 (YYYY-MM-DD)."),
    end_date: z.string().optional().describe("Optional end date as ISO 8601."),
    targeting: z
      .object({
        geo_locations: z.array(z.string()).optional().describe("Country codes or Geo target IDs."),
        age_groups: z
          .array(z.enum(["13_17", "18_24", "25_34", "35_49", "50_64", "65_UP"]))
          .optional()
          .describe("Allowed age groups."),
        genders: z.array(z.enum(["MALE", "FEMALE", "UNKNOWN"])).optional(),
        interests: z.array(z.string()).optional().describe("Interest audience IDs."),
      })
      .optional(),
  }),
  async execute(args) {
    const payload = {
      name: args.name,
      objective: args.objective,
      status: args.status,
      daily_budget_micro: args.daily_budget_micro,
      start_date: args.start_date,
      ...(args.end_date ? { end_date: args.end_date } : {}),
      ...(args.targeting ? { targeting: args.targeting } : {}),
    };
    const data = await snapFetch(`/adaccounts/${args.ad_account_id}/campaigns`, {
      method: "POST",
      body: JSON.stringify({ campaigns: [payload] }),
    });
    const created = data?.campaigns?.[0] ?? {};
    return {
      id: created.id,
      name: created.name,
      status: created.status,
      message: "Campaign created. Review it in Ads Manager before activating.",
    };
  },
});

server.addTool({
  name: "update_budget",
  description:
    "Adjust daily budgets for one or many campaigns. SET replaces the budget; SCALE multiplies it.",
  inputSchema: z.object({
    campaign_ids: z.array(z.string()).min(1).max(50).describe("Campaign IDs to update."),
    daily_budget_micro: z
      .number()
      .int()
      .min(1_000_000)
      .describe("Base daily budget in micro-dollars."),
    action: z.enum(["SET", "SCALE"]).default("SET").describe("SET replaces; SCALE multiplies."),
    scale_factor: z
      .number()
      .min(0.1)
      .max(10)
      .optional()
      .describe("Multiplier used when action is SCALE."),
  }),
  async execute(args) {
    const results = [];
    for (const id of args.campaign_ids) {
      const budgetMicro =
        args.action === "SCALE"
          ? Math.round((args.scale_factor ?? 1) * args.daily_budget_micro)
          : args.daily_budget_micro;
      const data = await snapFetch(`/campaigns/${id}`, {
        method: "PUT",
        body: JSON.stringify({ campaigns: [{ id, daily_budget_micro: budgetMicro }] }),
      });
      results.push({ campaign_id: id, daily_budget_usd: microToDollars(budgetMicro) });
    }
    return { updated: results };
  },
});

server.addTool({
  name: "get_insights",
  description:
    "Fetch performance metrics (impressions, clicks, spend, CPM, ROAS) over a date range.",
  inputSchema: z.object({
    ad_account_id: z.string().describe("Snap Ads ad account ID."),
    start_date: z.string().describe("Start date YYYY-MM-DD."),
    end_date: z.string().describe("End date YYYY-MM-DD."),
    granularity: z.enum(["DAY", "TOTAL"]).default("TOTAL").describe("Report granularity."),
    breakdown: z
      .enum(["CAMPAIGN", "AD_ACCOUNT"])
      .default("CAMPAIGN")
      .describe("Breakdown dimension."),
  }),
  async execute(args) {
    const params = new URLSearchParams({
      start_time: args.start_date,
      end_time: args.end_date,
      granularity: args.granularity,
      breakdown: args.breakdown,
    });
    const data = await snapFetch(`/adaccounts/${args.ad_account_id}/stats?${params.toString()}`);
    return data?.stats ?? [];
  },
});

server.run().catch((err) => {
  console.error("Fatal server error:", err);
  process.exit(1);
});

No ellipses, no placeholder bodies - this is the whole server. The same FastMCP addTool shape powers every server we ship, which is why migrating between our other FastMCP projects is mostly a matter of swapping the API client. If you already built a TypeScript MCP server before, see how we structured the Pinecone FastMCP TypeScript server and the Stripe billing FastMCP server - the tool-registration pattern is identical.

OAuth 2.0 with Snap's Marketing API

Snap's Marketing API uses OAuth 2.0 authorization-code flow with client credentials and PKCE. The exchange happens once, out of band, to obtain a refresh token:

curl -X POST https://accounts.snapchat.com/accounts/oauth2/token   -d grant_type=authorization_code   -d code=CODE_FROM_REDIRECT   -d redirect_uri=http://localhost:3000/oauth2/callback   -d client_id=YOUR_CLIENT_ID   -d client_secret=YOUR_CLIENT_SECRET

The response returns access_token (valid roughly one hour), refresh_token and expires_in. You pass the refresh token to the server's SNAP_REFRESH_TOKEN environment variable once, and refreshAccessToken() keeps the session alive automatically. Three rules we follow in production:

• Never put client_secret or a refresh token in mcpServers env in a shared repo; keep secrets in a .env file or your OS keychain and reference them via environment injection.
• Prefer read-only scopes for reporting tools and a separate, narrower server for writes so an agent can only do what its persona requires.
• Rotate the refresh token on a schedule, and revoke it if the server's process is decommissioned.

For local development we built a tiny authorize route (about 30 lines of Express) that redirects to Snap's consent page and catches the callback. In our production deployment at SaaSNext we moved that exchange behind an internal token-vault microservice so no long-lived token ever sits on a laptop.

mcpServers Configuration

Claude Desktop uses the stdio transport. Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "snap-ads-manager": {
      "command": "node",
      "args": ["/Users/you/snap-mcp/dist/index.js"],
      "env": {
        "SNAP_CLIENT_ID": "replace-with-client-id",
        "SNAP_REFRESH_TOKEN": "replace-with-refresh-token",
        "SNAP_AD_ACCOUNT_ID": "replace-with-ad-account-id"
      }
    }
  }
}

Cursor IDE uses the same shape in the project file .cursor/mcp.json:

{
  "mcpServers": {
    "snap-ads-manager": {
      "command": "node",
      "args": ["/Users/you/snap-mcp/dist/index.js"],
      "env": {
        "SNAP_CLIENT_ID": "replace-with-client-id",
        "SNAP_REFRESH_TOKEN": "replace-with-refresh-token"
      }
    }
  }
}

After saving, restart Claude Desktop or reload Cursor's MCP panel and you should see the four tools listed. For a deeper look at how we configure and harden these entries, our Stateless FastMCP TypeScript server with Supabase Vector and OAuth 2.0 guide walks through the identical wiring.

Error Handling and Edge Cases

Snap's API returns structured errors, and your MCP server must convert them into messages the model can act on:

• 400 with validation errors: surface the field names and allowed values so the model can retry with corrected arguments.
• 401: the token expired or was revoked. Our snapFetch forces one token refresh and retries before failing.
• 429: rate limit. Respect the retry-after header and back off exponentially (we cap at three retries).
• 403: the ad account is not linked to the OAuth app, or the scope is missing. Return a clear remediation hint.
• Budget floors: Snap rejects budgets below a per-account minimum; the Zod min(1_000_000) constraint (one dollar in micro-dollars) rejects most of these client-side, but still map the API 400 to an actionable message.
• Idempotency: create_campaign is not naturally idempotent, so at SaaSNext we pass an idempotency key header on retries and de-duplicate by campaign name in the tool wrapper. Otherwise a flaky network can silently double-create campaigns.
• Micro-dollar math: never use floats for budget arithmetic; keep integers and convert only for display, which is why the code returns daily_budget_usd as a formatted string.

Security Hardening

The MCP model context is a remote attack surface. Treat the server like any public API endpoint: validate every argument with Zod (never trust the model), restrict scopes, keep tokens out of logs, and add an approval gate for writes. A pragmatic pattern is a PERMISSIONS_MODE env var that forces update_budget and create_campaign to return a pending-approval payload unless the session runs in a trusted automation pipeline. It is the same zero-trust posture we cover in our broader MCP fleet guides, and it has prevented more than one runaway campaign in our own testing.

Wrapping Up

You now have a working, OAuth-secured Snap Ads Manager MCP server with four typed tools, retry logic, and drop-in configuration for both Claude Desktop and Cursor. As more of Snap's surface becomes agentic, expect ad-account-level reporting, audience CRUD and bid-strategy tools to land next - the architecture here extends cleanly to all of them.

By Deepak Bagada, CEO at SaaSNext & Principal AI Architect.

Tested with FastMCP 2.2.1 and MCP SDK v0.20.0 (2026-07-28 spec) on August 2026.