# AdsAgent Tri-Channel Plugin

MCP here means **Model Context Protocol** (the Claude/Cursor tool-calling standard). It does **not** mean Multi-Channel Platform.

Public skill pack and plugin for AdsAgent tri-channel hosted MCP: Meta, Google Ads, and TikTok. It supports **ChatGPT, Claude, Codex, and Cursor**.

> **Directory SEO one-liner:** AdsAgent is a hosted **Meta Ads MCP** (Model Context Protocol) plus Google Ads & TikTok MCP — connect Claude/Cursor via [adsagent.md/connect](https://adsagent.md/connect?utm_source=github&utm_medium=readme&utm_campaign=adsagent-ai-skills).

**Install:**

- **Claude plugin:** `claude plugin marketplace add adsagents/adsagent-ai-skills` then `claude plugin install adsagent@adsagent`
- **Cursor plugin:** install AdsAgent from Cursor Marketplace (this repo's `.cursor-plugin/` + `mcp.json`)
- **Dashboard fallback:** AdsAgent dashboard -> Settings -> MCP Access -> Copy install prompt (clients without plugin support)

**Supported clients:**

| Client | How it uses this repo | Status |
| --- | --- | --- |
| **Claude** (Code, Desktop, Cowork) | `adsagent` plugin: skills + `.mcp.json` OAuth MCP URLs | Listed in the Claude plugin directory; also installable from this repo's marketplace |
| **ChatGPT** | The same `skills/<name>/SKILL.md` Agent Skills folders, plus a connection to the three hosted MCP endpoints | Skills supported |
| **Codex** | Plugin marketplace (`codex plugin marketplace add adsagents/adsagent-ai-skills`) or a plain skills clone | Submitted |
| **Cursor** | `.cursor-plugin/` + `mcp.json` | Current version listed on Cursor Directory and MCP Market |

Skills describe client-independent behavior. Install steps differ per client and live in [Installation](#installation).

**Distribution split (important):**

| Surface | What it is | This repo? |
| --- | --- | --- |
| **Claude plugin** (self-hosted marketplace) | Skills + root `.mcp.json` HTTP MCP URLs (OAuth) | Yes |
| **Cursor plugin** (marketplace manifest) | Skills + `mcp.json` HTTP MCP URLs (OAuth) | Yes |
| **Anthropic Connectors Directory** | Hosted MCP server listing only | No — separate submission on `adsagent.md` services |

**Official GitHub repo:** [github.com/adsagents/adsagent-ai-skills](https://github.com/adsagents/adsagent-ai-skills)

**Website:** [adsagent.md](https://adsagent.md?utm_source=github&utm_medium=readme&utm_campaign=adsagent-ai-skills)  
**Official links hub:** [adsagent.md/connect](https://adsagent.md/connect?utm_source=github&utm_medium=readme&utm_campaign=adsagent-ai-skills)  
**Skill pack landing page:** [adsagent.md/skills](https://adsagent.md/skills?utm_source=github&utm_medium=readme&utm_campaign=adsagent-ai-skills)  
**Support:** [support@adsagent.md](mailto:support@adsagent.md)

**Privacy:** [AdsAgent Privacy Policy](https://adsagent.md/privacy)

Also listed on [Product Hunt](https://www.producthunt.com/products/adsagent), [Cursor Directory](https://cursor.directory/plugins/adsagent-meta-mcp), and [MCP Market](https://mcpmarket.com/zh/server/adsagent-ai-skills).

Current contract version: `0.7.76`. The plugin slug is `adsagent` (marketplace key `adsagent`).

For contributor cloud environments, provision `uv` in the image and run the
bundled `bash scripts/cloud-agent-setup.sh`; see
[cloud setup](docs/cloud-agent-setup.md). Plugin users do not run this setup.
New Meta connections default to the v2 product profile; all three hosted endpoints
negotiate modern MCP `2026-07-28` stateless discovery while retaining supported
legacy initialize clients.


Version history lives in [CHANGELOG.md](CHANGELOG.md).

The local helper `scripts/update_reminder.py` compares strict semantic versions and stores only bounded version/timestamp state in `$XDG_CACHE_HOME/adsagent-ai-skills/update-reminder-v1.json` (or `~/.cache/...`). Cache failure never blocks MCP work.

## What This Is

- A public Claude plugin marketplace package: **behavior skills** plus **hosted MCP URLs** via `.mcp.json`.
- A behavior guide for Claude Code, Cursor, Codex, and other MCP-aware clients.
- A reliability and safety layer that tells agents when to retry, when to wait, and when to stop.
- A versioned GitHub distribution for AdsAgent user onboarding and agent behavior guidance.
- A data-minimization contract for AI agents that should not scan AdsAgent like a raw database.
- Optionally, a Glama-deployable **AdsAgent Skill Pack (docs)** stdio MCP that lists and reads public `skills/` Markdown. See [docs/glama-release.md](docs/glama-release.md).

## What This Is Not

- Not the hosted AdsAgent Meta, Google Ads, or TikTok MCP backend. The optional Docker/Glama image only serves this repository's public docs; ads tools remain on the HTTP URLs in `mcp.json` and require AdsAgent OAuth.
- Not the Anthropic Connectors Directory MCP listing (that is registered separately on the hosted servers).
- Not a complete MCP tool reference.
- Not an SDK.
- Not a local transport relay for ads APIs.
- Not a disclosure of AdsAgent backend routes, schemas, database tables, or internal diagnostics.

For Claude Code plugin installs, OAuth MCP setup comes from this repo's `.mcp.json`.
For clients without plugin support, the AdsAgent dashboard install prompt remains
the manual fallback:

```text
AdsAgent dashboard -> Settings -> MCP Access -> Copy install prompt
```

Use that copied prompt only for a manual connection when the account exposes
MCP Access. Installed Claude plugins already include the three URLs. The setup
skill guides users from a missing connection through authorization to their
original advertising task.

## Connect After Installing

Start with the channel you need. Installing the skill pack does not authorize
an advertising account, and a Meta task does not require Google or TikTok setup.

| Client | Connect the requested channel |
| --- | --- |
| Claude web, Desktop, or Cowork | Open Settings -> Connectors and use the installed AdsAgent connection's Connect action. If only skills were installed, add a custom connector using the hosted URL below. Complete browser OAuth. |
| Claude Code | Open `/mcp` and authenticate the requested bundled server. Reuse an existing connection. |
| Cursor | Authenticate the requested bundled server in MCP settings. |
| Other MCP clients | Add the requested hosted HTTP URL with OAuth, or use the account's dashboard install prompt. |

| Channel | Hosted MCP URL |
| --- | --- |
| Meta | `https://adsagent.md/mcp/v2` |
| Google Ads | `https://google.adsagent.md/mcp` |
| TikTok | `https://tiktok.adsagent.md/mcp` |

Then ask: **"Check my Google Ads connection and help me finish any missing
authorization, then show yesterday's campaign performance."** Substitute your
channel and task. AdsAgent checks that channel, supplies a browser link when
needed, waits for you to finish, and resumes the same task. For a connection
check alone, it reports the result without starting a report.

Each server has its own OAuth authorization. Use the same AdsAgent login in
the browser and client; never copy an OAuth token between the three URLs.

For multiple OAuth tenants on one server, each workflow retains its selected
connection through approval, confirmation, task queries and retries. Selection
uses an explicit account choice, uniquely verified object ownership, or the
sole available connection; ambiguous choices need one account question. See
[multi-tenant routing](docs/faq.md#how-are-multiple-oauth-tenants-selected) for
the installed policy and optional client-adapter dispatch guard.

Platform authorization and initial asset/history sync are separate steps;
"connected" does not mean history is loaded or ads are ready to launch.

Claude connection controls are documented in the official
[custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)
and [Claude Code MCP guide](https://code.claude.com/docs/en/mcp).

## Official MCP Registry manifests

Three hosted-server manifests record the existing `md.adsagent/*` entries in the
[official MCP Registry](registry/README.md), first published on 2026-08-18.
Version `1.0.0` was verified active/latest on 2026-10-09; these files are snapshots,
not pending publications. GitHub first-time directory inclusion remains under
manual review. The public skills, guides and connection configurations are MIT;
the hosted advertising backends are proprietary.

## Included Skills

| Skill | Purpose |
| --- | --- |
| `adsagent-router` | Route AdsAgent requests to setup, reliability, approvals, insights, create, or manage workflows. |
| `adsagent-setup` | Connect the requested MCP, complete platform authorization, verify usable account scope, and resume the original task. |
| `adsagent-notifications` | Inspect alerts, request an alert refresh, and explain supported MCP Events or retired integrations. |
| `adsagent-approvals` | Shared prepare, approval, and confirm rules: `needs_input`, dry-run (`validate_only`) rejections, amount-guard refusals, error classes, and never replaying a write whose result is unknown. |
| `adsagent-reliability` | Respect retry, backoff, session refresh, and concurrency limits. |
| `agent-scheduled-tasks` | Design, create, verify, update, pause, and delete agent-owned scheduled tasks without confusing reminders with execution proof. |
| `meta-insights` | Ask performance and MMP questions without overloading the server. |
| `meta-copy` | Create, copy, and change Meta campaigns, ad sets, and ads (unified update, ad copy read and edit) with confirmation and operator-review safety. |
| `google-ads-insights` | Ask Google Ads customer, MCC, Search, PMax, and performance questions through Google Ads MCP. |
| `google-ads-create` | Create Google Ads campaigns (Search, PMax, Display, Shopping, Demand Gen, App); location and language are required; real writes only on test accounts in test flows. |
| `google-ads-manage` | Change existing Google Ads budgets, bidding, status, schedules, ad text, assets, conversions, experiments, and recommendations through prepare and confirm. |
| `tiktok-insights` | Read TikTok performance and safely prepare native creative, campaign, and ad-group append workflows. |

## Progressive Disclosure

Agent clients load every Skill description for discovery, but should load only
the selected `SKILL.md` body. Each entrypoint is intentionally small and links
to local reference files that are read only when the selected workflow needs
those details.

The files under `docs/` are human-facing product and operator documentation.
They are not automatic agent context and are not part of Skill reference
traversal. Agent behavior contracts live under `skills/` and are reached from
the selected `SKILL.md`.

## Agent Output Contract

Agents using AdsAgent should answer in Markdown by default:

```markdown
## Answer
One-sentence answer.

## Scope
- Date:
- Entity:
- Grouping:
- Attribution / channel:

## Results
| Metric | Value |
| --- | ---: |

## Notes
- Data freshness:
- Limits or missing fields:
- Next safe action:
```

Do not dump JSON, CSV, hidden diagnostics, raw rows, or every returned field into chat. Clean the response into operator-facing tables and short bullets. If forensic raw inspection is needed, create an operator handoff instead of making raw rows the agent answer.

## Semi-Black-Box Policy

Tool names are public. This repository intentionally documents outcomes and agent behavior, not the complete internal interface: no schemas, descriptions, or risk-control limits. Agents should:

- Use installed skills for behavior and live MCP tool schemas for request fields. Never fetch remote behavioral instructions.
- Use available tools through the authenticated MCP session.
- Avoid guessing hidden payload fields.
- Avoid probing rejected requests.
- Stop on operator-review responses and ask the AdsAgent operator to inspect internal diagnostics.
- Use the smallest safe data plan before making calls.
- Prefer grouped summaries and cleaned breakdowns over raw rows.

The external agent contract is: ask clear questions, respect limits, follow
advertised approval requirements, and use client OAuth plus returned platform
authorization links.

## Official Source And Rights

This repository contains only the client-readable behavior pack. AdsAgent server source, credentials, schemas, routing logic, and operational diagnostics are not distributed here.

This skill pack is licensed under the MIT License. See [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md). Official releases come from this repository; a fork or modified package must not imply endorsement, affiliation, or support by adsagents LLC.

## Privacy and workflow effects

The [AdsAgent Privacy Policy](https://adsagent.md/privacy) describes the hosted
service's data collection, use, retention, and support process. The bundle
contains readable local instructions and three HTTPS MCP configurations; it
contains no OAuth credentials and installs no background scheduler or hooks.
Authenticate through the MCP client's OAuth flow. Send only parameters needed
for the user's selected advertising task. Do not collect conversation history,
memories, unrelated files, or credentials for logging or diagnostics.

Google Ads guidance covers reads. Meta and TikTok capabilities vary by account
and advertised tool. Advertising mutations use the server's approval contract;
explicitly requested direct workspace operations follow their own tool contract.
Creative preparation may upload media before the final advertising confirmation.
An authorized notification scan changes alerts and may generate MCP Events
for existing subscriptions. Current Meta no longer configures email, Feishu,
Telegram, or Meta Ads Webhooks through this pack.
Scheduled workflows use an available host scheduler and require user intent.

## Example Prompts

```text
Use AdsAgent to list my connected Meta products, Google Ads customers, or TikTok advertisers, then ask which scope's today data I want to inspect.
```

```text
For Google Ads, inspect agent_method_profile, pick an enabled non-manager customer, and use one cached insights_query_consistent request when the profile is advertised.
```

```text
For TikTok, inspect agent_method_profile and use one insights_query_consistent scopes request when advertised; otherwise use the native batch overview fallback.
```

```text
Prepare a copy of this winning Meta ad into the target account, but ask me for confirmation before creating anything.
```

```text
Group these distinct Meta Ads by language into the requested Campaign and AdSet layout. Prepare one grouped_plan, show every settings_source_ad_id and geography override, and wait for my approval before confirming once.
```

More examples are in [docs/examples.md](docs/examples.md).

## Validation

Run the local release contract and tests:

```bash
python scripts/validate_tri_channel_pack.py
python scripts/validate_release_manifest_tag.py
python -m pytest -q
```

Releases are published tag-first: create the git tag and GitHub release,
then point `release-manifest.json` on main at that tag. The tag check above
passes only when the tag is published on origin, the tagged tree carries
that version, and the GitHub release exists, because sync clients fetch
the tagged manifest and would otherwise fail with 404.

The blocking checks are offline: skill structure, the tool reference contract
(`contracts/public-tool-references.json`), and the list of deprecated tools
(`contracts/deprecated-tools.json`), which skills and docs must not mention.

```bash
python scripts/validate_public_tool_manifests.py
```

Whether the skills still match the services is checked separately by
`scripts/check_drift.py` against the services' current public tool-name
manifests. That check only warns and opens an issue; it never blocks a merge or a
release. See [docs/drift-check.md](docs/drift-check.md).

## Installation

This repo ships as the **`adsagent` Claude plugin** (skills + `.mcp.json` MCP URLs).
The GitHub repository name stays `adsagent-ai-skills`.

### Claude Code (recommended)

```bash
claude plugin marketplace add adsagents/adsagent-ai-skills
claude plugin install adsagent@adsagent
```

Update an existing user-scope install:

```bash
claude plugin update --scope user adsagent@adsagent
```

If `claude plugin list` shows duplicate local and user installs, keep user scope:

```bash
claude plugin uninstall --scope local adsagent@adsagent
```

Start a fresh Claude Code session after installing or updating.

### Cloud / Cowork preinstall (settings snippet)

```json
{
  "extraKnownMarketplaces": {
    "adsagent": {
      "source": {
        "source": "github",
        "repo": "adsagents/adsagent-ai-skills"
      }
    }
  },
  "enabledPlugins": ["adsagent@adsagent"]
}
```

After install, authenticate only the MCP servers needed for your task. In
Claude Code use `/mcp`; in Claude web/Desktop or Cowork use Settings -> Connectors.
Do not add `headers.Authorization` to `.mcp.json`; OAuth must remain the auth path.

### Migrating from legacy plugin slugs

Older installs used `adsagent-ai-skills@adsagent-ai-skills` or
`adsagent-meta-ai-skills@adsagent-meta-ai-skills`. The marketplace declares a
rename to `adsagent@adsagent`. After migrating, remove legacy duplicates:

```bash
claude plugin uninstall --scope user adsagent-ai-skills@adsagent-ai-skills
claude plugin uninstall --scope user adsagent-meta-ai-skills@adsagent-meta-ai-skills
```

### Codex CLI

```bash
codex plugin marketplace add adsagents/adsagent-ai-skills
codex plugin add adsagent@adsagent
```

Refresh:

```bash
codex plugin marketplace upgrade adsagent
```

Start a fresh Codex session after installing or upgrading.

### Git fallback and other Agent-Skills-compatible clients

The skills in `skills/` use the standard Agent Skills layout
(`skills/<name>/SKILL.md` with YAML frontmatter). Clients that only consume skills
(without the plugin MCP bundle) can clone manually:

```bash
git clone https://github.com/adsagents/adsagent-ai-skills.git ~/.codex/skills/adsagent-ai-skills
```

Those clients still need a separate MCP connection (dashboard install prompt or
Connectors Directory). The plugin path is the one-step skills + MCP bundle.

For a manual client, use hosted OAuth or, when available to your account,
AdsAgent's dashboard install prompt:

```text
Settings -> MCP Access -> Copy install prompt
```

Paste the copied prompt into a fresh chat when the plugin bundle is not used.
The prompt provides hosted HTTP MCP URLs for:

```text
Meta default: https://adsagent.md/mcp/v2
Meta legacy fallback: https://adsagent.md/mcp
Google Ads: https://google.adsagent.md/mcp
TikTok: https://tiktok.adsagent.md/mcp
```

## Important Runtime Rules

- Hosted HTTP MCP only for ads work.
- Use `https://adsagent.md/mcp/v2` for new Meta connections; `/mcp` is the legacy fallback.
- Do not run or relay the hosted AdsAgent ads MCP locally. The optional `skill_pack_mcp` image is a docs-only reader of this repository; it is not an ads backend.
- Do not use a local relay unless the AdsAgent dashboard explicitly says to.
- Cache connection setup where the client supports it.
- Keep per-token MCP concurrency bounded.
- Respect `Retry-After`.
- Parse `Retry-After` from the HTTP header, top-level `data`, or JSON-RPC `error.data`.
- Honor `mcp_concurrency_limited` with wait plus jitter.
- Honor `mcp_fanout_detected` by switching to the platform batch overview tool instead of retrying the blocked single-scope request.
- When `agent_method_profile.profile_id=adsagent_agent_methods_v1` and its consistent read is present in the client-local catalog, use one `insights_query_consistent` request with `scope` or ordered `scopes` for all three platforms.
- Without that profile, or when its advertised read is missing only from the client-local catalog, use the profile's named native fallback or the documented server-side tools: Meta/TikTok `insights_query_batch_overview`, Google `google_ads_insights_overview_batch`. Do not report a server registration failure from a local selector miss.
- Query aggregated data first and never infer cross-platform capability parity from a shared tool name.
- Report server-computed totals from the response; do not sum currently visible rows.
- Trust totals only when `meta.complete=true`; missing scopes are unknown, never zero.
- Poll queued tasks to `terminal=true` and return the artifact link instead of raw CSV.
- Poll queued work directly with `tasks_get_status(task_ref=...)` when the server advertises direct task refs.
- QuickCreate confirm tokens are single-use and expire after 15 minutes. Check `expires_at`; after `confirm_token_invalid`, prepare again, show the new summary, and obtain fresh explicit approval.
- Poll Meta creation tasks with `tasks_get_status(task_ref=..., response_mode=compact)`. On `no_create_permission`, direct the user to `/dashboard/assets/fb-users`; never change customer permissions or replay the failed creation automatically.
- Avoid raw-row reads in normal user conversations.
- Use Markdown tables for numbers.
- Confirm before ad creation or modification.
- Use `grouped_plan` for multiple distinct source Ads; never emulate it through a client-side series of copy mutations.
- Stop on operator-review errors.
- When an error includes `support_ref`, preserve and show it verbatim for support. It is not authorization; never invent, modify, enumerate, or replace it with tokens, request bodies, or logs.

## Links

- Official website: https://adsagent.md
- Official repository: https://github.com/adsagents/adsagent-ai-skills
- Support: support@adsagent.md
- Public onboarding path: https://adsagent.md/docs/mcp-onboarding

## Glama / Docker docs MCP

The root `Dockerfile` builds **AdsAgent Skill Pack (docs)** — a stdio MCP that
exposes `list_skills`, `get_skill`, `get_hosted_mcp_urls`, and `get_pack_readme`.
Glama Build → Make Release scores that docs server. It does **not** replace
`https://adsagent.md/mcp/v2`, `https://google.adsagent.md/mcp`, or
`https://tiktok.adsagent.md/mcp`. Details: [docs/glama-release.md](docs/glama-release.md).

## License

MIT. See [LICENSE](LICENSE).