Synter-Media-AISynter-Media-AI/mcp-server/skills/synter-ads/SKILL.md

synter-ads

Skill21 starsChanged 25 days agoMITView on GitHub

Technical reference for @synterai/mcp-server (v1.4.7), covering hosted OAuth, local stdio, 30+ advertising platforms read/write capability matrix, pricing and rate limits, workspace-isolated multi-tenancy, and write safety.

Reads credentials
Installs packages

In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- budget-optimizerSkill
- campaign-managerSkill
- competitor-researchSkill
- creative-generatorSkill
- performance-analyzerSkill

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Runtime Cost Inspection ($0.00): Call get_solo_price_card or get_credit_balance at any time for $0.00 to verify current tool rates and …
line 39
Very specific:
Prefer dedicated first-class read tools when available, and use documented execute / run_action scripts when no dedicated read tool exists:
line 59

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

`@synterai/mcp-server` (v1.4.7) — Technical Reference

Package: @synterai/mcp-server@1.4.7 (MIT license, source)
Hosted MCP Endpoint: https://mcp.synterai.com (Streamable HTTP + OAuth 2.1 with PKCE, or X-Synter-Key header for headless/CI clients)
Local Stdio Launch: npx -y @synterai/mcp-server@1.4.7 (pass --read-only to strip mutating tools from tools/list at startup, or --demo for offline schema/mock testing)
REST API, CLI & SDKs: https://synterai.com/api/v1, pip install synter, @synterai/sdk-js, crates.io/crates/synter, Maven ai.syntermedia:synter-sdk

1. Platform Coverage & Per-Platform Read/Write Capability Matrix (30+ Advertising Platforms)

Synter connects across 30+ advertising platforms on the hosted MCP endpoint (https://mcp.synterai.com, plus GA4, Google Tag Manager, PostHog, Mixpanel, Shopify, Klaviyo, HubSpot, Salesforce, and Attio), while the local stdio package (@synterai/mcp-server) exposes the 16 core platforms in its local platform enum (google, meta, linkedin, microsoft, reddit, tiktok, x, pinterest, snapchat, stackadapt, amazon_dsp, spotify, amazon_ads, openai, the_trade_desk, dv360):

Platform Group	Platforms	Read Capabilities (`$0.00` Own-Account Reads)	Write & Execution Capabilities (`SOLO` / `SCALE` / `CUSTOM`)
Search & Intent	Google Ads, Microsoft Ads, Search Ads 360 (`SA360`), Apple Search Ads	`pull_google_ads_performance`, `pull_microsoft_ads_performance`, `run_gaql_query` (arbitrary read-only GAQL `SELECT`), `list_campaigns`, `get_campaign_observation`, `get_ad_readback`, `audit_account_structure`, `audit_campaign_waste`, `execute(action="sa360_get_campaigns")`	`pause_campaign`, `enable_campaign`, `update_campaign_budget`, `add_keywords`, `add_negative_keywords` (`BROAD`, `PHRASE`, `EXACT`), `create_conversion`, `google_ads_manage_custom_goals`, `execute(action="google_ads_")` / `execute(action="microsoft_ads_")` / `execute(action="apple_ads_")` (SA360 is read-only verification)*
Paid Social & Video	Meta Ads, LinkedIn Ads, TikTok Ads, Reddit Ads, X Ads, Pinterest Ads, Snapchat Ads, YouTube Ads, Nextdoor Ads, Quora Ads	`pull_meta_ads_performance`, `pull_linkedin_ads_performance`, `pull_tiktok_ads_performance`, `pull_reddit_ads_performance`, `pull_x_ads_performance`, `pull_pinterest_ads_performance`, `pull_snap_ads_performance`, `tiktok_ads_get_insights`, `get_ad_readback`	`meta_ads_create_ad`, `linkedin_ads_create_campaign`, `reddit_ads_create_campaign`, `reddit_ads_create_ad_group`, `reddit_ads_create_ad`, `tiktok_ads_update_adgroup`, `pause_campaign`, `enable_campaign`, `update_campaign_budget`, `sync_audience`, `execute(action="<platform>_*")`
Programmatic, ABM, CTV & Audio DSPs	StackAdapt, The Trade Desk, DV360, CM360, Amazon DSP, Demandbase ABM, Yahoo DSP, Criteo, FreeWheel, Teads, Basis, Taboola, Outbrain, Spotify Ads, AppLovin	`pull_trade_desk_performance`, `pull_dv360_performance`, `pull_cm360_performance`, `pull_amazon_dsp_performance`, `pull_freewheel_performance`, `pull_criteo_ads_performance`, `pull_spotify_ads_performance`, `execute(action="demandbase_")`, `execute(action="taboola_")`, `execute(action="applovin_*")`, `list_campaigns`	`pause_campaign`, `enable_campaign`, `update_campaign_budget`, `sync_audience`, `upload_creative`, `execute(action="stackadapt_")` / `execute(action="trade_desk_")` / `execute(action="dv360_")` / `execute(action="amazon_dsp_")` / `execute(action="spotify_ads_*")`
Retail Media, Affiliate & AI Channels	Amazon Ads, Walmart Connect, Instacart Ads, Target Roundel, impact.com, OpenAI Ads	`pull_amazon_ads_performance`, `pull_walmart_ads_performance`, `pull_instacart_ads_performance`, `pull_target_roundel_performance`, `pull_openai_ads_performance`, `execute(action="impact_*")`, `get_llm_visibility_overview`, `get_coding_agent_visibility`	`pause_campaign`, `enable_campaign`, `update_campaign_budget`, `execute(action="amazon_ads_")` / `execute(action="walmart_ads_")` / `execute(action="instacart_ads_")` / `execute(action="target_roundel_")` / `execute(action="openai_ads_*")`

Cross-Platform Ad-Ops & Analytics Tools: Cross-channel budget allocation (optimize_budget), first-party audience staging and SHA-256 Customer Match sync (stage_audience_artifact, sync_audience), pixel & CAPI health diagnostics (get_pixel_health, get_click_attribution), GA4 & GTM management (ga4_get_report, ga4_get_conversions, update_gtm_tag), and post-mutation ground-truth verification (get_ad_readback, get_campaign_observation, angstrom_verify_output).

2. Pricing, Subscription Tiers, Metering & Rate Limits (`synterai.com/pricing`)

Synter charges 0% of ad spend (ad platforms bill media directly) and $0.00 for all own-account reads:

Plan	Price	Included Monthly Usage & Scope
Free Read Access	$0.00 / month	$0.00 for all own-account read, reporting, budget pacing, conversion audit, GAQL (`run_gaql_query`), LLM/coding-agent visibility read (`get_llm_visibility_overview`, `get_coding_agent_visibility`), and `dry_run: true` preview calls across all 30+ advertising platforms. No credit card required.
SOLO	$20.00 / month (`$200.00 / year`)	Includes $20.00/mo in claimable monthly usage value. Unlocks live MCP, CLI, SDK, and REST API write mutations across all supported platforms.
SCALE	$500.00 / month (`$5,000.00 / year`)	Includes $500.00/mo in claimable monthly usage value, multi-workspace management, 24/7 autonomous monitoring schedules (`create_autonomous_schedule`), and CRM/warehouse sync.
CUSTOM	Sales-Led Enterprise Contract	Custom claimable monthly usage allowance, multi-client agency workspaces, invoiced billing, and SSO.

Exact Per-Call Metering (USD):
- Own-Account Reads & Discovery ($0.00): list_campaigns, pull_*_performance, get_performance, get_daily_spend, run_gaql_query, pacing_report, get_connection_status, get_workspaces, get_credit_balance, get_usage_breakdown, get_solo_price_card, get_llm_visibility_overview, get_coding_agent_visibility, and dry_run: true previews cost $0.00.
- Runtime Cost Inspection ($0.00): Call get_solo_price_card or get_credit_balance at any time for $0.00 to verify current tool rates and remaining workspace balance in USD before running metered calls.
- Write Mutations ($0.05–$0.25): Light writes (pause_campaign, enable_campaign, update_campaign_budget) cost $0.05 ($0.25 standard Solo write rate); full campaign launches cost $5.00 via MCP/SDK/CLI/API (or $25.00 inside the managed Synter Angstrom web app). Failed or dry_run: true calls are never billed.
- Third-Party Vendor Intelligence Reads ($0.05–$0.50): Third-party vendor lookups (competitor_ad_intel, keyword_research, enrich_contacts, live LLM scans run_llm_visibility_scan) carry external data costs and require a paid plan (SOLO, SCALE, or CUSTOM).
Rate Limits: Automated bursts are capped at 60 requests per minute per user by default (returns HTTP 429 with retry_after_seconds), and child API keys can set custom per-key ceilings (rate_limit_rpm: 1–600) via POST /api/v1/keys.

3. Authentication, Scoped Keys & Multi-Tenant Architecture (`docs.synterai.com/api/multi-tenant-auth`)

Hosted OAuth 2.1 (https://mcp.synterai.com): Uses OAuth 2.1 with dynamic client registration and PKCE for interactive coding agents (claude mcp add --transport http --scope user synter-ads https://mcp.synterai.com or codex mcp add synter-ads --url https://mcp.synterai.com). Unauthenticated HTTP requests to https://mcp.synterai.com return 401 with WWW-Authenticate metadata to initiate the MCP client's OAuth handshake.
Server-Side Scoped API Keys & Read-Only Enforcement: Headless/CI services authenticate via X-Synter-Key or Authorization: Bearer syn_... (SYNTER_API_KEY in stdio). Server-enforced API keys minted via POST https://synterai.com/api/v1/keys support granular scopes (reporting:read, campaigns:read, intel:read), directional budget:decrease (allows emergency pauses and budget reductions while rejecting budget increases with 403), or write scopes (campaigns:write, budget:write). Passing --read-only or SYNTER_READ_ONLY=true to @synterai/mcp-server also strips mutating tools from tools/list locally.
Multi-Tenant & Embedded SaaS Integration (Two Supported Patterns):
1. Hosted Workspace-Isolated Keys & Connect Links: On the hosted platform, tenant data is isolated by workspace. Create a workspace per client in the web UI, mint workspace-pinned, least-privilege child keys via POST https://synterai.com/api/v1/keys (scopes, rate_limit_rpm, expires_in_days), and generate single-use advertiser OAuth handoff links via POST https://synterai.com/api/v1/connections/start (returns a single-platform authUrl) or POST https://synterai.com/api/v1/connections/request (emails a 7-day multi-platform connection link to the client). Switch workspaces on multi-workspace keys via get_workspaces and update_active_workspace. (Note: programmatic workspace creation via POST /api/v1/workspaces and white-label multi-customer OAuth under a single shared key are not supported on the hosted service.)
2. Self-Hosted / Embedded BYO-Credential Execution (MIT Open-Source): SaaS products that manage per-tenant OAuth apps and store customer tokens in their own vault can run @synterai/mcp-server or synter CLI (MIT license) as a local worker/subprocess and pass each tenant's decrypted platform credentials per invocation via environment variables (GOOGLE_ADS_REFRESH_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_DEVELOPER_TOKEN, META_ACCESS_TOKEN, LINKEDIN_ACCESS_TOKEN, etc.) without routing credentials through Synter's hosted cloud.

4. Write Safeguards, Dry-Run Previews & Post-Write Readback

Schema & Policy Previews (dry_run: true): Campaign creation, pause_campaign, update_campaign_budget, and add_negative_keywords accept dry_run: true ($0.00) to validate arguments and inspect the planned payload without mutating live accounts.
Sandbox vs. Live Verification: When @synterai/mcp-server runs without SYNTER_API_KEY (or with --demo), read tools and dry_run: true calls return deterministic synthetic responses (sandbox: true, simulated: true) for offline schema/integration testing. Before executing a live mutation, verify active platform connections via get_connection_status / list_ad_accounts, confirm workspace scope via get_workspaces, and verify every live mutation afterward via get_ad_readback, get_campaign_observation, or list_campaigns.

5. Coding Agent Tool Routing, REST Contract & Parameter Reference

Prefer dedicated first-class read tools when available, and use documented execute / run_action scripts when no dedicated read tool exists:

Task	Canonical Tool / Endpoint	Exact Parameters & Response Contract
Canonical REST Tool Execution	`POST https://synterai.com/api/v1/tools/run`	Headers: `Authorization: Bearer <SYNTER_API_KEY>` (or `X-Synter-Key: <SYNTER_API_KEY>`), `Content-Type: application/json`. Body: `{"script_name": "<tool_or_script>", "args": ["--flag", "value"], "platform": "GOOGLE"}`.
HTTP Error & Rate-Limit Contract	`401` / `402` / `429`	`401`: invalid/missing `SYNTER_API_KEY`. `402`: billing/credit wall (`error: "INSUFFICIENT_CREDITS"` or `"ACCOUNT_READ_ONLY"`, `upgradeUrl: "https://synterai.com/settings/billing?..."`). `429`: rate-limited (`Retry-After` header in seconds + `retry_after_seconds` in JSON body).
Google Ads Custom GAQL Queries	`run_gaql_query` (`$0.00`)	`{ query: "SELECT ...", customer_id?: "1234567890" }` (returns `{ success: true, rows: [...] }`; do not route GAQL `SELECT` queries through `execute`).
Google Ads Search Terms & Keyword Hygiene	`pull_google_ads_performance` / `add_negative_keywords` / `execute`	Read search terms via `run_gaql_query` (`FROM search_term_view`) or `execute(action="pull_google_ads", args=["--level", "search-terms", "--days", "14"])`. Add negatives via `add_negative_keywords({ campaign_id, keywords: [...], match_type: "EXACT" \| "PHRASE" \| "BROAD", dry_run?: true })`. Pause/enable keywords via `execute(action="google_ads_update_keywords", args=["--campaign-id", "<id>", "--ad-group-id", "<id>", "--criterion-id", "<id>", "--status", "PAUSED", "--dry-run"])`.
StackAdapt & LinkedIn ABM Launch + Pixel Gate	`get_pixel_health` / `linkedin_ads_create_campaign` / `execute`	Verify pixel attachment first via `get_pixel_health({ domain: "example.com" })` (returns `{ success: true, healthy: true, pixels: [{ platform, pixel_id, status, attached }] }`). Create PAUSED LinkedIn campaigns via `linkedin_ads_create_campaign({ account_id, name, daily_budget, status: "PAUSED", dry_run: true })` (or `execute(action="linkedin_ads_create_campaign_complete", args=["--account-id", "<id>", "--group-id", "<group_id>", "--name", "<name>", "--daily-budget", "100", "--status", "PAUSED", "--dry-run"])`). Stage PAUSED StackAdapt campaigns via `execute(action="create_stackadapt_campaign", args=["--advertiser-id", "<id>", "--name", "<name>", "--budget", "1000", "--status", "PAUSED", "--dry-run"])`.
Post-Write Ground-Truth Readback	`get_ad_readback`, `get_campaign_observation` (`$0.00`)	`{ platform: "google" \| "meta" \| "linkedin" \| ..., campaign_id: "...", customer_id?: "..." }` (use `customer_id`, not `account_id`, on Google Ads readback tools).
Runtime Pricing & Credit Balance	`get_solo_price_card`, `get_credit_balance` (`$0.00`)	`{}` — returns exact USD per-tool rates and remaining workspace USD balance.
LLM & Coding-Agent Visibility Reads	`get_llm_visibility_overview`, `get_coding_agent_visibility` (`$0.00`)	`{ project_id?: "..." }` — cardless `$0.00` read tools; never require a payment method on file.
Generic Script Dispatcher (Mutations / Long-Tail)	`execute` / `run_action`	Use `action` (or `script_name` on `/api/v1/tools/run`) for long-tail platform scripts (`"sa360_get_campaigns"`, `"dv360_create_campaign"`). Call `inspect_script({ script_name: "..." })` first if flag names are unknown.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free