Skip to main content

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.

​
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:
{
  "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:
  • Creates a session on first request
  • Returns responses as Server-Sent Events (SSE)
  • Maintains session state via mcp-session-id header

​
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. 
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: 
{
  "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. 
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: 
{
  "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.
ParameterRequiredTypeDescription
messageYesstringUser query (max 10,000 chars)
extraction_modeNostringnone or standard (default)
resolution_modeNostringnone or standard (default)
max_offersNonumberMax affiliate links to return, 1–3 (default: 1)
max_products_per_offerNonumberMax products per offer carousel, 1–3 (default: 1)
ipNostringEnd-user IP for geo-targeting
countryNostringISO 3166-1 alpha-2 country code
metadataNoobjectArbitrary 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 for full details on each parameter.

​
Troubleshooting

​
”Missing API key” (401)

Ensure x-api-key header is included in your config: 
"headers": {
  "x-api-key": "cak_your_api_key"
}

​
“Invalid API key type” (403)

The MCP endpoint requires a ChatAds API key (cak_ prefix). Widget keys (cwk_) are not supported. Make sure your key starts with cak_ — you can create one at 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

Get API Key

Sign up and create your API key in the dashboard

Python SDK

Server-side integration with the Python SDK