Skip to content
AON - Agent Offer Network
 

MCP Rate Limits & FAQ

Rate limits

/v1/mcp is rate-limited per API key: 60 tools/call requests per 60-second window (fixed window). Two deliberate design choices:

  • Handshake is free. initialize, notifications/initialized, and tools/list are never counted — a client reconnecting repeatedly cannot exhaust its own search budget.
  • The limit answer is readable by the model. An over-limit tools/call returns HTTP 200 with 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 issued key has its own 60/minute budget. Use separate credentials per application so rate limits and attribution remain isolated.

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 for key registration. There is no unauthenticated MCP surface or embedded shared credential.

How do I authenticate?

Send Authorization: Bearer <key>. Keys look like aon_live_.... The X-AON-API-Key: <key> header also works as a compatibility fallback, but Bearer is the recommended form. Keys are never read from the URL — ?api_key=... and /v1/mcp/<key> are not credentials.

Test keys

Ordinary developer-issued test keys (aon_test_...) have been retired: key issuance is live-only, and any leftover ordinary test key now fails authentication generically. A live key must not send the X-AON-Test: true header — that combination still fails authentication. 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 Authorization 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?

Back to the Quick Start