Setting Up Your MCP Client

This page walks you through connecting your AI assistant to AdAdvisor’s MCP server. Pick your client below and follow the instructions.

Prerequisites

Before you start, make sure you have:

An AdAdvisor account with at least one connected Meta ad account. Sign up here if you haven’t already.
An MCP-compatible AI client installed (see the tabs below for supported clients).
An API key (optional). OAuth is the default and recommended auth method. If you prefer API key auth, create one in Settings > MCP Server before starting. See Managing API Keys for details.

MCP server URL

All clients connect to the same server:

https://api.adadvisor.ai/mcp

Authentication

AdAdvisor supports two authentication methods:

OAuth (recommended): Your client opens a browser window where you log in to AdAdvisor. The token is issued and refreshed automatically. No key management needed.
API Key: Pass a key in the Authorization header. Useful for headless setups, CI/CD pipelines, or clients that don’t support OAuth.

Both methods grant the same level of access. See What is the MCP Server? for more details on how auth works.

Client setup

Claude Code runs in the terminal and supports both OAuth and API key authentication.Option 1: OAuth (recommended)Run this command to add the server globally (available in all projects):

claude mcp add adadvisor \
  --transport http \
  --scope user \
  https://api.adadvisor.ai/mcp

The next time you start a conversation and a tool from AdAdvisor is used, Claude Code will open your browser so you can log in. After that, you’re all set.To add the server for only the current project, omit --scope user:

claude mcp add adadvisor \
  --transport http \
  https://api.adadvisor.ai/mcp

You can verify the server is connected by running:

claude mcp list

Option 2: API KeyIf you prefer using an API key, run:

claude mcp add adadvisor \
  --transport http \
  https://api.adadvisor.ai/mcp \
  -- --header "Authorization: Bearer YOUR_API_KEY"

Or add it to your .mcp.json file in your project root:

.mcp.json

{
  "mcpServers": {
    "adadvisor": {
      "type": "http",
      "url": "https://api.adadvisor.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop supports MCP servers through its Connectors UI.

Open Settings > Connectors
Click Add Connector
Enter the server URL: https://api.adadvisor.ai/mcp
Claude Desktop will open your browser to log in to AdAdvisor via OAuth

That’s it. No API key needed.

Connectors are available on Claude Pro, Max, Team, and Enterprise plans.

ChatGPT supports MCP servers through its Apps settings (previously called Connectors).

Go to Settings > Apps & Connectors > Advanced and turn on Developer Mode
Go back to Settings > Apps & Connectors and click Create
Enter a name (e.g., “AdAdvisor”) and the server URL: https://api.adadvisor.ai/mcp
ChatGPT will handle the OAuth login flow through your browser

Available on ChatGPT Pro, Plus, Team, Enterprise, and Edu plans.

You can add the server through the Command Palette or by editing the config file directly.Method 1: Command Palette

Open the Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows/Linux)
Run Cursor Settings: Open MCP Settings
Add the AdAdvisor server configuration (see JSON below)

Method 2: Edit config fileAdd the following to .cursor/mcp.json in your project root, or ~/.cursor/mcp.json for global access:With OAuth:

.cursor/mcp.json

{
  "mcpServers": {
    "adadvisor": {
      "type": "streamableHttp",
      "url": "https://api.adadvisor.ai/mcp"
    }
  }
}

Cursor will open your browser to log in when the server requires authentication.With API Key:

.cursor/mcp.json

{
  "mcpServers": {
    "adadvisor": {
      "type": "streamableHttp",
      "url": "https://api.adadvisor.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

If OAuth tokens expire and tools stop working, open the Command Palette and run Cursor: Clear All MCP Tokens, then reconnect.

You can add the server through the Command Palette or by editing the config file directly.Method 1: Command Palette

Open the Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows/Linux)
Run MCP: Open User Configuration
Add the AdAdvisor server configuration (see JSON below)

Method 2: Edit config fileAdd the following to .vscode/mcp.json in your project root:With OAuth:

.vscode/mcp.json

{
  "servers": {
    "adadvisor": {
      "type": "http",
      "url": "https://api.adadvisor.ai/mcp"
    }
  }
}

VS Code will show an “Auth” button above the server definition. Click it to log in through your browser.With API Key:

.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "adadvisor-key",
      "description": "AdAdvisor API Key",
      "password": true
    }
  ],
  "servers": {
    "adadvisor": {
      "type": "http",
      "url": "https://api.adadvisor.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${input:adadvisor-key}"
      }
    }
  }
}

VS Code will prompt you for the key securely when the server connects. The key is never stored in plaintext in your config file.

Requires VS Code 1.101 or later with GitHub Copilot.

If OAuth tokens expire, open the Command Palette and run Authentication: Remove Dynamic Authentication Providers, then reconnect.

Add the following to your ~/.gemini/settings.json file (or .gemini/settings.json in your project root):With OAuth:

settings.json

{
  "mcpServers": {
    "adadvisor": {
      "httpUrl": "https://api.adadvisor.ai/mcp"
    }
  }
}

Gemini CLI will detect that the server requires authentication and open your browser to log in.With API Key:

settings.json

{
  "mcpServers": {
    "adadvisor": {
      "httpUrl": "https://api.adadvisor.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

OpenAI’s Codex CLI uses a TOML config file.With OAuth:Add to your ~/.codex/config.toml:

config.toml

[mcp_servers.adadvisor]
url = "https://api.adadvisor.ai/mcp"

Then run codex mcp login adadvisor to complete the browser login.With API Key:

config.toml

[mcp_servers.adadvisor]
url = "https://api.adadvisor.ai/mcp"
bearer_token_env_var = "ADADVISOR_API_KEY"

Set the environment variable before running Codex:

export ADADVISOR_API_KEY="your-api-key-here"

Add the following to your Windsurf MCP config file:

macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

With OAuth:

mcp_config.json

{
  "mcpServers": {
    "adadvisor": {
      "serverUrl": "https://api.adadvisor.ai/mcp"
    }
  }
}

Windsurf will open your browser to log in the first time you use it.With API Key:

mcp_config.json

{
  "mcpServers": {
    "adadvisor": {
      "serverUrl": "https://api.adadvisor.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ADADVISOR_API_KEY}"
      }
    }
  }
}

Set the environment variable before launching Windsurf:

export ADADVISOR_API_KEY="your-api-key-here"

Any MCP-compatible client that supports remote HTTP servers should work. Use these values:

Setting	Value
Server URL	`https://api.adadvisor.ai/mcp`
Transport	HTTP (Streamable HTTP)
Auth	OAuth 2.0 or Bearer token via `Authorization` header

Using mcp-remote for legacy clientsIf your client doesn’t natively support remote HTTP MCP servers (only supports stdio), you can use mcp-remote as a bridge:

{
  "mcpServers": {
    "adadvisor": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.adadvisor.ai/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

This runs a local proxy that translates between stdio and HTTP, so older clients can connect to the remote server.

Verifying the connection

After adding the server, try asking your AI assistant something about your ad data. For example:

What campaigns are currently running in my ad account?

Show me my top performing ad sets by ROAS this month.

What's my average CPC across all active campaigns?

If everything is set up correctly, the assistant will connect to AdAdvisor, pull your data, and return results grounded in your actual campaign performance.

Troubleshooting

Authentication errors (401 Unauthorized)

If using API key auth:

Verify the key hasn’t been revoked or expired in Settings > MCP Server
Make sure the Authorization header format is exactly Bearer YOUR_API_KEY (with a space after “Bearer”)
Create a new key if needed. See Managing API Keys

If using OAuth:

OAuth sessions can expire. Re-authenticate by triggering a new connection from your client:
- Claude Code: Remove and re-add the server with claude mcp remove adadvisor then re-run the add command
- Cursor: Open Command Palette > Cursor: Clear All MCP Tokens, then restart
- VS Code: Open Command Palette > Authentication: Remove Dynamic Authentication Providers, then restart
- Other clients: Remove the server entry from your config, restart the client, and re-add it

Server not appearing or tools not loading

Double-check the URL is exactly https://api.adadvisor.ai/mcp (no trailing slash, no typos)
Restart your client after editing the config file. Most clients don’t hot-reload MCP config changes.
Make sure you’re editing the correct config file for your client (project-level vs global)
For Cursor and VS Code, check that the JSON is valid. A missing comma or bracket will silently fail.

No data returned

Verify your Meta ad account is connected in AdAdvisor and the initial data sync has completed. Check Settings > Connected Accounts.
Make sure the business you’re querying has active campaigns with data in the date range you’re asking about.

Connection timeout

If you’re behind a corporate firewall or VPN, make sure outbound HTTPS connections to api.adadvisor.ai aren’t blocked.
Try the mcp-remote proxy method (see the “Other clients” tab above) if your client has trouble with direct HTTP connections.

Security best practices

Use OAuth when possible. It’s more secure than static API keys and handles token rotation automatically.
One API key per client. If a key is compromised, you only need to revoke and replace that one without affecting other tools.
Set expiration dates on API keys for shared machines or temporary setups.
Don’t commit keys to git. Use environment variables or your client’s secure input mechanism (like VS Code’s promptString input) instead of hardcoding keys in config files.

Finding the setup instructions in AdAdvisor

You can also find these instructions directly in the app. Go to Settings > MCP Server and scroll down to the “Quick Start” section. Select your client from the dropdown and the instructions (with code blocks you can copy) will appear.

Overview

Get Connected

Capabilities

Setting Up Your MCP Client

Prerequisites

MCP server URL

Authentication

Client setup

Verifying the connection

Troubleshooting

Authentication errors (401 Unauthorized)

Server not appearing or tools not loading

No data returned

Connection timeout

Security best practices

Finding the setup instructions in AdAdvisor

Overview

Get Connected

Capabilities

​Prerequisites

​MCP server URL

​Authentication

​Client setup

​Verifying the connection

​Troubleshooting

​Authentication errors (401 Unauthorized)

​Server not appearing or tools not loading

​No data returned

​Connection timeout

​Security best practices

​Finding the setup instructions in AdAdvisor

Prerequisites

MCP server URL

Authentication

Client setup

Verifying the connection

Troubleshooting

Authentication errors (401 Unauthorized)

Server not appearing or tools not loading

No data returned

Connection timeout

Security best practices

Finding the setup instructions in AdAdvisor