Skip to main content

​
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.
Some MCP clients require paid plans for remote HTTP servers. If your client doesn’t support remote servers, use the Python Wrapper instead (stdio transport).

​
Quick Start

Add ChatAds to your MCP client’s configuration. The location varies by client:
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
{
  "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: Initialize Session

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": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "clientInfo": {"name": "my-client", "version": "1.0"},
      "capabilities": {}
    },
    "id": 1
  }'
Response headers include: 
mcp-session-id: abc123...
Save this session ID for subsequent requests.

​
Step 2: List Available Tools

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" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 2
  }'
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"},
          "quality": {"type": "string"}
        },
        "required": ["message"]
      }
    }]
  }
}

​
Step 3: Call the Tool

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" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "chatads_message_send",
      "arguments": {
        "message": "I need a good standing desk for my home office"
      }
    },
    "id": 3
  }'
Response: 
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"data\":{\"status\":\"filled\",\"offers\":[{\"link_text\":\"standing desk\",\"url\":\"https://amazon.com/...\",\"confidence_level\":\"high\"}],\"requested\":1,\"returned\":1},\"error\":null}"
    }]
  }
}

​
Available Tools

​
chatads_message_send

The main tool for fetching affiliate product recommendations. Parameters:
ParameterTypeRequiredDescription
messagestringYesUser message to analyze (1-5000 chars)
ipstringNoIPv4/IPv6 address for country detection (max 45 chars)
countrystringNoISO country code (e.g., “US”)
qualitystringNo”fast”, “standard” (default), or “best”
Response Format: 
{
  "data": {
    "status": "filled",
    "offers": [
      {
        "link_text": "standing desk",
        "url": "https://amazon.com/dp/...",
        "confidence_level": "high"
      }
    ],
    "requested": 1,
    "returned": 1
  },
  "error": null,
  "meta": {
    "request_id": "abc-123"
  }
}

​
Comparison: Native Server vs Wrapper

FeatureNative ServerPython Wrapper
InstallationNonepip install chatads-mcp-wrapper
TransportHTTP (remote)stdio (local)
UpdatesAutomaticManual pip upgrade
Local controlNoYes
Circuit breakerServer-sideBuilt-in client-side
Offline useNoCan cache locally

​
Troubleshooting

​
”Missing API key” (401)

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

​
“Missing session ID”

The MCP protocol requires session initialization. If calling directly, ensure you:
  1. First call initialize method
  2. Save the mcp-session-id from response headers
  3. Include it in subsequent requests

​
”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 Wrapper

Local server for clients requiring stdio transport