Rate limits and errors

Limits

Endpoint	Limit	Window	Counted per
POST / — the MCP endpoint	180 requests	60 seconds	Potloc user account
POST /register — registration	20 requests	60 seconds	Client IP address

Four things worth knowing:

• The unit is HTTP requests, not tool calls. initialize, tools/list and each tools/call cost one request apiece.
• The budget is per user, not per token or per client. Every client, device and refreshed token you hold draws on the same budget.
• The window slides. There is no separate burst allowance: you may spend the whole budget at once, and capacity returns as the oldest requests age out.
• It sits well above a normal session. A measured agent loop peaks near 47 requests a minute, because a batch of parallel tool calls still costs one turn. Ordinary interactive use, a full report run included, does not come close.

Requests without a token are counted nowhere — they are rejected before the throttle sees them.

When you exceed a limit

The server answers 429 Too Many Requests with a Retry-After header giving the seconds to wait — never longer than the window above — and:

{ "error": "rate_limit_exceeded" }

Wait for Retry-After before retrying. Requests sent earlier keep failing and do not extend the penalty. The server does not return X-RateLimit-* headers, so remaining budget is not visible before a limit binds.

Transport errors

These come back as plain HTTP responses, outside the JSON-RPC envelope:

Status	Body	Meaning
401	{"error": "unauthorized"}	Missing, expired or revoked token. Carries a WWW-Authenticate header pointing at the protected-resource document — re-run the OAuth flow.
403	{"error": "insufficient_scope"}	A valid token, but not one issued for this server. It must carry the mcp_customer scope.
404	JSON-RPC Method not found	A method that would open a server-initiated notification stream. Any other unsupported method answers 200 with a JSON-RPC -32601 error instead.
422	{"error": "invalid_redirect_uri"}	On /register: the address the app gave for sending you back was refused. error_description says why.
422	{"error": "invalid_client_metadata"}	On /register: the registration payload was rejected. error_description names the problem.
429	{"error": "rate_limit_exceeded"}	Rate limit exceeded — see above.

Tool errors

A tool that cannot complete — an id that does not exist, a survey you may not open, an argument the record rejects — is different. The request still succeeds at the HTTP and JSON-RPC level, and the failure comes back as an MCP tool error result carrying a readable message:

{ "error": "Not authorized to show? this Survey" }

{ "error": "Survey 4044 not found" }

{ "error": "Validation failed: Title has already been taken" }

Your assistant surfaces these as tool errors rather than connection problems, and recovers from them without reconnecting.