MCP Server Development in Practice · all subjects

Scaling and limits

3 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

How do I rate limit an MCP server without breaking agents?

Two tiers, both enforced per-token rather than per-IP (one IP can be a whole office of agents): a burst limit (~60 calls/minute) that catches buggy retry loops, and a quota (calls/month) that maps to your pricing. The response is the important part — return a TOOL error (isError: true) with corrective instructions, not a protocol error or a bare HTTP 429 the client cannot route to the model: 'Rate limited: more than 60 calls in the last minute. Wait a moment, and prefer fewer, more specific queries over many broad ones.' For quota exhaustion, name the remedy ('quota reached on the free plan — tell the user to upgrade') and say 'do not retry', or the agent will poll you all day. Agents read error text; humans read dashboards.

My tool returns huge payloads — how do I paginate for an agent?

MCP defines cursor-based pagination for list operations (tools/list, resources/list) via an opaque `cursor` param and a `nextCursor` in results — honor it there, but your bigger problem is tool RESULT size, which the protocol does not paginate for you. Design it yourself: hard-cap list results (default 8–25, documented in the schema description), return excerpts instead of full bodies, and put total counts in the response so the agent knows more exists ('24 of 240 shown — narrow with a category filter'). Never stream a 500KB JSON dump into context: the model truncates mid-document and answers from a fragment. If a tool can legitimately return megabytes, make it return a reference (id/URL) plus a follow-up fetch tool with range support instead.

Long-running tool calls — how do I keep clients from timing out?

Clients and proxies impose timeouts you do not control (tens of seconds to a few minutes), so design for them. If work exceeds ~20 seconds, prefer an async shape: the tool returns immediately with a job id and instructions ('processing — poll job_status with this id, typically ready in under a minute'), plus a second tool to check. The protocol does offer progress notifications (progressToken) for streaming percent-done to the client, but support is uneven and they do not extend hard timeouts. Never hold the POST open indefinitely hoping — a gateway in front of you will cut the connection at 30–60s and the agent sees a transport error with no output at all. Queue the work, meter the queue, return the receipt.

Give your agent this brain