# Adyntel MCP server

## Integrating Adyntel MCP Server with Your Workflows

This guide explains how to connect the Adyntel MCP server to various AI assistants and workflows, enabling you to search and analyze advertising data from Facebook, Google, and LinkedIn directly through conversational AI.

### Overview

The Adyntel MCP server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) to expose our endpoints to AI assistants. Once connected, you can ask your AI assistant to search for competitor ads, analyze creative strategies, and gather advertising insights across platforms.

#### Available Tools

| Tool                  | Description                                                 |
| --------------------- | ----------------------------------------------------------- |
| `search_facebook_ads` | Search Meta/Facebook ads by company page or domain          |
| `search_google_ads`   | Search Google Ads by company domain                         |
| `search_linkedin_ads` | Search LinkedIn sponsored content by company page or domain |

### Prerequisites

Before integrating, you'll need:

1. **Adyntel API credentials** - Your email and API key from [Adyntel](https://adyntel.com)

### Integration Methods

#### Claude Desktop

Add the following to your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "adyntel-ads": {
      "url": "https://mcp.adyntel.com/sse?email=YOUR_EMAIL&api_key=YOUR_API_KEY"
    }
  }
}
```

Replace `YOUR_EMAIL` and `YOUR_API_KEY` with your Adyntel credentials.

**Important:** If your email contains special characters like `+`, you must URL-encode them. For example:

* `user+tag@example.com` → `user%2Btag@example.com`

After saving, restart Claude Desktop. The Adyntel tools will appear in the tools menu.

#### Cursor

Add the MCP server to your Cursor settings:

1. Open Cursor Settings (`Cmd+,` on macOS, `Ctrl+,` on Windows)
2. Navigate to **Features** → **MCP Servers**
3. Click **Add Server** and configure:

```json
{
  "mcpServers": {
    "adyntel-ads": {
      "url": "https://mcp.adyntel.com/sse?email=YOUR_EMAIL&api_key=YOUR_API_KEY"
    }
  }
}
```

#### Claude Code (CLI)

Add the MCP server using the Claude Code CLI:

```bash
claude mcp add --transport sse adyntel-ads "https://mcp.adyntel.com/sse?email=YOUR_EMAIL&api_key=YOUR_API_KEY"
```

This will add the server to your user config at `~/.claude.json`. You can also specify a scope:

* `--scope user` (default) - Available in all your projects
* `--scope project` - Stored in `.mcp.json` at project root, shared with team
* `--scope local` - Private to you, stored in project's `.claude.json`

Alternatively, manually add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "adyntel-ads": {
      "type": "sse",
      "url": "https://mcp.adyntel.com/sse?email=YOUR_EMAIL&api_key=YOUR_API_KEY"
    }
  }
}
```

Verify the connection with:

```bash
claude mcp list
```

#### Other MCP Clients

Any MCP-compatible client can connect using the SSE transport:

* **Endpoint:** `https://mcp.adyntel.com/sse?email=YOUR_EMAIL&api_key=YOUR_API_KEY`
* **Protocol:** MCP v2024-11-05
* **Transport:** SSE (Server-Sent Events)

Alternatively, you can pass credentials via HTTP headers:

* `X-Adyntel-Email`: Your Adyntel account email
* `X-Adyntel-Api-Key`: Your Adyntel API key

### Using the Tools

Once connected, you can interact with the tools through natural language. Your credentials are automatically included from the connection URL, so you don't need to mention them in your prompts.

```
Search for Facebook ads from nike.com
```

### Example Workflows

#### Competitor Analysis

```
1. Search for Facebook ads from my competitor acme.com
2. Search for their Google Ads as well
3. Summarize their messaging strategy and key value propositions
```

#### Ad Creative Research

```
Find all video ads from Nike on Facebook. I want to analyze
their video creative approach.
```

#### Multi-Platform Overview

```
Give me a comprehensive view of Shopify's advertising:
- Their Facebook ads
- Their Google Ads
- Their LinkedIn ads
Summarize the differences in messaging across platforms.
```

### Handling Pagination

For companies with many ads, results are paginated. The response includes a `continuation_token` that you can use to fetch more results:

```
Get more Facebook ads from Nike using continuation token: xyz789
```

### Error Handling

| Error                 | Cause                    | Solution                                |
| --------------------- | ------------------------ | --------------------------------------- |
| Authentication failed | Invalid email or API key | Verify your Adyntel credentials         |
| Insufficient credits  | API credits depleted     | Top up your Adyntel account             |
| Validation error      | Invalid parameters       | Check parameter format and requirements |
| Request timeout       | Slow response from API   | Try again or reduce scope of request    |

### Security Considerations

* **Credentials:** Your API credentials are stored in your MCP client configuration. Never share your configuration file or commit it to version control.
* **Access control:** Use your credentials only in trusted environments.
* **URL parameters:** Credentials in the URL may be logged by some clients. Consider using HTTP headers (`X-Adyntel-Email`, `X-Adyntel-Api-Key`) if your client supports them.

### Troubleshooting

#### Connection Issues

1. Verify the server is accessible at `https://mcp.adyntel.com/sse`
2. Ensure your client supports SSE transport
3. Check for network or firewall restrictions

#### Tool Not Appearing

1. Restart your AI client after configuration changes
2. Verify JSON syntax in configuration file
3. Check client logs for connection errors

#### API Errors

1. Verify your Adyntel credentials are active
2. Check your API credit balance
3. Ensure required parameters are provided

#### Authentication Failed (401 Error)

If you're getting authentication errors despite having correct credentials:

1. **Check URL encoding** - Special characters in your email must be URL-encoded:
   * `+` → `%2B`
   * `@` → `%40` (though `@` usually works without encoding)
   * `&` → `%26`
2. **Example:** If your email is `user+test@example.com`, use:

   ```
   email=user%2Btest@example.com
   ```

### Support

* **Adyntel API:** Contact <hello@adyntel.com>