# Synter Media AI - Documentation for AI Agents (llms.txt)

> Synter is the AI Agent Operator for Ads across 21 ad platforms. It provides a Model Context Protocol (MCP) server, REST APIs, a Campaign IDE, and CAPI conversion tracking.

## Core Resources & Guides

- [Quickstart Guide](https://docs.syntermedia.ai/quickstart): 5-minute setup guide to connect ad platforms and issue your first campaign prompt.
- [MCP Overview](https://docs.syntermedia.ai/mcp/overview): Connecting AI clients (Cursor, Claude Desktop, Claude Code, ChatGPT) to Synter MCP.
- [MCP Configuration](https://docs.syntermedia.ai/mcp/configuration): Detailed setup instructions and client configurations for `mcp.syntermedia.ai`.
- [MCP Tool Catalog](https://docs.syntermedia.ai/mcp/tools): Complete reference of available MCP tools (pull metrics, generate creative, manage campaigns, audit tracking).
- [MCP Scopes](https://docs.syntermedia.ai/mcp/scopes): Which scope each tool requires on your API key.
- [MCP Rate Limits](https://docs.syntermedia.ai/mcp/rate-limits): Per-key request and credit limits.
- [MCP Error & Troubleshooting Runbooks](https://docs.syntermedia.ai/mcp/errors): Diagnosing auth, reauth required, rate limits, and invalid campaign configurations.
- [API Reference - Authentication](https://docs.syntermedia.ai/api/authentication): Authenticating REST requests with `X-Synter-Key`.
- [REST Endpoints](https://docs.syntermedia.ai/api/run-script): Run a script, plus [list campaigns](https://docs.syntermedia.ai/api/list-campaigns), [get metrics](https://docs.syntermedia.ai/api/get-metrics), [pause campaign](https://docs.syntermedia.ai/api/pause-campaign), [update budget](https://docs.syntermedia.ai/api/update-budget).
- [Playground](https://docs.syntermedia.ai/playground): Test API calls interactively.
- [Best Practices](https://docs.syntermedia.ai/best-practices): Tips for efficient usage.
- [Integrations](https://docs.syntermedia.ai/integrations): Platform connection details.
- [Changelog](https://docs.syntermedia.ai/changelog/mcp-server-launch): Release notes.

## Full Documentation

For every tool parameter, API example, and integration detail, see
https://docs.syntermedia.ai/llms-full.txt

## MCP Connection Details

- **MCP Endpoint**: `https://mcp.syntermedia.ai`
- **Authentication**: `X-Synter-Key: syn_your_api_key_here` (or Bearer token)
- **Onboarding without API key**:
  1. Call `synter_onboarding_start(email="you@company.com")`
  2. Click magic link in email to verify
  3. Poll `synter_onboarding_status(session_token="...")` until account is ready.

Tool names are unprefixed on the wire. Some clients display them with a prefix
(Cursor shows `mcp_synter_onboarding_start`); call the unprefixed name.

## Key MCP Tools & Commands

Signatures below are the registered parameters on `mcp.syntermedia.ai`. A
parameter with no default is **required**; `name=value` shows the default;
`name?` is optional with no default.

### 1. Performance & Reporting

- `pull_google_ads_performance(days=30, date_range?, level="campaigns", account_id?, account_name?, start_date?, end_date?)`: Google Ads impressions, clicks, spend, conversions, CPA per campaign.
- `pull_meta_ads_performance(days=30, date_range?, level="campaign", account_id?, account_name?, start_date?, end_date?)`: Meta (Facebook/Instagram) metrics. `level` accepts campaign, ad-set, ad.
- `pull_linkedin_ads_performance(days=30, date_range?, account_id?, account_name?, start_date?, end_date?, campaign_group_ids?)`: LinkedIn metrics. `campaign_group_ids` is comma-separated.
- `pull_x_ads_performance`, `pull_reddit_ads_performance`, `pull_tiktok_ads_performance`, `pull_microsoft_ads_performance`: same window parameters as above, `(days=30, date_range?, account_id?, account_name?, start_date?, end_date?)`.
- `pull_amazon_ads_performance(days=30, ad_type="ALL", account_id?, account_name?)`.
- `pull_openai_ads_performance(days=30, campaign_id?, ad_group_id?, ad_id?, aggregation_level?, time_granularity?, limit=1000, account_id?, account_name?)`.
- `get_spend_reconciliation(start_date, end_date, google_account_id?, google_account_name?, ttd_advertiser_id?, ttd_account_name?)`: Cross-platform reconciliation (Google Ads vs The Trade Desk) with discrepancies and likely causes. Read-only, range capped at 92 days.
- `list_campaigns(platform, account_id?, status?, account_name?)`: List campaigns for one platform.

Date windows: pass a `date_range` preset (`today`, `yesterday`, `last_7_days`,
`last_14_days`, `last_30_days`, `last_90_days`), or `start_date`/`end_date` as
`YYYY-MM-DD` for a custom range, or `days` for a rolling window. There is no
`campaign_id` filter on the `pull_*_performance` tools. If more than one account
is connected for a platform, ask the user which one and pass `account_name`.

### 2. Campaign Planning & Execution

- `research_campaign_opportunity(seed_keywords, competitor_domains?, geo_target="2840", platforms="google,meta", include_trends=false, landing_page_url?, account_id?, account_name?)`: Real keyword volumes and CPCs, competitor ads, current trends. Run this **before** `create_campaign_plan`.
- `create_campaign_plan(plan_key, title, brief_json?)`: Create or update a reviewable launch plan. `plan_key` is the idempotency key; objective, platforms and budget go inside `brief_json`. The response carries the `execute_token`.
- `execute_campaign_plan(plan_id, execute_token)`: Launch the planned entities across connected platforms in dependency order. **Both parameters are required** - `execute_token` comes from the `create_campaign_plan` response, and the call fails without it.

### 3. AI Creative Generation

- `create_ad_copy(platform, product, landing_page_url?, tone="professional", headlines_count?, descriptions_count?, keywords?, cta?)`: Text ad copy - headlines, descriptions, CTAs - respecting each platform's character limits.
- `create_image(prompt, size?, provider="imagen", name?)`: One AI image. `size` defaults to `1200x628`; `provider` accepts imagen, flux, sdxl.
- `create_image_asset(prompt, platform?, name?, provider="imagen", sizes?, negative_prompt?, headline?, cta?, subheadline?, mode="ai", eyebrow?, stat?, creative_brief?)`: Platform-sized display/social image. Use `mode="system-graphic"` (requires `headline`) for text-led creative; always pass `headline` for LinkedIn.
- `create_video_ad(concept, product, platform="tiktok", provider?, pain_point?, benefit?, cta="Learn more", name?, target_audience?)`: Concept-templated video ad. `concept` accepts ugc-testimonial, pas, vs-alternative, made-easy, before-after, hook-demo-cta, product-demo, social-proof.
- `generate_video(product_name, key_benefit, concept="pas", target_audience?, duration?, provider?)`: Generic AI video generation (Veo, Runway, Luma).

### 4. Conversion & Tracking

- `verify_pixel_ownership(url, platform, account_id?)`: Cross-validates that the pixel/tag IDs on a landing page belong to the connected ad account. Takes the **page URL**, not a pixel ID.
- `audit_account_structure(platform="reddit", account_id?, account_name?)`: Read-only structure audit - duplicate campaign/ad group/ad names, empty or invalid targeting, rebuilt-not-edited campaigns.

### Retired names

`generate_text_ad`, `generate_image_ad`, `generate_video_ad` and
`reconcile_platforms` are **not** MCP tools. They survive only as legacy script
aliases reachable through `execute(action=...)`. Calling them as tools returns
tool-not-found. Use `create_ad_copy`, `create_image_asset`, `create_video_ad`
and `get_spend_reconciliation` instead.