MCP Rate Limits & FAQ
Rate limits
/v1/mcp is rate-limited per application: 60 tools/call requests per
60-second window (fixed window), shared across all placements of the
application. Two deliberate design choices:
- Handshake is free.
initialize,notifications/initialized, andtools/listare never counted — a client reconnecting repeatedly cannot exhaust its own search budget. - The limit answer is readable by the model. An over-limit
tools/callreturns HTTP 429 with aRetry-Afterheader and a JSON-RPC error, code-32000, whose message says when to retry. Agents see it as tool output and can tell the user, instead of the connection appearing broken.
If the rate-limit backend itself is unavailable the endpoint fails closed with HTTP 503 — retry with backoff.
Each application has its own 60/minute budget. Use a separate application per product so rate limits and attribution remain isolated. All anonymous traffic belongs to one AON default application and shares one public bucket, so send a placement id of your own to get an isolated budget and attribution.
FAQ
Which endpoint do I use?
POST https://api.aon.pro/v1/mcp — it is the only MCP endpoint.
api.agentoffernetwork.com serves the same API for existing integrations.
What happened to /mcp/v0?
The unauthenticated legacy endpoint /mcp/v0 has been retired. Every request
gets HTTP 410 Gone with a JSON-RPC-shaped body pointing to /v1/mcp and
the Developer Portal to create a placement. Every
/v1/mcp call is identified by a placement id; without one, search runs in
anonymous mode (see below).
Do I need an API key?
No. Without any identity, aon_search_offers,
aon_resolve_category and aon_get_category_schema run in anonymous mode:
the request is served through the AON default placement, the aon_search_offers
response carries extra.identity.mode="anonymous" (the two category tools carry
no identity marker), nothing is earned, and anonymous requests are
not idempotently replayed (a retry recomputes). To earn attribution send your
own placement id (see below). A non-empty invalid placement returns
INVALID_PLACEMENT; an empty or whitespace-only value counts as not provided.
The handshake (initialize, tools/list) needs no placement or key and
carries no identity; anonymous query mode is decided per tools/call. We
recommend always sending your placement id: anonymous traffic cannot be
attributed to your application, now or retroactively.
The write tools aon_submit_feedback and aon_manage_watch also need no API
key, but they require an active placement in the X-AON-Placement-Id header.
They cannot run anonymously. For search and category tools, an unmapped live
key without a placement is served anonymously, and a non-sandbox aon_test_
key without a placement returns 401 UNAUTHORIZED.
How do I authenticate write tools?
Send X-AON-Placement-Id: plc_YOUR_PLACEMENT_ID on every call. It must identify
an active placement whose application and developer can serve traffic. A
missing or blank header returns 401 UNAUTHORIZED; a malformed, unknown or
inactive placement returns INVALID_PLACEMENT. The header alone supplies
identity: API keys are ignored, and a body/query placement id or anonymous
default cannot substitute for it. The application's normal MCP rate limit applies.
How do I identify my traffic?
Send your placement id as the X-AON-Placement-Id header. Placement ids look like
plc_... and are not secrets. Placement ids are never read from the URL
path.
Can I send test traffic?
MCP traffic is always live — do not send the X-AON-Test: true header, which
is rejected. For a shared, non-billable way to try the Query API before review
completes, use the Public Test Sandbox
instead (it cannot call MCP).
My MCP client can't set custom headers
Bridge through mcp-remote, which
runs locally via stdio and forwards your X-AON-Placement-Id header — the
Quick Start shows the exact Claude Desktop config. There is
no header-free network endpoint.
Is the server stateful? Do I need SSE?
No. The server is stateless JSON-RPC over HTTP POST — every request stands alone, no session handshake is stored, and no SSE stream is required. Streamable-HTTP clients work as-is.
Why did my search return zero offers?
Results are relevance-gated: if nothing in the network genuinely matches, you
get an empty list plus data.empty_reason — not filler. Broaden the query,
follow an engagement suggestion, or try another category.
Why was my argument ignored?
Check extra.hints[] in the response. Invalid values are tolerated (treated
as not sent) and each one is reported there with a correction — see
tolerant degradation.
Are search results influenced by who pays more?
Ranking is relevance-gated; every offer carries match_reason explaining why
it appears. Tracking links attribute the click to your application for
revenue share — they do not change ranking.
Where do I report issues?
- Placement & application management: Developer Portal
- Protocol and schema: github.com/agentoffernetwork