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
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
# 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.toolThe 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:
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.tool2. 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.
# 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_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/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.
// .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 mode | Anonymous mode | |
|---|---|---|
| Identity you send | X-AON-Placement-Id header | none |
| Served through | your own placement | AON default placement |
| Response marker | none | extra.identity.mode="anonymous" on aon_search_offers (category tools carry none) |
| Attribution / earnings | your application | none |
| Idempotent replay | yes, per request_id | no; 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.
- Replace the placeholder in your client configuration with your placement id (recommended), or remove the placement header to stay in anonymous mode without earnings.
- Traffic is attributed to the application that owns the placement.
- Send
X-AON-Placement-Idforaon_submit_feedbackandaon_manage_watch. The header alone supplies identity; no API key is needed. - 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
- Tools Reference — full argument surface of the five tools
- Usage Guide — the guidance loop and session continuity
- Rate Limits & FAQ