Skip to content
 

MCP Quick Start

The Hosted MCP runtime owner has certified this production endpoint as the fixed AON v1.0 projection. Its evidence is MCP-body based: initialize.serverInfo.version="1.0.0" and tool-response data.protocol_version="1.0". MCP clients do not send an AON-Protocol-Version HTTP selector and the endpoint does not promise that REST response header.

Use this guide with the placement id of a placement in your Application. Every /v1/mcp call you send with it is identified by that placement id, sent as the X-AON-Placement-Id header, and attribution and earnings go to your application (registered mode). Without a placement id the call runs in anonymous mode (no key and no placement; the request is served through the AON default placement, the aon_search_offers response carries extra.identity.mode="anonymous", and it earns nothing), so no account is needed to try search and category tools. No API key is needed for any Hosted MCP tool. aon_submit_feedback and aon_manage_watch require an active placement in the X-AON-Placement-Id header on each call; anonymous mode cannot use them. The snippets show client configuration and an offer-search request.

Configure your placement id — anonymous calls earn nothing

We recommend sending your own placement id on every /v1/mcp call. Anonymous mode is for trying the endpoint: its traffic is served through the shared AON default placement, so clicks, conversions and earnings cannot be attributed to your application — not now and not retroactively. Anonymous traffic also shares one public rate-limit bucket.

Need a bounded test path?

MCP search needs no key: use your own placement id, or anonymous mode. If you only want a bounded test, use the non-billable Public Test Sandbox to exercise the raw Query API contract. The sandbox does not configure MCP access or create application credentials.

Your placement id

Replace plc_YOUR_PLACEMENT_ID with your placement id (plc_…) from your application's Placements page in the Developer Portal. It identifies your traffic, sends attribution and earnings to your application, and is not a secret. No API key is needed to search: without the X-AON-Placement-Id header (or the placement_id argument) the request runs in anonymous mode through the AON default placement (the response carries extra.identity.mode="anonymous") and earns nothing. For aon_submit_feedback and aon_manage_watch, the X-AON-Placement-Id header is required on every call. No API key is needed for any Hosted MCP tool.

1. Your first search — one curl

Search offers with your placement id
curl
# Anonymous mode (no key, no earnings): drop the X-AON-Placement-Id header.
curl -s -X POST https://api.aon.pro/v1/mcp \
  -H "Content-Type: application/json" \
  -H "X-AON-Placement-Id: plc_YOUR_PLACEMENT_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "aon_search_offers",
      "arguments": {
        "intent": {
          "content": [
            { "type": "input_text", "text": "credit card with cashback" }
          ]
        }
      }
    },
    "id": 1
  }' | python3 -m json.tool

The result's content[0].text is a JSON document. The parts that matter:

{
  "code": "SUCCESS",
  "data": {
    "offers": [
      {
        "offer_info": { "title": "Crypto.com: Buy BTC, ETH & CRO" },
        "entity": { "name": "Foris DAX MT" },
        "action": {
          "type": "open_url",
          "payload": { "url": "https://aon.link/3AN6AbHvQ2wT8kLp" }
        }
      }
    ],
    "request_id": "01a00beb-...",
    "protocol_version": "1.0"
  },
  "extra": {}
}

In anonymous mode extra is not empty: it carries "identity": { "mode": "anonymous", "placement_source": "default" } and a notice reminding you that the request earned nothing and that you should pass your own placement id.

Each offer's action.payload.url is a live, trackable link — open it and you land on the real product. When present, data.engagement holds follow-up suggestions the Usage Guide shows you how to act on.

Results are relevance- and geo-aware: supply differs by country, so a different query can genuinely return an empty list with data.empty_reason — that is an honest answer, not a failure. Try another category or use aon_resolve_category to find where the inventory is.

Curious what else the server exposes? List its tools:

List the server's tools
curl
curl -s -X POST https://api.aon.pro/v1/mcp \
  -H "Content-Type: application/json" \
  -H "X-AON-Placement-Id: plc_YOUR_PLACEMENT_ID" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python3 -m json.tool

2. Connect your client

All four configurations below use the same placement id placeholder (registered mode); delete the placement header to run in anonymous mode.

Claude Code

Claude Code is production-verified by the owner smoke evidence for this runtime. That evidence is specific to Claude Code and this certified endpoint.

Claude Code
curl
# One command — Claude Code stores the server in your project's .mcp.json
claude mcp add --transport http aon https://api.aon.pro/v1/mcp \
  --header "X-AON-Placement-Id: plc_YOUR_PLACEMENT_ID"
# Anonymous mode (no key, no earnings): run it without the --header option.
# Write tools (feedback / watch) require the placement header above; no API key.

Then just ask: "find me noise-cancelling headphones under $300".

Claude Desktop

Configuration reference only — Claude Desktop has not been independently tested with this release.

Claude Desktop cannot send custom HTTP headers to a remote server, so the config bridges through mcp-remote (needs Node.js installed). Restart Claude Desktop after saving.

Claude Desktop (via mcp-remote)
JSON
// claude_desktop_config.json
// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
//
// Claude Desktop cannot attach custom HTTP headers itself, so the entry
// bridges through the mcp-remote package (the header is passed via env to
// survive argument splitting on every platform).
// Registered mode shown. For anonymous mode drop "--header" and the env
// block for search/category tools. Write tools require the placement header; no API key.
{
  "mcpServers": {
    "aon": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.aon.pro/v1/mcp",
        "--header",
        "X-AON-Placement-Id:${AON_PLACEMENT_ID}"
      ],
      "env": {
        "AON_PLACEMENT_ID": "plc_YOUR_PLACEMENT_ID"
      }
    }
  }
}

Cursor

Configuration reference only — Cursor has not been independently tested with this release.

Save the file, then enable the server under Settings → MCP.

Cursor
JSON
// .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
// Registered mode shown. Anonymous mode: omit "headers" for search/category tools.
// Write tools require the placement header; no API key.
{
  "mcpServers": {
    "aon": {
      "url": "https://api.aon.pro/v1/mcp",
      "headers": {
        "X-AON-Placement-Id": "plc_YOUR_PLACEMENT_ID"
      }
    }
  }
}

VS Code

Configuration reference only — VS Code has not been independently tested with this release.

Save the file, then start the server from the MCP view or when prompted.

VS Code
JSON
// .vscode/mcp.json
// Registered mode shown. Anonymous mode: omit "headers" for search/category tools.
// Write tools require the placement header; no API key.
{
  "servers": {
    "aon": {
      "type": "http",
      "url": "https://api.aon.pro/v1/mcp",
      "headers": {
        "X-AON-Placement-Id": "plc_YOUR_PLACEMENT_ID"
      }
    }
  }
}

3. Use your placement id, or anonymous mode

Registered modeAnonymous mode
Identity you sendX-AON-Placement-Id headernone
Served throughyour own placementAON default placement
Response markernoneextra.identity.mode="anonymous" on aon_search_offers (category tools carry none)
Attribution / earningsyour applicationnone
Idempotent replayyes, per request_idno; a retry is recomputed

Copy the placement id from your application's Placements page in the Developer Portal. The placement id is not a secret. A non-empty placement that is malformed, unknown or inactive returns INVALID_PLACEMENT; an empty or whitespace-only value counts as not provided. Rate limits apply per application, and all anonymous traffic shares one application bucket. The handshake (initialize, tools/list) never needs a placement or key and carries no identity; that is not the same thing as anonymous mode, which is decided per tools/call. If a deployment has anonymous mode switched off, a tools/call without a placement returns 401 UNAUTHORIZED instead. This public guide does not set up applications, issue keys, or change account availability.

Earnings are attributed only through the placement id on the request. A call made in anonymous mode stays unattributed: setting the placement id later does not move its clicks, conversions or earnings to your application.

  1. Replace the placeholder in your client configuration with your placement id (recommended), or remove the placement header to stay in anonymous mode without earnings.
  2. Traffic is attributed to the application that owns the placement.
  3. Send X-AON-Placement-Id for aon_submit_feedback and aon_manage_watch. The header alone supplies identity; no API key is needed.
  4. Preserve returned actions and tracking data according to the integration contract.

MCP completion check

Complete this connection only after a request with your placement id (or an anonymous one) reaches /v1/mcp, the selected client configuration connects, tools/list returns discovery results, and one tools/call returns a success result. The Public Test Sandbox is not MCP access proof. If your placement id is rejected, check that the placement is active in a serviceable Application; this documentation has no other access step.

Next steps

Explore the tools →