Quick start

Wire Claude Code (or any MCP-compatible client) to Adlyse in under a minute.

Fast path: npx adlyse-mcp#

For Claude Code, Claude Desktop, Cursor, or Windsurf, one command does the whole job — no API key to copy:

npx adlyse-mcp

It detects which of those clients you have installed, writes the right config entry for each (native remote HTTP for Claude Code/Cursor, an mcp-remote bridge for Claude Desktop/Windsurf), and backs up any existing config first. On first connect the client sends you to your browser to sign in — Adlyse issues an OAuth token scoped to your organization automatically.

npx adlyse-mcp --client claude-code   # skip the interactive picker
npx adlyse-mcp --client all --yes     # install everywhere detected, no prompts
npx adlyse-mcp --scope ads            # only the /mcp/ads/ endpoint (default: all)

Restart the client and you’re done. See the package README for the full flag list and exactly what gets written per client.

Reach for the manual setup below if you’re on a client adlyse-mcp doesn’t support yet (e.g. ChatGPT Desktop or a custom MCP host), you want a static API key instead of OAuth, or you want to see exactly what’s being configured.

1. Create an API key#

Go to Admin → API Keys and click Create API Key. Copy the mii_prod_... value — you only see it once. See Authentication for the alternatives (OAuth) and API Keys for the full lifecycle.

2. Add the servers#

How you register a remote MCP server depends on the client.

Claude Code#

Claude Code speaks remote HTTP MCP natively. The quickest path is the CLI:

claude mcp add --transport http --scope user adlyse-insights \
  https://mcp.adlyse.com/mcp/insights/ \
  --header "Authorization: Bearer mii_prod_xxx"

Repeat for reports, ads, and workflows. The workflows server includes agents, skills, schedules, tables, and institutional memory. Add admin only when you need organization or sub-organization information. Or edit the config directly — user scope lives in ~/.claude.json, project scope in a .mcp.json at your repo root. Note the required "type": "http":

{
  "mcpServers": {
    "adlyse-insights": {
      "type": "http",
      "url": "https://mcp.adlyse.com/mcp/insights/",
      "headers": { "Authorization": "Bearer mii_prod_xxx" }
    },
    "adlyse-reports": {
      "type": "http",
      "url": "https://mcp.adlyse.com/mcp/reports/",
      "headers": { "Authorization": "Bearer mii_prod_xxx" }
    },
    "adlyse-ads": {
      "type": "http",
      "url": "https://mcp.adlyse.com/mcp/ads/",
      "headers": { "Authorization": "Bearer mii_prod_xxx" }
    },
    "adlyse-workflows": {
      "type": "http",
      "url": "https://mcp.adlyse.com/mcp/workflows/",
      "headers": { "Authorization": "Bearer mii_prod_xxx" }
    },
    "adlyse-admin": {
      "type": "http",
      "url": "https://mcp.adlyse.com/mcp/admin/",
      "headers": { "Authorization": "Bearer mii_prod_xxx" }
    }
  }
}

Claude Desktop#

You have two options.

Option A — OAuth (recommended, no API key). Settings → Connectors → Add custom connector, give it a name, and paste the Remote MCP server URL (e.g. https://mcp.adlyse.com/mcp/insights/). Leave the OAuth Client ID/Secret fields blank — Adlyse self-registers the client — then click Add and complete the browser login. Repeat for reports, ads, and workflows; add admin only when the connector needs organization or sub-organization information. Tokens refresh automatically, so there’s nothing to rotate. (This works because the MCP host advertises its authorization server and challenges unauthenticated requests; see Authentication.)

Option B — API key via mcp-remote. Best when you’d rather use a static mii_prod_ key, or for clients without an OAuth UI. Claude Desktop’s claude_desktop_config.json only supports local (stdio) servers — paste the url+headers form above and it silently skips every entry (“not valid MCP server configurations”). Bridge each remote server through mcp-remote instead (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "adlyse-insights": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.adlyse.com/mcp/insights/", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer mii_prod_xxx" }
    },
    "adlyse-reports": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.adlyse.com/mcp/reports/", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer mii_prod_xxx" }
    },
    "adlyse-ads": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.adlyse.com/mcp/ads/", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer mii_prod_xxx" }
    },
    "adlyse-workflows": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.adlyse.com/mcp/workflows/", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer mii_prod_xxx" }
    },
    "adlyse-admin": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.adlyse.com/mcp/admin/", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer mii_prod_xxx" }
    }
  }
}

The token goes in env (not inline in args) on purpose: it dodges a Claude Desktop bug that mangles spaces inside an arg, so the --header value has no space around the :. Requires Node.js (npx) on your PATH; the first launch downloads mcp-remote, so the servers take a few extra seconds to appear.

Desktop’s “Add custom connector” UI is OAuth-only — it has no field for an API key, so the mcp-remote bridge is the way to use a mii_prod_ key there. See Authentication for the current state of OAuth discovery.

You don’t need every scoped server enabled. The default npx adlyse-mcp installation uses /mcp/all/, which combines insights, ads, reports, workflows, agents, skills, and institutional memory. adlyse-admin stays separate because it exposes organization hierarchy information.

3. Restart your client#

Tools auto-complete from there. Try:

adlyse-insights.list_ad_accounts

If you get auth_error, double-check the bearer token and that the key hasn’t been revoked.

Local development#

If you’re developing against a local Adlyse server, swap the host:

https://mcp.adlyse.com  →  http://localhost:8766

Start the local MCP host with ./start-mcp.sh from server/.

Example workflows#

”What should I pause today?"#

adlyse-insights.list_ad_accounts
adlyse-insights.get_dashboard_snapshot(ad_account_id=...)
adlyse-ads.list_campaigns(ad_account_id=..., status="enabled")
adlyse-ads.get_performance(..., group_by="campaign")
adlyse-ads.update_campaign_status(..., status="paused", preview=true)   # review diff
adlyse-ads.update_campaign_status(..., preview=false)                   # apply; decision logged

"Send me this week’s executive summary"#

adlyse-insights.list_ad_accounts
adlyse-reports.generate_report(template_key="weekly_check_in", ad_account_ids=[...], ...)
adlyse-reports.get_report(report_id)    # polls until status="ready" → pdf_url

"Draft three on-brand headlines for our top-fatigued ad”#

adlyse-insights.get_guideline(slug="brand")
adlyse-insights.get_guideline(slug="meta")
adlyse-ads.list_ads(ad_account_id=..., status="enabled")
adlyse-ads.get_ad_performance(..., ad_id=...)    # find fatigued

Install the builder skills#

Adlyse ships two system skills that teach Claude how to build on the platform — agent_builder (create and schedule an AI colleague) and workflow_builder (author a node-graph workflow). They read the same in the Adlyse chat and in an external client, and each is exportable as an Anthropic Agent Skills bundle:

1. Open /adlyse/skills in the Adlyse dashboard, find agent_builder or workflow_builder, and click Export — it downloads a zip holding <skill>/SKILL.md.
2. Unzip it into ~/.claude/skills/ (Claude Code), or upload the zip to claude.ai under Settings → Capabilities → Skills.
3. Connect the server each skill’s Prerequisites section lists: https://mcp.adlyse.com/mcp/workflows/ for both builders (see step 2 above).

Then ask Claude to “build me a colleague who checks pacing every weekday” or “turn this into a workflow” and it follows the same playbook the dashboard agent uses. The skill’s last section lists the few tool names that differ between chat and MCP (e.g. configure_assistant in chat is update_assistant on /mcp/workflows/).

Next steps#

• Authentication — API keys vs. OAuth
• adlyse-insights — ABI, waste, safe-budget, decisions, guidelines
• adlyse-ads — cross-platform campaign & ad reads, gated writes
• adlyse-reports — generate and fetch PDF reports
• adlyse-workflows — workflows, agents, skills, schedules, tables, and memory
• adlyse-admin — organization and sub-organization information