MCP limits and budgets

The call limits on every Coffee Chats address, the size of a call body and a result, and the bounds on work in flight.

This page states every limit the connector applies: how often each address answers, how large a call body and a result may be, and how much work one connection can have in flight. Each number is what the connector enforces today.

Call limits

A refused call is answered with HTTP status 429 and these headers: RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After. Wait the number of seconds in Retry-After before calling again.

What you are doing	Limit	Counted per
Starting or submitting a sign-in	10 per minute	Calling network address
Coming back from Google	30 per minute	Calling network address
Asking for an email sign-in link	5 every 3 minutes	Calling network address
Asking for an email sign-in link	1 every 3 minutes	Account
Every other authorization call	60 per minute	Calling network address
Opening or deciding a review request in the browser	60 per minute	Calling network address
Opening or deciding a review request in the browser	30 per minute	Account
Agent calls on an open connection	120 per minute	Connection and client together

The protocol limiter answers a refusal with this body:

Rate limit response body

{ "error": "rate_limited" }

A polling loop that ignores Retry-After will spend the whole budget on one waiting change and lock the agent out of its own reads. Poll a waiting approval at a human pace.

Call body size

The body of a call to the protocol address is accepted up to 2 megabytes. A larger body is refused with HTTP status 413. Only the spreadsheet imports, contacts.import and jobs.applications.import, and their checks, contacts.import.check and jobs.applications.import.check, take input that can come close. A sheet that does not fit, or that has more than 1000 rows, is sent as several calls.

Result size

Every tool declares a maximum result size, and its own page in the tool reference prints the number.

Tools	Budget
mail.drafts.send	1,024 bytes
Nineteen write tools (the five booking changes, the thank-you send, mail.outreach.update, the two profile writes, the notes, tags and outcome writes, the two campaign writes, the three application writes other than import, and actions.cancel), plus profile.job_search_stage.get and mail.outreach.get	4,096 bytes
mail.batch.enqueue and contacts.update.get	8,192 bytes
jobs.applications.apply and the other forty read tools	16,384 bytes
contacts.create, contacts.bulk_create, contacts.update, contacts.research.start, documents.section.update, the two spreadsheet imports and their two checks	32,768 bytes
The six contact read tools	49,152 bytes
documents.resumes.get, documents.jobs.get, documents.resumes.generate, documents.jobs.tailor and jobs.apply_batches.list	65,536 bytes

The budget is measured on the whole result as it goes over the wire, so the wrapping JSON counts as well as the data. 65,536 bytes is the largest result any tool in the catalogue can return, and only the document tools and the apply batch list carry it, because one resume or one batch of applications is a large single record. Among the lists, a contact page carries more records than the others do, which is why the six contact read tools have the larger budget of 49,152 bytes.

A result that would exceed its budget is not truncated. Tools whose single stored value can grow past the budget return a measured fragment and a cursor instead, and read your data describes how to reassemble one. For any other tool, a result over the budget fails with the fixed text Tool call failed., which is why the reads are narrow and paged in the first place.

A cursor is bounded too. Each tool that takes one states its length in its own input table, as either 256 or 512 characters.

Idempotency keys

Rule	Value
Length of a key	16 to 128 characters
Write tools that take one	18 of the 31
The exceptions	actions.cancel, whose whole input is the identifier of the review request it withdraws, and the twelve writes Safe writes and approvals lists by name: the contact and application creates and imports, jobs.applications.update, the three document writes, the two outreach sends and jobs.applications.apply

A stored change is made unique by the connection, the tool name and the key together. The connector sets no expiry on a key. The record a key names carries no purge clock, so a replay of an old key returns the old answer however long ago the change was made.

Work in flight

A connection can have at most four changes cleared to run at once. Each clearance lasts thirty seconds, and that is a deadline for starting rather than a promise about finishing. A change that holds a clearance and does not start within it is refused and nothing is written. A change that has already started is not stopped, including by a disconnect.

A review request waits thirty minutes from the moment it is made, and editing it does not extend that deadline.

Credential lifetimes

The sign-in and credentials page carries the full table. The two numbers that shape an agent’s behaviour are that an access credential lasts ten minutes, and that a refresh credential can be used once.

Next steps

Handle errors and retries

What to do when a limit refuses a call.

Tool reference

Each tool’s own result budget and cursor bound.