> ## 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 Server
> Connect AI assistants directly to ChatAds via Model Context Protocol
## Overview
ChatAds provides a **native MCP server** that runs on our infrastructure. No local installation required - just point your MCP client directly to our endpoint.
## Quick Start
Add ChatAds to your MCP client's configuration. The location varies by client:
Add to your user config at `~/.claude.json` under the `mcpServers` key:
Edit your Claude Desktop config:
* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
* Windows: `%APPDATA%\Claude\claude_desktop_config.json`
* Linux: `~/.config/Claude/claude_desktop_config.json`
Settings → Features → MCP Servers → Add Server
Check your MCP client's documentation for config location. Most clients use a similar JSON format.
```json theme={null}
{
"mcpServers": {
"chatads": {
"url": "https://api.getchatads.com/mcp/mcp",
"transport": "http",
"headers": {
"x-api-key": "cak_your_api_key"
}
}
}
}
```
Restart your MCP client and you're ready to go.
## Benefits
* **No installation** - Works immediately, no Python or dependencies
* **Always up-to-date** - Server updates apply automatically
* **Team-friendly** - Centralized configuration, consistent behavior
* **Cross-platform** - Works with any MCP-compatible client
***
## Technical Details
### Endpoint
```
POST https://api.getchatads.com/mcp/mcp
```
### Transport
The native server uses **MCP Streamable HTTP** transport, which:
* Runs stateless — no session initialization required
* Returns responses as Server-Sent Events (SSE)
### Authentication
All requests require the `x-api-key` header with your ChatAds API key.
***
## Direct API Usage
You can also interact with the MCP endpoint programmatically using JSON-RPC 2.0.
### Required Headers
```
Content-Type: application/json
Accept: application/json, text/event-stream
x-api-key: cak_your_api_key
```
### Step 1: List Available Tools
The server runs stateless — no session initialization required. You can call any method directly.
```bash theme={null}
curl -X POST "https://api.getchatads.com/mcp/mcp" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "x-api-key: cak_your_api_key" \
-d '{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 1
}'
```
**Response:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"tools": [{
"name": "chatads_message_send",
"description": "Send a message to ChatAds and get affiliate recommendations...",
"inputSchema": {
"properties": {
"message": {"type": "string"},
"ip": {"type": "string"},
"country": {"type": "string"},
"extraction_mode": {"type": "string"},
"resolution_mode": {"type": "string"}
},
"required": ["message"]
}
}]
}
}
```
### Step 2: Call the Tool
Send an AI assistant response as the `message` — this is what ChatAds scans for product mentions to turn into affiliate links.
```bash theme={null}
curl -X POST "https://api.getchatads.com/mcp/mcp" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "x-api-key: cak_your_api_key" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "chatads_message_send",
"arguments": {
"message": "For noise cancelling headphones, I'\''d recommend the Sony WH-1000XM5 for their excellent noise cancellation and comfort. The Bose QuietComfort Ultra are also a great choice if you prefer a lighter fit. Both are available on Amazon and typically run between $250-350."
}
},
"id": 3
}'
```
**Response:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [{
"type": "text",
"text": "{\"data\":{\"status\":\"filled\",\"offers\":[{\"link_text\":\"Sony WH-1000XM5\",\"url\":\"https://www.amazon.com/dp/B09XS7JWHH/?tag=...\",\"product\":{\"title\":\"Sony WH-1000XM5 Premium Noise Canceling Headphones...\"}}],\"requested\":1,\"returned\":1,\"billed\":true},\"error\":null,\"meta\":{\"request_id\":\"abc-123\",\"timestamp\":\"...\",\"version\":\"1.0.0\"}}"
}]
}
}
```
***
## Available Tools
### chatads\_message\_send
The main tool for fetching affiliate product recommendations.
| Parameter | Required | Type | Description |
| ------------------------ | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message` | Yes | string | User query (max 10,000 chars) |
| `extraction_mode` | No | string | `none` or `standard` (default) |
| `resolution_mode` | No | string | `none` or `standard` (default) |
| `max_offers` | No | number | Max affiliate links to return, 1–3 (default: 1) |
| `max_products_per_offer` | No | number | Max products per offer carousel, 1–3 (default: 1) |
| `ip` | No | string | End-user IP for geo-targeting |
| `country` | No | string | ISO 3166-1 alpha-2 country code |
| `metadata` | No | object | Arbitrary JSON object (max 10KB) echoed back in the top-level `metadata` response field on successful data responses. Non-object or oversized values are replaced with `{"error":"invalid input"}`. |
See the [API Reference](/api-reference/messages) for full details on each parameter.
***
## Troubleshooting
### "Missing API key" (401)
Ensure `x-api-key` header is included in your config:
```json theme={null}
"headers": {
"x-api-key": "cak_your_api_key"
}
```
### "Invalid API key type" (403) / "This tool requires a cak\_ API key"
The `chatads_message_send` tool (documented on this page) requires a ChatAds API key (`cak_` prefix). Widget keys (`cwk_`) are not supported.
The same `/mcp/mcp` endpoint also serves a separate set of read-only widget-data tools authenticated with a personal User Key (`uk_` prefix) — see the [MCP Connector guide](/guides/mcp-connector) if that's what you're trying to use.
Make sure your key starts with `cak_` — you can create one at [app.getchatads.com](https://app.getchatads.com).
### "Client must accept both application/json and text/event-stream"
Add the proper Accept header:
```
Accept: application/json, text/event-stream
```
### 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?"
***
## Next Steps
Sign up and create your API key in the dashboard
Server-side integration with the Python SDK