Limits and troubleshooting

An agent calls tools in a loop, and a tool that spends money in a loop is a different risk from an HTTP client a human is driving. The server is built around that difference: spend caps, confirmation, a rate limit, careful retries, and errors that say what they mean.

Spending#

The budget counts calls, not credits:

• Each billed response states what it cost (meta.credits_charged), and the assistant and the card show that figure, never an estimate. A call served from the response cache shows 0, because it was not billed again.
• The cap stays a count of calls because a call is what the assistant decides to make; what a call will cost is known only once it has answered.
• The running spend for the session is measured from your balance before and after.
• The balance is re-read before a billable call whenever the last reading is more than a minute old (the credits endpoint is free), so the figure moves as you spend. Credits bought mid-session are reported as added rather than as negative spend.

Confirmation

Past the threshold, the server asks through MCP elicitation: the protocol's own ask-the-user mechanism.

• It fails closed. In a client with no elicitation support the call is refused rather than spent. A confirmation nobody can answer must not become an implicit yes.
• sprouts_research_run at high, xhigh or auto effort always asks, whatever the session's call count. Those are the tiers where one call can cost more than a whole session of searches. The confirmation names the price, which is held when the run starts and charged only if the run succeeds: a run that fails or that you cancel costs nothing.

Running out of credits#

A billable call that fails with 402 credits.insufficient can turn into a payment you can make, instead of a dead end. What happens depends on your host:

• The 402 never grows a payment link in its text. A URL goes only behind a host's consent dialog or through the tool you asked to use.
• Only credits.insufficient qualifies. A 402 for a declined card is a different problem, and a top-up page would not fix it.
• The low-balance warning works the other way round. It informs and never interrupts, because a payment prompt on every call under a threshold would be an advertisement, not a warning.

Rate limit#

60 tool calls per minute per credential. Only tools/call is metered. Protocol chatter (listing tools, reading resources, the handshake) is free, because rate-limiting discovery would make a client look broken before it had done any work. The bucket belongs to the credential's identity, so refreshing a sign-in token does not reset it.

Past the limit, the server answers the request itself, before any tool runs:

• an HTTP 429 with a Retry-After header, in seconds
• a JSON-RPC error with code: -32000 and a message saying how long to wait
• data: { code: "quota.burst_exceeded", retry_after_seconds }, the same code the HTTP API uses for the same condition, so a client can branch on data.code rather than on the message

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Rate limit reached on this server: wait 12s and retry. This protects your credit balance as much as the service — do not tighten the loop.",
    "data": { "code": "quota.burst_exceeded", "retry_after_seconds": 12 }
  },
  "id": null
}

Nothing ran and nothing was charged. Wait for Retry-After, then send the call again. The limit is surfaced rather than swallowed on purpose: a server that silently slept would look like a hang. How it reaches the model depends on your client.

Retries and pagination#

• Only 503 and 504 are retried, once, with the same Idempotency-Key. They are almost always answered before any charge. The exception is 503 credits.unavailable, where the billing service could not confirm a charge and the call may have been billed; because the retry carries the same key, a retry that returns the same rows is not charged again. A 402 is commercial and will never succeed on a retry; a 429 carries its own wait.
• A dropped connection on a billed call is never retried. The server cannot know whether the search already ran and was charged, so a retry could bill you twice. You get a clear error instead. Free calls (coverage, credits, usage, filters) are retried, because there is nothing to double-charge.
• One call, one page. No tool ever paginates internally. Continuing is a visible decision, made with a cursor, by the model or by you from a card after confirming it. Each further page is charged for the results it adds, which is exactly why it should not happen behind your back. A page bought from a card goes through the same budget, confirmation and cache as the model's own calls.

Sessions#

A session is opened by the initialize handshake and identified by Mcp-Session-Id thereafter.

• It is bound to the credential that opened it. A request presenting someone else's session id is refused, and every cache, held record and rate-limit bucket is scoped to the credential, so one hosted process serving many tenants keeps them fully separate. That holds for an API key and an OAuth token alike: the binding is to the credential, not to which kind it is.
• Sessions expire after 30 idle minutes. An expired or unknown id is answered with an instruction to re-initialize, which well-behaved clients do transparently.

Troubleshooting#