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

# MCP Connector

> Pull your ChatAds widget usage, conversations, and click data into Claude or any MCP client

## Overview

The MCP connector is a **read-only** MCP server for your ChatAds widget data - usage, conversation transcripts, and inline-link clicks. It makes no changes to your account: no settings, no keys, no billing. Point any MCP-compatible client (Claude, Cursor, etc.) at it and ask questions about your widget's performance in plain language.

## Get Your Key

The connector authenticates with your **personal User Key** (`uk_...`), not a team API key.

1. Log into [app.getchatads.com](https://app.getchatads.com)
2. Open **Account**
3. In the **User Key** card, click **Create User Key** (or **Show** if you already have one)

<Note>
  If you created your User Key before this feature launched, reveal it once (or reset it) on the Account page - that's what registers it for MCP lookups. New keys work immediately.
</Note>

## Connect

Add the connector to your MCP client's configuration:

```json theme={null}
{
  "mcpServers": {
    "chatads-widget": {
      "url": "https://api.getchatads.com/mcp/mcp",
      "transport": "http",
      "headers": {
        "x-api-key": "uk_your_user_key"
      }
    }
  }
}
```

Restart your MCP client and it's ready to go.

## Tools

| Tool                           | Params                                                                      | What it returns                                                                                               |
| ------------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `chatads_widget_usage`         | `start_date`, `end_date` (`YYYY-MM-DD`, default: last 30 days ending today) | Daily message/page-load/click counts for the range, plus your widget plan tier and daily chat limit           |
| `chatads_widget_conversations` | `limit` (default 100, max 1000)                                             | Recent chat transcripts, grouped by session, newest first                                                     |
| `chatads_widget_clicks`        | `limit` (default 200, max 10000)                                            | Inline affiliate-link click events from the last 90 days, with a `source` label (Amazon, Skimlinks, CJ, etc.) |

All three also accept an optional `team_id` parameter - you only need to pass it if your account belongs to more than one team. If you do, the tool tells you your team IDs and names so you can pick one.

## Limits

* A per-user rate limit applies across all three tools, separate from any team's ChatAds plan limits.
* Conversations and clicks are retained 90 days (the same purge schedule as the dashboard).
* Data mirrors what you'd see in the dashboard's **Conversations** tab and **Click Log Export** - this connector doesn't compute anything new, it just makes that data queryable from your MCP client.

## Troubleshooting

### "Widget data tools require a uk\_ user key"

You connected with a team API key (`cak_...`). The widget-data tools only accept a personal User Key (`uk_...`) - create one on the [Account page](https://app.getchatads.com/account).

### "Your account belongs to multiple teams"

Pass the `team_id` from the error message as an argument to the tool call.

### Tool not appearing in your MCP client

1. Verify the URL is exactly: `https://api.getchatads.com/mcp/mcp`
2. Check that `transport` is set to `"http"`
3. Restart your MCP client completely
4. Ask: "What tools do you have access to?"