# PaidSync agent onboarding

PaidSync is a Model Context Protocol (MCP) server for paid media. AI agents
(Claude, ChatGPT, Gemini, Perplexity, Cursor, Windsurf, Claude Code) connect
once and operate Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads, Snapchat
Ads, Reddit Ads, Pinterest Ads, Microsoft Ads, Google Tag Manager, Google
Analytics 4, Google Search Console, Google Merchant Center, and ChatGPT Ads.

This file is the plain-English entry point for agents and integrators.
Machine-readable equivalents are at the well-known endpoints listed below.

## Capability summary

- 630+ tools across 14 platforms.
- 14 platforms: Google Ads, Meta Ads, LinkedIn Ads, TikTok Ads, Snapchat
  Ads, Reddit Ads, Pinterest Ads, Microsoft Ads, X Ads, ChatGPT Ads,
  Google Tag Manager, Google Analytics 4, Google Search Console
  (read-only in PaidSync), and Google Merchant Center. Read and write
  on every platform except Google Search Console. New campaigns can be
  created on Google Ads, Meta, LinkedIn and ChatGPT Ads; on TikTok,
  Snapchat, Reddit, Pinterest, X and Microsoft Ads, PaidSync manages
  existing campaigns.
- Verified Marketing Partner with Google, Meta,
  and TikTok.
- Guarded writes. Creates are previewed with a dry run first, and
  destructive changes (delete, remove, pause, disable, revert, budget
  updates) need an explicit confirm. In the PaidSync workspace every
  write is also held as an approval card, and an applied card offers Undo when the change has a safe inverse. Over MCP,
  the approval step is your assistant's own confirmation prompt.
- One MCP endpoint, one auth token, one connection.

The full tool registry is not enumerated here. Authenticated agents can
fetch the live list by calling the MCP `tools/list` method after a
successful `initialize` handshake.

## MCP connection

- Endpoint: `https://paidsync.ai/mcp` (alternate: `https://mcp.paidsync.ai/mcp`)
- Transport: streamable HTTP
- Server card: `https://paidsync.ai/.well-known/mcp/server-card.json`
- Handshake: standard MCP `initialize` is required before `tools/list` or
  `tools/call` will succeed.

## Authentication

Three supported paths. Pick the one that matches your agent runtime.

### 1. API key (recommended for headless / programmatic agents)

- Issue the key from the dashboard at `https://paidsync.ai/dashboard`.
- Key format: `ps_` followed by 64 hex characters. There is no sandbox key.
- Send the key in a header on every MCP request, either
  `Authorization: Bearer ps_...` or `x-api-key: ps_...`.
- Header only. Never put the key in a URL; query strings end up in
  browser history and server, proxy and client logs.
- An API key cannot apply changes to Google Ads (reads and dry runs
  only). On the other platforms it can apply changes, under the same
  checks as an OAuth session.

### 2. OAuth 2.1 with PKCE (recommended for end-user-facing agents)

- Discovery: `https://paidsync.ai/.well-known/oauth-authorization-server`
- Protected resource metadata:
  `https://paidsync.ai/.well-known/oauth-protected-resource`
- Grants: `authorization_code`, `refresh_token`
- PKCE: required
- Client registration: dynamic client registration (RFC 7591) is live at
  `https://api.paidsync.ai/register`. Clients are public (token endpoint
  auth method `none`) and use PKCE, so there is no client secret.
- Scopes: `openid`, `email`, `profile`, `ads`.

### 3. OpenID Connect (identity)

- Discovery: `https://paidsync.ai/.well-known/openid-configuration`
- Use when your agent platform expects an OIDC identity provider.

## Bot identity (RFC 9421 Web Bot Auth)

PaidSync publishes a signature directory at
`https://paidsync.ai/.well-known/http-message-signatures-directory` so bot
clients with verified-bot identity can present signed requests. The
directory file is available today; live response signing is on the roadmap.

## Tool listing

PaidSync does NOT publish the full tool registry statically. The complete
list, with parameter schemas, is returned by the MCP `tools/list` method
after an authenticated `initialize`. Category-level skill buckets are
listed in `.well-known/mcp/server-card.json` (under `skills`) and in
`.well-known/agent-skills/index.json` for discovery.

## Discovery and related metadata

| Path | Purpose |
|---|---|
| `/AGENTS.md` | This file (root alias) |
| `/.well-known/agents.md` | This file (well-known alias) |
| `/.well-known/agent-auth.json` | Machine-readable auth and registration discovery |
| `/.well-known/mcp/server-card.json` | MCP server card (skills, auth, pricing) |
| `/.well-known/mcp.json` | MCP discovery alias |
| `/.well-known/agent-card.json` | A2A agent card |
| `/.well-known/agent-skills/index.json` | Skill index |
| `/.well-known/api-catalog` | RFC 9727 API catalog |
| `/.well-known/ai-plugin.json` | Legacy ChatGPT plugin manifest |
| `/.well-known/oauth-authorization-server` | RFC 8414 OAuth discovery |
| `/.well-known/oauth-protected-resource` | RFC 9728 protected resource metadata |
| `/.well-known/openid-configuration` | OIDC discovery |
| `/.well-known/http-message-signatures-directory` | RFC 9421 signature directory |
| `/.well-known/security.txt` | RFC 9116 security contact |
| `/llms.txt` | LLM-targeted short index |
| `/llms-full.txt` | LLM-targeted long form |

## Contact

- Partnerships: partners@paidsync.ai
- Security: security@paidsync.ai
- Support: support@paidsync.ai

Last updated: 2026-06-15.