> ## Documentation Index
> Fetch the complete documentation index at: https://adadvisor.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting Up Your MCP Client

> Step-by-step setup instructions for connecting Claude Code, Claude Desktop, ChatGPT, and other MCP-compatible AI clients to AdAdvisor's MCP server.

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:

1. **An AdAdvisor account** with at least one connected Meta ad account. [Sign up here](https://app.adadvisor.ai) if you haven't already.
2. **An MCP-compatible AI client** installed (see the tabs below for supported clients).
3. **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](https://adadvisor.ai/docs/ai/managing-api-keys.md) 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?](https://adadvisor.ai/docs/ai/what-is-mcp-server.md) for more details on how auth works.

## Client setup

> [tab] Claude Desktop
>
> Claude Desktop supports MCP servers through its Connectors UI. No API key needed.
>
> **1. Open Customize**
>
> Open Claude Desktop and click **Customize** in the sidebar.
>
> ![Customize option in the Claude Desktop sidebar](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/claude-desktop-mcp/claude-desktop-mcp-step-1.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=66904fcd9ff8490d3cc3399caab4fee6)
>
> **2. Open Connectors**
>
> Select **Connectors** from the Customize menu.
>
> ![Connectors option in the Customize menu](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/claude-desktop-mcp/claude-desktop-mcp-step-2.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=bd335e323bf7991e918bcef63ca828bf)
>
> **3. Add custom connector**
>
> Click the **+** icon and choose **Add custom connector**.
>
> ![Add custom connector menu](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/claude-desktop-mcp/claude-desktop-mcp-step-3.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=e5bb1d0d311ad89169f42c9c2b1a6537)
>
> **4. Enter the MCP URL**
>
> Name it **AdAdvisor**, paste `https://api.adadvisor.ai/mcp`, and click **Add**.
>
> ![Connector form with name and URL filled in](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/claude-desktop-mcp/claude-desktop-mcp-step-4.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=bed0c8edbba535c5fa6ab6c38d16954b)
>
> **5. Connect**
>
> Click **Connect** on the AdAdvisor row to start authorization.
>
> ![AdAdvisor row with Connect button](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/claude-desktop-mcp/claude-desktop-mcp-step-5.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=29e96613793f242930186375b74d6830)
>
> **6. Authorize**
>
> Sign in to AdAdvisor and click **Authorize Claude** to grant access.
>
> ![AdAdvisor OAuth consent screen for Claude Desktop](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/claude-desktop-mcp/claude-desktop-mcp-step-6.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=42dd552ce587bccd9cc6cf3fa51fe441)
>
> **7. Done**
>
> Review the tool permissions and start chatting. AdAdvisor is connected.
>
> ![Tool permissions screen with AdAdvisor connected](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/claude-desktop-mcp/claude-desktop-mcp-step-7.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=06e960f6ba353110986009328db299c9)
>
> > [!NOTE]
> >
> > Connectors are available on Claude Pro, Max, Team, and Enterprise plans.

> [tab] ChatGPT
>
> ChatGPT supports MCP servers through its Apps & Connectors settings.
>
> **1. Open Settings**
>
> Open ChatGPT, click your avatar, and choose **Settings**.
>
> ![ChatGPT avatar dropdown with Settings option](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/chatgpt-mcp/chatgpt-desktop-1.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=588bf8bd8d81b3cbd167e028978cfab2)
>
> **2. Open Advanced settings**
>
> Open the **Apps & Connectors** tab and click **Advanced settings**.
>
> ![Apps tab with Advanced settings link](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/chatgpt-mcp/chatgpt-desktop-2.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=245c7d70f9ee1fca39534f1d3efc59cd)
>
> **3. Enable Developer mode**
>
> Turn on **Developer mode**, then click **Create**.
>
> ![Developer mode toggle and Create app button](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/chatgpt-mcp/chatgpt-desktop-3.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=ae8e5379b5bbc499ab3bf7d0db219477)
>
> **4. Configure the connector**
>
> Name it **AdAdvisor**, paste `https://api.adadvisor.ai/mcp` as the MCP URL, accept the safety warning, and click **Create**.
>
> ![Create connector form with name and URL filled in](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/chatgpt-mcp/chatgpt-desktop-4.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=831af486b86e06a335e27a5257078f89)
>
> **5. Authorize**
>
> Sign in to AdAdvisor and click **Authorize ChatGPT** to grant access.
>
> ![AdAdvisor OAuth consent screen for ChatGPT](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/chatgpt-mcp/chatgpt-desktop-5.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=058ae387514c480f90ab2734afb6063e)
>
> **6. Done**
>
> AdAdvisor is connected. Open the connector menu in any chat to use AdAdvisor tools.
>
> ![Connected AdAdvisor app overview in ChatGPT](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/chatgpt-mcp/chatgpt-desktop-6.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=9654c4245b43bb8d812c24dcc49e0ecc)
>
> > [!NOTE]
> >
> > Available on ChatGPT Pro, Plus, Team, Enterprise, and Edu plans.

> [tab] Claude Code
>
> Claude Code runs in the terminal and supports both OAuth and API key authentication.
>
> **Option 1: OAuth (recommended)**
>
> **1. Register the server**
>
> Run this command to add AdAdvisor as an MCP server. Use `--scope user` to make it available across all projects, or omit it to add for the current project only.
>
> ```bash theme={null}
> claude mcp add adadvisor \
>   --transport http \
>   --scope user \
>   https://api.adadvisor.ai/mcp
> ```
>
> **2. List MCP servers**
>
> Run `/mcp` inside Claude Code (or `claude mcp list` in your terminal). The `adadvisor` server will appear, marked as **needs authentication**.
>
> ![Claude Code /mcp output showing the adadvisor server listed](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/claude-code-mcp/claudecode-mcp-1.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=c52ad7d59acb21f911fa2880b5b90b50)
>
> **3. Authenticate**
>
> Select the `adadvisor` server and choose **Authenticate**. Claude Code will open your browser to AdAdvisor's OAuth page.
>
> ![AdAdvisor MCP server detail with the Authenticate option highlighted](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/claude-code-mcp/claudecode-mcp-2.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=3bcca5f6b028b850c1da15a823b9b3ce)
>
> **4. Authorize in browser**
>
> Sign in to AdAdvisor and click **Authorize Claude Code (adadvisor)** to grant read access to your campaign data.
>
> ![AdAdvisor OAuth consent screen for Claude Code](https://mintcdn.com/adadvisor/rW9M82bhvFj68KWZ/images/screenshots/claude-code-mcp/claudecode-mcp-3.png?fit=max\&auto=format\&n=rW9M82bhvFj68KWZ\&q=85\&s=d298a9227e7de757236f687f7e7e307c)
>
> **Option 2: API Key**
>
> If you prefer using an API key, run:
>
> ```bash theme={null}
> 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:
>
> ```json .mcp.json theme={null}
> {
>   "mcpServers": {
>     "adadvisor": {
>       "type": "http",
>       "url": "https://api.adadvisor.ai/mcp",
>       "headers": {
>         "Authorization": "Bearer YOUR_API_KEY"
>       }
>     }
>   }
> }
> ```

> [tab] Other clients
>
> 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 clients**
>
> If your client doesn't natively support remote HTTP MCP servers (only supports stdio), you can use `mcp-remote` as a bridge:
>
> ```json theme={null}
> {
>   "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](https://adadvisor.ai/docs/ai/managing-api-keys.md)

**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
  * **Claude Desktop / ChatGPT**: Open the connector settings, disconnect AdAdvisor, then reconnect
  * **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)
* If your client uses a JSON config file, 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 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.

![MCP quick start](https://mintcdn.com/adadvisor/kiWqxDWUg7mkBBTE/images/screenshots/mcp-quick-start.png?fit=max\&auto=format\&n=kiWqxDWUg7mkBBTE\&q=85\&s=7354a35523ea0c528485c90dfedea307)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.