Model Context Protocol

Manage 9 ad platforms from your AI agent

Connect Claude Code, Cursor, Claude Desktop, Windsurf, VS Code, Codex, Gemini CLI, Hermes, or any MCP client to your ad accounts across Meta, Google, TikTok, LinkedIn, Reddit, Apple, Bing, ChatGPT, and Snapchat. BYOA gets the bridge; Starter+ unlocks Lazy Ads AI.

Quick start

1. Generate an API key

In the Lazy Ads dashboard open Settings → API and create a key. Any paid plan works: BYOA for the bridge, Starter or above for the full suite with Lazy Ads AI.

2. Add the server to your client

Point your MCP client at https://mcp.lazyads.ai/mcp over Streamable HTTP and send the key as Authorization: Bearer on every request. Copy the snippet for Claude Code, Cursor, Claude Desktop, Windsurf, VS Code, Codex, Gemini CLI, or Hermes.

3. Verify and start prompting

Run tools/list (or ask "Which ad platforms am I connected to?"). BYOA sees the 33 bridge tools; Starter and above see all 47.

Hosted endpoint

Production is live at https://mcp.lazyads.ai/mcp. Nothing to install or run: your client speaks Streamable HTTP to us and we talk to the ad platforms with the accounts you connected in the dashboard.

Endpoint: https://mcp.lazyads.ai/mcp
Transport: Streamable HTTP, MCP 2026-07-28 (stateless: no session handshake)
Auth: Authorization: Bearer <api-key> on every request (X-API-Key also accepted)
Rate limits (per key, per minute): BYOA 60 · Starter 30 · Growth 100 · Scale 500 · Enterprise 1000. 429 + Retry-After on bursts
Access modes: Bridge: 33 tools on every paid plan incl. BYOA. Full: 47 tools on Starter, Growth, Scale, Enterprise
MCP Registry: ai.lazyads/mcp (server.json points at the hosted endpoint)

Verify your key from any shell (returns the tool list)

curl -sS https://mcp.lazyads.ai/mcp \
  -H "Authorization: Bearer la_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Developing against a local checkout? npm run dev:http in services/mcp-server serves the same server at http://127.0.0.1:3100/mcp.

Setup by client

Every snippet points at the hosted endpoint and sends your key as a Bearer header. Replace la_your_api_key with the key from Settings → API, or reference it from an environment variable where the client supports it.

Claude Code

Terminal (writes ~/.claude.json or .mcp.json)

claude mcp add --transport http lazyads https://mcp.lazyads.ai/mcp \
  --header "Authorization: Bearer la_your_api_key"

Add --scope project to commit a .mcp.json for your team; keep the key in an env var with "Authorization: Bearer ${LAZY_ADS_API_KEY}". Run /mcp inside Claude Code to confirm the server is connected.

Cursor

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

{
  "mcpServers": {
    "lazyads": {
      "url": "https://mcp.lazyads.ai/mcp",
      "headers": {
        "Authorization": "Bearer la_your_api_key"
      }
    }
  }
}

Cursor Settings → Tools & MCP shows the server and its tools once the file is saved. Use "Bearer ${env:LAZY_ADS_API_KEY}" to keep the key out of the repo.

Claude Desktop

claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\)

{
  "mcpServers": {
    "lazyads": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.lazyads.ai/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer la_your_api_key"
      }
    }
  }
}

Claude Desktop only launches local (stdio) servers and its Connectors UI is OAuth-only, so the mcp-remote bridge forwards to the hosted endpoint. Keep the header value in env (no space around the colon) so Windows does not split the argument. Fully quit and reopen Claude Desktop after saving.

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "lazyads": {
      "serverUrl": "https://mcp.lazyads.ai/mcp",
      "headers": {
        "Authorization": "Bearer la_your_api_key"
      }
    }
  }
}

Windsurf reads remote servers from serverUrl, not url. A block copied from Cursor will be ignored silently. Click Refresh in the Cascade MCP panel after saving.

VS Code (GitHub Copilot)

.vscode/mcp.json (workspace) or MCP: Open User Configuration

{
  "inputs": [
    {
      "type": "promptString",
      "id": "lazyads-api-key",
      "description": "Lazy Ads API key (Settings → API)",
      "password": true
    }
  ],
  "servers": {
    "lazyads": {
      "type": "http",
      "url": "https://mcp.lazyads.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${input:lazyads-api-key}"
      }
    }
  }
}

VS Code uses a servers key (not mcpServers) and requires type. The inputs block prompts each developer for their own key, so the file is safe to commit.

OpenAI Codex CLI

~/.codex/config.toml (or .codex/config.toml in a trusted project)

[mcp_servers.lazyads]
url = "https://mcp.lazyads.ai/mcp"
bearer_token_env_var = "LAZY_ADS_API_KEY"

Export LAZY_ADS_API_KEY in your shell first; Codex sends it as Authorization: Bearer. Equivalent one-liner: codex mcp add lazyads --url https://mcp.lazyads.ai/mcp --bearer-token-env-var LAZY_ADS_API_KEY. The same config is shared with the ChatGPT desktop app and Codex IDE extension.

Gemini CLI

~/.gemini/settings.json (global) or .gemini/settings.json (project)

{
  "mcpServers": {
    "lazyads": {
      "httpUrl": "https://mcp.lazyads.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${LAZY_ADS_API_KEY}"
      }
    }
  }
}

Gemini CLI uses httpUrl for Streamable HTTP (url is the legacy SSE field). Settings resolve $VAR / ${VAR} from your environment. Or run: gemini mcp add --transport http lazyads https://mcp.lazyads.ai/mcp --header "Authorization: Bearer ..."

Hermes Agent

~/.hermes/config.yaml

mcp_servers:
  lazyads:
    url: "https://mcp.lazyads.ai/mcp"
    headers:
      Authorization: "Bearer ${LAZY_ADS_API_KEY}"

Put LAZY_ADS_API_KEY in ~/.hermes/.env; Hermes resolves ${VAR} in config.yaml. Install the Lazy Ads skill too so the agent knows when to reach for each tool. Full guide.

n8n (MCP Client Tool node)

AI Agent → Tools → MCP Client Tool

Endpoint:        https://mcp.lazyads.ai/mcp
Server Transport: HTTP Streamable
Authentication:  Header Auth
  Name:  Authorization
  Value: Bearer la_your_api_key

Create a Header Auth credential once and reuse it across workflows. Pair it with our outbound webhooks to trigger flows when campaigns build or creatives finish. Full guide.

47 tools, bridge + full MCP

Tools marked bridge work on every paid plan including BYOA (33 tools). ai tools require Starter, Growth, Scale, or Enterprise (full suite = 47). Tools marked write change your account or the live platform.

Create and publish (bridge · 7)

create_manual_campaignbridgewrite
Create a campaign from your agent's own strategy on Meta, Google, TikTok, LinkedIn, Reddit, Apple, Bing, ChatGPT, and Snapchat, plus the Lazy Ads record
create_manual_ad_setbridgewrite
Create an ad set / ad group with geo, age, gender, interest, keyword, and custom-audience targeting
create_manual_adbridgewrite
Create a live ad with copy, destination URL, and image or platform creative
create_meta_ad_creativebridgewrite
Build a Meta ad creative from a public image URL plus copy before create_manual_ad
list_platform_audiencesbridge
List Meta or TikTok custom audiences to attach via targeting.customAudienceIds
update_manual_campaignbridgewrite
Update name, objective, daily budget, or end date in Lazy Ads and on the platform
duplicate_campaignbridgewrite
Clone a campaign with its ad sets and ads into a new draft

Import and sync (bridge · 4)

list_live_platform_campaignsbridge
List campaigns directly from a connected ad account, including ones not yet in Lazy Ads
import_platform_campaignbridgewrite
Link an existing live campaign into Lazy Ads so it shows on the unified dashboard
sync_campaign_performancebridgewrite
Pull live metrics for one campaign into performance snapshots (1 to 90 days)
sync_all_campaign_performancebridgewrite
Sync every linked campaign across every connected platform

Manage live campaigns (bridge · 10)

list_campaignsbridge
List Lazy Ads campaigns with status and the latest synced metrics
get_ad_detailsbridge
Full campaign structure: ad sets, ads, copy, and attached creatives
pause_resume_campaignbridgewrite
Pause or resume a campaign on the live platform
pause_resume_ad_setbridgewrite
Pause or resume an ad set / ad group on the live platform
pause_resume_adbridgewrite
Pause or resume a single ad on the live platform
set_campaign_budgetbridgewrite
Change a campaign daily budget in Lazy Ads and on the platform
set_ad_set_budgetbridgewrite
Ad-set daily budget where the platform budgets at that level (Meta ABO, TikTok, LinkedIn, Reddit)
update_ad_set_targetingbridgewrite
Update live audience targeting when the platform API allows it
update_ad_set_bidbridgewrite
Manual bid on LinkedIn, TikTok, ChatGPT, or Snapchat ad groups (null reverts LinkedIn to auto)
add_ad_set_keywordsbridgewrite
Add search keywords with match types to Google, Bing, or Apple ad groups

Analytics (bridge · 5)

get_campaign_performancebridge
Aggregated spend, clicks, conversions, CPA, and ROAS for one or all campaigns over a date range
get_ad_spend_summarybridge
Budget and spend overview by platform and campaign
get_breakdown_databridge
Performance by age, gender, placement, device, country, region, or platform position
get_best_performing_creativebridge
Rank a campaign’s ads by ROAS, conversions, or CTR
compare_campaignsbridge
Head-to-head comparison of two campaigns

Creatives, audiences, and account (bridge · 7)

list_creativesbridge
Browse the creative library with lifetime ROAS/spend and predicted scores
attach_creative_to_adbridgewrite
Assign a library creative to an ad
list_audiencesbridge
Targeting audiences currently used across your ad sets
list_platform_connectionsbridge
Connected ad accounts, status, and granted permissions
connect_chatgpt_adsbridgewrite
Connect ChatGPT Ads with an Ads Manager API key (other platforms connect in the dashboard)
check_platform_billingbridge
Whether an ad account can spend, with a deep link to its billing page
get_recent_notificationsbridge
Recent in-app notifications for your account

Lazy Ads AI (Starter+ · 14)

build_ai_campaignaiwrite
Run the Lazy Ads AI campaign builder with the dashboard options: platforms, budget, objective, creativeMix, preferred creatives, and custom instructions
get_campaign_build_statusai
Poll an AI build for step-by-step progress
set_campaign_automationaiwrite
Toggle Tracking (dashboard + analysis) and Management (optimizer may edit) on a campaign
get_optimization_suggestionsai
AI performance analysis with recommended actions
chat_with_lazy_adsaiwrite
Natural-language chat with the Lazy Ads assistant (can act on your account)
get_creative_scoreai
Predicted performance score for a creative before launch
generate_creativeaiwrite
Generate AI image or video creatives (credits and quota enforced)
get_audience_suggestionsaiwrite
AI targeting suggestions from a plain-language description
list_competitorsai
Tracked competitors with Ad Library data and AI analysis
search_competitor_adsai
Search the Meta Ad Library for a brand or keyword
get_competitor_analysisai
Stored AI analysis for a tracked competitor
scan_competitor_adsaiwrite
Scan a competitor’s live ads and run AI creative analysis
get_ai_activityai
Recent Lazy Ads AI tasks and actions
list_activityai
Searchable activity log: credit charges and campaign, ad set, or ad changes

BYOA bridge workflow

create_manual_campaign with your own objective and budget (LinkedIn maps to a campaign group).
create_manual_ad_set with targeting; attach audiences from list_platform_audiences.
Meta: create_meta_ad_creative then create_manual_ad. Other platforms: create_manual_ad with an imageUrl.
sync_campaign_performance so spend and ROAS land on the unified Lazy Ads dashboard.

MCP questions, answered

What is the Lazy Ads MCP server?

A hosted Model Context Protocol server at https://mcp.lazyads.ai/mcp that lets any MCP client (Claude Code, Cursor, Claude Desktop, Windsurf, VS Code, Codex, Gemini CLI, Hermes) create, monitor, and optimize ad campaigns across Meta, Google, TikTok, LinkedIn, Reddit, Apple, Bing, ChatGPT, and Snapchat through the ad accounts you connected in Lazy Ads.

Which plans include MCP access?

Every paid plan. BYOA gets the 33-tool bridge (your agent supplies strategy and copy; Lazy Ads is the connector and dashboard). Starter, Growth, Scale, and Enterprise get the full 47-tool suite, which adds 14 Lazy Ads AI tools such as build_ai_campaign, chat_with_lazy_ads, and generate_creative. Free accounts cannot create API keys.

How do I authenticate?

Generate an API key under Settings → API in the Lazy Ads dashboard and send it on every request as Authorization: Bearer <key> (X-API-Key is also accepted). The server is stateless, so there is no session handshake to keep alive.

Does the MCP server spend my Lazy Ads AI credits?

Only the Lazy Ads AI tools do (campaign builds, chat, creative generation, competitor scans). Bridge tools never call Lazy Ads AI, which is why BYOA can use them with no AI usage costs on our side.

What are the rate limits?

Per API key, per minute: BYOA 60, Starter 30, Growth 100, Scale 500, Enterprise 1000. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; bursts over the limit return HTTP 429 with Retry-After.

Is there a REST API too?

Yes. Growth, Scale, and Enterprise plans can use the same API key against the REST API at https://lazyads.ai/api/v1 (OpenAPI spec at /api/v1/openapi.json) and register HMAC-signed outbound webhooks. BYOA and Starter keys are MCP-only.

Using Hermes?

We publish a dedicated Hermes skill so Lazy Ads feels native to your agent, including BYOA bridge workflows. Growth+ teams can also use the REST API and webhooks with the same key.