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

# Analytics MCP Server

> Connect your AI agents to Topsort's advertising platform for real-time analytics and catalog operations

The **Model Context Protocol (MCP)** is an open standard for connecting AI applications to external systems—think of it as a USB-C port for AI. Our Analytics MCP server gives your AI assistants direct access to Topsort's advertising analytics and catalog APIs.

<Note>
  Looking for documentation access instead? Check out our [Documentation MCP Server](/api/mcp) for AI-assisted API integration guidance.
</Note>

## What You Can Do

By connecting to Topsort's Analytics MCP server, AI assistants can:

* **Analyze advertising performance** - Query real-time metrics like CTR, CVR, ROAS, CPC, and ad spend across campaigns or marketplaces
* **Monitor campaign health** - Check budget utilization, bidding behavior, quality scores, and pacing in real-time
* **Compare performance over time** - Run week-over-week, month-over-month, or custom period comparisons to identify trends and anomalies
* **Benchmark against industry** - Compare campaign metrics against category benchmarks (retail, pharmacy, travel, etc.)
* **Visualize insights** - Generate line, bar, and pie charts from any analytics data for easy interpretation
* **Get Topsort guidance** - Answer questions about API integration, troubleshooting, and platform best practices

All queries can be scoped to a specific vendor, ensuring advertisers only access their own data while marketplace operators can view aggregate insights.

## Quick Start

Our Analytics MCP server is available at:

```
https://mcp-server.api.topsort.ai/mcp
```

<Warning>
  This MCP server requires authentication. Contact your Topsort sales representative to request an API key with MCP Server access.
</Warning>

## Authentication

### Marketplace Authentication

All requests must include a valid API key. For MCP clients that use `mcp-remote` (like Claude Desktop), pass the key via the `--header` argument:

```json theme={null}
{
  "mcpServers": {
    "topsort-analytics": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-server.api.topsort.ai/mcp",
        "--header",
        "X-API-Key: MPS_xxxx"
      ]
    }
  }
}
```

### Vendor ID Filtering

Tool results can be filtered for specific vendors by including the Vendor ID in the request header. This restricts the scope of all tools, preventing data leakage across vendors:

```json theme={null}
{
  "mcpServers": {
    "topsort-analytics": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-server.api.topsort.ai/mcp",
        "--header",
        "X-API-Key: MPS_xxxx",
        "--header",
        "X-Vendor-Id: 1111-2222-3333-4444-55555"
      ]
    }
  }
}
```

## Tool Filtering

Tags enable fine-grained access control over which tools are available to different clients. Each tool can be annotated with one or more tags, and clients are assigned their own set of tags.

When retrieving tools, the system filters the list by checking for any overlap between the client's tags and each tool's required tags—a client only needs one matching tag to gain access.

## Integration Guides

<CardGroup cols={3}>
  <Card title="ChatGPT" icon="message" href="#chatgpt">
    Connect ChatGPT to Topsort analytics
  </Card>

  <Card title="Claude Desktop" icon="desktop" href="#claude-desktop">
    Configure Claude Desktop with authentication
  </Card>

  <Card title="Postman" icon="paper-plane" href="#postman">
    Test the MCP server with Postman
  </Card>
</CardGroup>

## ChatGPT

ChatGPT supports remote MCP servers for Plus and Team subscribers.

<Steps>
  <Step title="Open ChatGPT Settings">
    Navigate to [chat.openai.com](https://chat.openai.com) and click your profile icon, then select **Settings**.
  </Step>

  <Step title="Access Connections">
    Click on **Connections** or **Integrations** in the settings sidebar.
  </Step>

  <Step title="Add MCP Server">
    Click **Add Connection** and enter:

    * **Name**: `Topsort Analytics`
    * **Server URL**: `https://mcp-server.api.topsort.ai/mcp`
    * **Transport Type**: `http`
    * **Headers**: Add `X-API-Key` with your API key
  </Step>
</Steps>

## Claude Desktop

Claude Desktop provides comprehensive local MCP support.

### Prerequisites

* **Node.js** installed on your system (required for `mcp-remote`)

### Configuration

<Steps>
  <Step title="Open Claude Desktop Settings">
    * **macOS**: Click **Claude** in the menu bar → **Settings**
    * **Windows**: Click **File** → **Settings**
  </Step>

  <Step title="Navigate to Developer Tab">
    Click on the **Developer** tab in the left sidebar.
  </Step>

  <Step title="Edit MCP Configuration">
    Click **Edit Config** and add:

    ```json theme={null}
    {
      "mcpServers": {
        "topsort-analytics": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://mcp-server.api.topsort.ai/mcp",
            "--header",
            "X-API-Key: MPS_xxxx"
          ]
        }
      }
    }
    ```

    Replace `MPS_xxxx` with your actual API key.

    For vendor-scoped access, add an additional `--header` argument:

    ```json theme={null}
    {
      "mcpServers": {
        "topsort-analytics": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://mcp-server.api.topsort.ai/mcp",
            "--header",
            "X-API-Key: MPS_xxxx",
            "--header",
            "X-Vendor-Id: 1111-2222-3333-4444-55555"
          ]
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Claude Desktop">
    Save the configuration and restart Claude Desktop.
  </Step>
</Steps>

## Postman

You can test the Analytics MCP server using Postman's MCP support.

<Steps>
  <Step title="Open Postman">
    Launch Postman and navigate to **Settings** → **MCP Servers**.
  </Step>

  <Step title="Add New Server">
    Click **Add Server** and configure:

    * **Name**: `Topsort Analytics`
    * **URL**: `https://mcp-server.api.topsort.ai/mcp`
  </Step>

  <Step title="Configure Headers">
    Add the required headers:

    * `X-API-Key`: Your Topsort API key
    * `X-Vendor-Id`: (Optional) Vendor ID for scoped access
  </Step>

  <Step title="Test Connection">
    Click **Test Connection** to verify the server is responding correctly.
  </Step>
</Steps>

## Troubleshooting

### Connection Issues

* Verify the URL is correct: `https://mcp-server.api.topsort.ai/mcp`
* Ensure your API key is valid and has MCP Server access
* Check your internet connection
* Restart your MCP client application

### Authentication Errors

* Confirm your API key starts with `MPS_`
* Verify the `X-API-Key` header is correctly formatted
* Contact your Topsort sales representative if your key is rejected

### Server Not Responding

* Verify the transport type is set to `http`
* Check if your firewall or VPN is blocking the connection
* Check [our status page](https://status.topsort.com) for any service disruptions

## Learn More

* [Model Context Protocol Documentation](https://modelcontextprotocol.io)
* [MCP Client List](https://modelcontextprotocol.io/clients)
* [Topsort API Documentation](/api-reference)
* [Documentation MCP Server](/api/mcp) - For AI-assisted API integration