How do I make MCP rate-limit and quota responses consistent across denial and empty-result paths?

What should I check, step by step?

1. Inventory every path that can answer a tools/call: success with data, success with empty content, tool execution error (isError: true), JSON-RPC protocol error, and transport HTTP 429/401/403.

2. Decide which of those paths consume quota. Charge the same bucket for "ran and empty" and "denied by policy after auth" if both reveal that the credential was accepted and the tool name was valid — otherwise an agent learns the difference by watching remaining drop on one path only.
3. Define a single over-limit envelope: same HTTP status strategy per MCP method family, same RateLimit-* / Retry-After headers, and the same machine-readable retryAfter (seconds) in JSON-RPC error data or in the isError text the model reads.
4. Follow MCP's two error classes deliberately: protocol/JSON-RPC errors for malformed or unknown tools; tool results with isError: true for execution and budget failures the model should see. Do not mix "quota exceeded" into an empty successful result.
5. Normalize denial vs empty: when you must hide whether a row exists or a policy blocked it, return the same body, headers, and timing band for both (constant-shape empty or constant-shape error), and log the real reason only server-side.
6. Never put different remaining, limit, or reset values on denial vs empty for the same credential and window. Agents compare those counters across probes.
7. Test with a scripted client: call the same tool under (a) throttle, (b) policy deny, (c) empty dataset, and assert status, header names, remaining, and retryAfter match your matrix. Diff response bodies with a schema, not by eye.
8. Record allow/deny and which envelope you emitted with record_ai_run (hashes of tool name, decision class, remaining, retryAfter) outside the agent session so you can audit side-channel fixes without giving the model the reason codes.

Why denial and empty must not disagree on quota

MCP Security Considerations for tools tell servers to rate-limit invocations and sanitize outputs. Rate limits only help if the throttle signal is not itself a free oracle about policy or existence.

• MCP Tools define two error paths: JSON-RPC protocol errors (unknown tool, bad request) and tool execution errors returned as results with isError: true that clients SHOULD show the model for self-correction. Putting "rate limit" on one path and a silent empty content array on another teaches the model which probes are "real" denials.
• Production MCP gateways already document method-specific envelopes. Solo's agentgateway rate limiting returns isError: true for rate-limited tools/call, JSON-RPC -32003 with limit/remaining/retryAfterSeconds for other id'd methods, and HTTP 429 for notifications — and keeps rate-limit response headers on each. Copy that discipline: one matrix, applied every time, including when the business result would have been empty.
• Amazon Bedrock AgentCore's MCP throttle body puts retryAfter in the JSON-RPC error data. Whatever vendor you use, the important part for side-channels is sameness: the same credential hitting the same limit must see the same remaining and retry hints whether the underlying query would have returned rows or a policy deny.

A practical consistency matrix

Transport throttle (burst / concurrency): prefer HTTP 429 with Retry-After plus RateLimit-Limit/Remaining/Reset (or your gateway's x-ratelimit-* equivalents) before tool code runs. Say the same retry seconds in any JSON body you also return.

• Per-tool or daily budget spent: return tools/call with isError: true and a short text that names the limit and when to retry — not a successful empty list that looks like "no tickets found."
• Authz deny that should be indistinguishable from empty (existence or tenant isolation): return one fixed shape (either always empty success with no differentiating headers, or always the same isError budget/deny envelope) and do not decrement a visible remaining counter on only one of those paths.
• Unknown tool / malformed call: JSON-RPC protocol error. Do not burn per-tool budget in a way that moves RateLimit-Remaining differently than a well-formed call, or an agent can fingerprint valid tool names via the counter.

What can go wrong?

Policy deny returns 403 with Remaining: 0 while empty search returns 200 with Remaining: 12 — the agent maps which queries your ACL cares about.

• Throttle returns Retry-After: 20 but the isError text says "try again in 60s," so the model retries on the wrong schedule and also learns you have two code paths.
• Empty results skip the rate-limit middleware entirely, so only denied calls move the counter — a classic side channel.
• Verbose error_description names the internal policy id or row id on deny but not on empty, leaking the distinction in the body even when headers match.