AdSparky documentation

AdSparky is a remote MCP (Model Context Protocol) server and a web dashboard for PPC specialists, freelancers and agencies that run Google Ads and Meta Ads for many clients. You work on client accounts in plain language from Claude, ChatGPT, Claude Code, Codex or another MCP client. The dashboard at www.adsparky.com shows clients, alerts, changes waiting for approval, the change history and reports.

Supported platforms:

• Google Ads
• Meta Ads (Facebook and Instagram)
• Google Analytics 4 (read only)
• Google Tag Manager
• Google Merchant Center
• Optionally, the client's website through the AdSparky WordPress plugin

One agency account holds many clients. A client profile links that client's Google Ads, Meta, GA4, Tag Manager and Merchant Center accounts, so the assistant always works on one selected client.

Numbers come from the platform APIs and are calculated by the AdSparky engine with fixed rules (for example 7, 14 and 28-day windows and a minimum number of conversions before a verdict). The AI assistant you use describes the results and proposes next steps; AdSparky itself does not run or call any AI model.

1. Create an account

AdSparky is in closed beta and free until November 4, 2026. Accounts are created by invitation: join the waitlist on adsparky.com and you will receive an e-mail with a personal sign-up link. Nothing is charged without your consent. Join the waitlist

Team members join through an invitation sent from the agency's dashboard (Settings → Team).

2. Connect Google and/or Meta

In the dashboard open Settings → Connections: Google, Meta. Only the agency owner or an admin can connect accounts. One platform is enough - you can add the other one later.

Both connections use the official OAuth sign-in of Google and Meta with verified apps. AdSparky never asks for your Google or Meta password.

Google: one sign-in covers Google Ads, GA4, Tag Manager and Merchant Center. Google's consent screen has a checkbox next to each scope. If you untick one, the connection still works and the dashboard tells you which features are unavailable without it. AdSparky requests these scopes:

Meta: you sign in with Facebook and choose which ad accounts and Pages AdSparky may access. Pages are needed only for lead forms - without a selected Page, AdSparky cannot read its leads.

Requested Meta permissions: ads_read, ads_management, business_management, pages_show_list, pages_read_engagement, pages_manage_ads, leads_retrieval

3. Add a client

After you connect, the accounts you have access to appear in Settings → Connections. Click “Add as client” next to an account. AdSparky suggests Google and Meta accounts with similar names, so one client can hold both. Use “Refresh account list” when a new account is shared with you.

The server address is the same for everyone:

https://adsparky.onrender.com/mcp

You sign in with your AdSparky account (OAuth) and click “Allow”. The assistant then works with your agency's clients and your role - nothing more. You use your own Claude or ChatGPT subscription.

Claude (claude.ai and Claude Desktop)

1. 1

   Open Customize → Connectors. On Team/Enterprise plans an owner adds the connector in Organization settings → Connectors.

2. 2

   Click “+” → Add custom connector.

3. 3

   Name it AdSparky and paste the server URL. Leave OAuth Client ID/Secret empty.

4. 4

   Click Add, then Connect - the AdSparky sign-in opens. Sign in and click “Allow”.

5. 5

   In a chat, enable AdSparky via “+” → Connectors. The connector also works in Claude Desktop and on mobile.

ChatGPT

1. 1

   In your browser, open ChatGPT → Plugins → “+” → Add custom MCP server. Access also depends on your workspace permissions.

2. 2

   Name it AdSparky and paste the server address from this page into Server URL. Choose Authentication: OAuth.

3. 3

   Choose Create as a plugin and connect your account - sign in to AdSparky and click “Allow”. Install the plugin you created.

4. 4

   In a new conversation type @ and select AdSparky, then ask it to check your client.

Claude Code

1. 1

   Add the server with one command. Paste in your terminal:

   claude mcp add -s user --transport http adsparky https://adsparky.onrender.com/mcp

2. 2

   Start Claude Code. Type /mcp, select adsparky and choose Authenticate.

3. 3

   Sign in and allow. The AdSparky sign-in opens in your browser. Sign in and click “Allow”.

Codex

1. 1

   Add the server with one command. Paste in your terminal:

   codex mcp add adsparky --url https://adsparky.onrender.com/mcp

2. 2

   Start the sign-in. This command opens the AdSparky sign-in in your browser:

   codex mcp login adsparky

3. 3

   Sign in and allow. Sign in to AdSparky and click “Allow”. Then start Codex.

Other MCP clients and API keys

Any client that supports remote MCP servers over HTTP with OAuth sign-in can use the same address. If your client cannot sign in with OAuth, create an API key in Settings → AI assistant (Claude / ChatGPT) → “API key - for Claude Code and Codex (advanced)” and paste the command shown there. Keys are stored only as a hash and can be revoked on the same page.

First message

Type “intro”. The assistant checks what you have connected and suggests first requests with your clients' names.

Write in plain language, in English or Polish. A few examples:

• “Audit the Google Ads account of client X”
• “Why did the cost per conversion go up last week?”
• “Which Meta creatives are showing fatigue?”
• “Where is budget wasted - placements and search terms that spend without conversions?”
• “Review target ROAS campaign by campaign”
• “Do a morning review of all clients”
• “Create a paused Search campaign for the new offer and show me the preview”
• “Duplicate the best Meta ad into a new ad set”
• “Swap the creative on this Meta ad”
• “Prepare the monthly report for the client”

Simple single changes (for example pausing one keyword) go straight to a preview. For larger tasks - a new campaign, changes across many campaigns, a bidding strategy - the assistant first agrees a short brief with you: goal, scope, boundaries and expected outcome. Tools that change accounts refuse to run without it.

AdSparky has more than 300 tools across Google Ads, Meta Ads, GA4, Tag Manager, Merchant Center and the client website. To keep the assistant's tool list short, it sees a core set of about 30 tools for the main workflows (reviews, audits, reports, changes, history and undo) and a gateway: the assistant searches the remaining tools by description and runs them through the gateway with the same safeguards as a direct call.

Every tool belongs to one of three kinds:

Read

Fetches and analyses data. Changes nothing.

Saves in AdSparky

Stores notes, client knowledge, goals or a brief in AdSparky. Does not touch ad accounts.

Changes an account

Changes an ad account, a Tag Manager container, Merchant Center or the client website. Always previewed and confirmed (see Safety).

Tool names and the split of the core set change as the engine evolves. The dashboard shows the current list of capabilities with descriptions.

Dry run and preview

Every account change is first calculated as a dry run and shown as a before/after preview. Nothing changes on the account at this stage.

Explicit approval

The change is applied only after you confirm it - in the chat or in the dashboard's approval queue.

Change log

Every change is recorded with its author, time, source (dashboard or assistant), reason and previous state. You see it in Change history.

One-step undo

Almost every change can be undone in one step. The preview flags the few exceptions before you confirm.

No deleting

AdSparky does not delete campaigns, ad sets or ads - at most it pauses them. New campaigns and ads are created paused.

Budget guardrail

One operation can raise a budget by at most 30% or cut it by at most 50%.

Client limits

Hard limits per client, for example a maximum daily budget, campaigns not to touch or allowed platforms. The assistant cannot get around them. From the chat they can only be made stricter; loosening is possible only in the dashboard (Client settings → Limits).

Automations

By default an automation only prepares a change for approval. Running automatically has to be turned on by an owner or admin, and stays within client limits and a daily action cap.

Team roles

Owner, Admin, Specialist and Viewer. Viewer is view-only: it sees data and advice but cannot prepare or approve changes. Only the owner or an admin connects Google and Meta.

• Each user authorizes their own Google and Meta accounts through OAuth. AdSparky sees only the accounts and scopes you grant.
• Google and Meta tokens are encrypted at rest (AES-256-GCM). API keys and connector access tokens are stored only as hashes.
• Agency data is isolated: every query is scoped to the signed-in user's agency, and data is never shared with other agencies using AdSparky.
• AdSparky does not call any AI model itself. The reasoning happens in your own Claude, ChatGPT, Claude Code or Codex. Results of the tools you run are returned to that assistant and processed by its provider under your own agreement with them.
• Data is used only to provide the service. It is not sold, not used for advertising and not used to train AI models. Use of data received from Google APIs follows the Google API Services User Data Policy, including the Limited Use requirements.

Full details, sub-processors and retention periods:

• Privacy policy (English section)
• Terms of service (English summary)
• Data processing agreement (English summary)

Google or Meta

Settings → Connections: Google, Meta → Disconnect. AdSparky revokes the token with Google or Meta and deletes it.

In your Google account

Remove AdSparky at myaccount.google.com/permissions.

In your Facebook account

Remove the AdSparky app in your Facebook settings. Meta then sends AdSparky a data deletion request and the Meta connection is deleted.

AI apps

Settings → AI assistant (Claude / ChatGPT) → Connected AI apps → Revoke. The app loses access within 30 seconds. API keys are revoked on the same page. You can also remove the connector in Claude or ChatGPT.

Everything

The agency owner can delete the agency and all its data in Settings → Account → Delete agency and data.

Manage Google access: myaccount.google.com/permissions

Questions or problems: write to kontakt@adsparky.com or ask the assistant to report a problem. Support page