Developer docs

MCP server

Connect your local Claude Desktop / Cursor / Cline / Continue agent to your SearchAd AI account and let it manage Apple Search Ads through chat.

Install

Modern MCP clients (Claude Desktop, Cursor, Cline, Continue) connect to remote MCP servers directly over HTTPS. Nothing to install — paste a URL and a bearer token into your client's MCP config:

{
  "mcpServers": {
    "searchad": {
      "url": "https://searchad.ai/mcp",
      "headers": {
        "Authorization": "Bearer sak_live_..."
      }
    }
  }
}

Where to put this block:

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Requires Claude Desktop ≥ Jan 2025.
Cursor: Settings → MCP → Add new server. Requires Cursor ≥ 0.46.
Cline / Continue: their respective settings pages — same JSON shape.

Restart the client. Your agent now has 24+ Apple Search Ads tools available.

If your client only supports stdio MCP, you can use the raw HTTP APIs below from your own shim. We may publish an official one later.

Get an API key

Go to searchad.ai/app.
Open Settings → API access for agents → MCP API keys.
Click + New key. Default scope is read — keep it that way unless you need mutating actions.
Copy the key (shown once) and paste it into SEARCHAD_API_KEY in your MCP config.

Scopes

Every key carries one or more scopes. Hierarchy: read < mutate < deploy. A key with mutate implicitly has read; a key with deploy implicitly has both.

Scope	What it can do
`read`	List apps, fetch dashboards, run all reports (spend, ad group, keyword, search term, impression share, ROAS, RevenueCat overview), search keywords, propose plans (drafts — no Apple writes).
`mutate`	Change bids, pause / resume campaigns, edit daily budgets. Subject to envelope enforcement. (Ships once we wire the first mutating tool.)
`deploy`	Create brand-new campaigns from a previously approved plan. Always lands paused. Always subject to envelope + approval enforcement.

Spending envelopes

An envelope is your pre-approved spending boundary: "agents may spend up to $X/day on apps Y in countries Z, valid until ." Created in the web UI under Settings → Spending envelopes. Mutating tools without a matching envelope are denied automatically; the error message points the agent at the approval URL.

Out-of-band approvals

If an action exceeds every envelope, the server returns a 403 with a URL. The flow:

Agent makes the call → 403 ENVELOPE_REQUIRED with approvalId + approvalUrl.
You receive a push notification (FCM) and see a banner in the web UI.
You open the approval URL, review the exact (tool, args) the agent proposed, click Approve.
The web UI displays a one-time token (valid 60 seconds).
You paste the token to the agent. The agent retries the tool call with _approvalId and _approvalToken in the arguments.
The server validates the token, confirms (tool, args) matches what you approved, consumes the token (single-use), and runs the tool.

Approval channel is out-of-band from the agent — a prompt-injected agent cannot self-approve, because the approval endpoint requires a Firebase Auth browser session.

Error codes

Code	HTTP	What to do
`BAD_AUTH`	401	Check `SEARCHAD_API_KEY`.
`REVOKED`	401	Key was revoked in the web UI. Issue a new one.
`EXPIRED`	401	Key expiry passed. Issue a new one.
`IP_NOT_ALLOWED`	403	Key has an IP allowlist; current IP isn't on it.
`SCOPE_INSUFFICIENT`	403	Tool needs a higher scope than this key has. Issue a new key.
`AGENTS_BLOCKED`	403	You hit the kill switch. Unblock from Settings → API access.
`ENVELOPE_REQUIRED`	403	No envelope covers this action. Create one or approve OOB.
`ENVELOPE_EXCEEDED`	403	Covering envelope is at daily cap. Raise the cap or approve OOB.
`APPROVAL_TOKEN_INVALID`	403	Token expired, reused, or doesn't match the current args.
`RATE_LIMITED`	429	60 req/min per key. Slow down.
`QUOTA_EXCEEDED`	429	10,000 req/day per key. Resets midnight UTC.
`UNKNOWN_TOOL`	404	Tool name not in the catalog. Call `GET /.well-known/tools` to list.
`TOOL_ERROR`	422	The Apple API or our tool itself failed; message has details.

Raw HTTP APIs

For custom integrations (your own agent framework, internal scripts, stdio-only MCP clients) you can hit either endpoint directly.

MCP-protocol endpoint (JSON-RPC 2.0)

Same wire format the install snippet above uses. Wrap it in your own shim if your client only speaks stdio:

POST https://searchad.ai/mcp
Authorization: Bearer sak_live_...
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"list_my_apps","arguments":{}}}

Methods: initialize, tools/list, tools/call, ping, shutdown. Returns MCP content blocks for tools/call; structured JSON-RPC results otherwise.

Custom invoke endpoint

Friendlier shape for shell scripts and direct API consumers:

POST https://searchad.ai/mcpInvoke
Authorization: Bearer sak_live_...
Content-Type: application/json

{ "tool": "list_my_apps", "args": {} }

To list tools:

GET  https://searchad.ai/mcpInvoke/.well-known/tools
Authorization: Bearer sak_live_...

Returns { ok: true, result: {...}, durationMs } on success; { ok: false, error: { code, message, details? } } on failure.

Limits

60 requests / minute / key
10,000 requests / day / key
20 active keys per user account
365-day maximum key expiry (90-day default)
20 active spending envelopes per account

Pricing

MCP calls don't cost SearchAd credits — your agent's LLM (Claude / GPT) runs against your subscription, not ours. Your SearchAd plan covers the tool surface and the underlying Apple API costs. Paid plans only.

Trust + safety

For the full security model, see the security page. Short version:

Apple credentials never leave Cloud Functions.
SearchAd stores the SHA-256 hash of your key — not the plaintext. We can't recover it; if you lose it, issue a new one.
Every MCP call is logged to your private audit log (live in the app under Settings → API access → View agent activity).
One-click kill switch revokes every key and blocks future calls.

Help

Stuck? Email team@searchad.ai or open an issue on GitHub. We'd like to know what's missing.