AON — Agent Offer Network README

AON MCP Server

Give any MCP-capable agent the ability to recommend real, buyable products and services — live pricing and a trackable link on every offer, drawn from the Agent Offer Network.

Endpoint: POST https://api.aon.pro/v1/mcp
Transport: Streamable HTTP (stateless JSON-RPC 2.0 — no SSE, no session handshake)
Placement (recommended): send your placement ID in the X-AON-Placement-Id header — create one in the Developer Portal. Without it, search still works in anonymous mode, but earnings cannot be attributed to your application
Quick Start: run the curl or client examples with your placement ID
Docs: docs.aon.pro/mcp

Tools

The Hosted AON endpoint currently lists five tools. Protocol v1.0 names the four base tools below; aon_get_category_schema is an optional Hosted category-guidance extension, not a portable Protocol v1.0 guarantee. Discover it through tools/list before calling it.

aon_search_offers — Search offers by natural-language intent; every result carries live pricing, a tracking link, and pre-validated follow-up suggestions.
aon_resolve_category — Turn free text into AON Taxonomy v1 category ids.
aon_get_category_schema — Optional Hosted extension: decision factors for a resolved category id, to ask the right clarifying question before searching.
aon_submit_feedback — Record an explicit "dismissed" / "not interested" on an offer (early scaffold: acknowledged, not persisted yet).
aon_manage_watch — Restore or cancel the default watch on an offer or category on explicit request (early scaffold: acknowledged, not persisted yet).

Tool	What it does
`aon_search_offers`	Search offers by natural-language intent. Arguments are an AgentOffer Query request object — the same shape as the REST API. Returns offers with pricing, a tracking link each, and an `engagement` block of pre-validated follow-up suggestions the agent can act on.
`aon_resolve_category`	Turn free text ("hiking boots", "team chat software") into AON Taxonomy v1 category ids — the model never has to memorize or invent them.
`aon_get_category_schema`	Optional Hosted extension: return decision factors for an already resolved category id, to ask the right clarifying question before searching. Its standalone result does not add `decision_factors` to the Query request or response.
`aon_submit_feedback`	Record an explicit "dismissed" / "not interested" from the user on an offer — never inferred from silence. Early scaffold: the call is acknowledged with success, but feedback is not persisted yet; the workflow behind it is rolling out.
`aon_manage_watch`	Restore (`watch`) or cancel (`unwatch`) the default watch on an offer or category when the user explicitly asks. Early scaffold: acknowledged with success, watch state not persisted yet.

Design notes agents benefit from:

Forgiving by design — invalid values never fail a search; they are treated as "not sent" and corrected in extra.hints[]. Only a malformed, unknown or inactive placement, invalid JSON, a missing intent.content, or an oversized body hard-fail. A missing placement is not an error: the call runs in anonymous mode.
Relevance-gated — an empty result list is a real answer, never filler.
Guidance loop — follow-up suggestions carry an RFC 7386 request_patch that merges straight into the next call, plus an origin to echo back for adoption attribution.

Quick start

Terminal

curl -s -X POST https://api.aon.pro/v1/mcp \
  -H "Content-Type: application/json" \
  -H "X-AON-Placement-Id: $AON_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
  }'

No placement yet? Create an application and a placement in the Developer Portal, and store the placement ID (plc_…) in $AON_PLACEMENT_ID. It identifies your placement and is safe to use in client configuration.

To just try the endpoint, drop the X-AON-Placement-Id header: the call runs in anonymous mode through AON's shared default placement, the response carries extra.identity.mode="anonymous", and it earns nothing — clicks and conversions from anonymous calls cannot be attributed to your application, including retroactively. Configure your placement ID before real traffic.

Client setup

Ready-to-paste configs live in examples/:

Client	Config
Claude Code	`examples/claude-code`
Claude Desktop	`examples/claude-desktop` (via `mcp-remote`)
Cursor	`examples/cursor`
VS Code	`examples/vscode`
Plain curl	`examples/curl`

Rate limits

/v1/mcp allows 60 tools/call requests per minute per application; handshake calls (initialize, tools/list, notifications/*) are never counted. An over-limit tools/call returns HTTP 429 with a Retry-After header and JSON-RPC error -32000 so the model can read the retry advice. Details: Rate Limits & FAQ.

Monetization & attribution

Every offer carries a tracked destination link (action.payload.url). Surface it verbatim — clicks and conversions attribute to your placement's application, which is the basis for developer revenue share. Reporting lives in the Developer Portal.

Registry manifest

server.json is the MCP registry manifest for this server (schema 2025-12-11, namespace pro.aon — DNS-verified against the aon.pro domain).

Related repositories

protocol — AgentOffer Protocol specs (normative)
schema — JSON Schemas, TypeScript types, taxonomy
examples — HTTP / SDK / agent integration examples
rfcs — protocol evolution proposals

License

Apache-2.0