# MCP Rate Limits & FAQ

Source: https://docs.aon.pro/mcp/faq

> Derived from the same AON Docs release as the source page.

## 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](https://developer.aon.pro/) 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](https://docs.aon.pro/quickstart/public-test-sandbox) instead (it cannot call MCP).

### My MCP client can't set custom headers

Bridge through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), which runs locally via stdio and forwards your `Authorization` header — the [Quick Start](https://docs.aon.pro/mcp/quickstart) 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](https://docs.aon.pro/mcp/guide#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?

-   Key & application management: [Developer Portal](https://developer.aon.pro/)
-   Protocol and schema: [github.com/agentoffernetwork](https://github.com/agentoffernetwork)

[Back to the Quick Start](https://docs.aon.pro/mcp/quickstart)