MCP limits and errors

The request and tool limits of the Square Cloud MCP server per plan, what TOOL_RATE_LIMITED looks like, and what to do about each error a client can get.

Limits

The limits are per account and shared by all its MCP connections. Each layer applies on top of the previous one:

1. Requests to the MCP server. Up to 60 a minute per account, or your plan’s API rate limit if it is lower. They count apart from your API calls, so a busy agent never blocks your other integrations. Over it, requests answer 429 RATE_LIMITED for 60 seconds.
2. An account blocked on the API is blocked here too. While the account is over its API rate limit, the MCP server answers 429 RATE_LIMITED as well.
3. The tool budget: tool calls a minute, half your plan’s API rate and at most 60, since a tool call does much more work than a request.
4. Per-tool caps for the tools that read or write inside your application or query the edge network.
5. The per-tool limits of Cubic, the Square Cloud AI assistant. The MCP and Cubic share them, per account.

Layers 3, 4 and 5 answer with a TOOL_RATE_LIMITED tool result, described below.

Tools	Calls a minute	Pause once reached
All tools, HOBBY-1	15	60 s
All tools, HOBBY-2	30	60 s
All tools, STANDARD-4 and above	60	60 s
list_files, read_file	20 each	60 s
search_files	3	120 s
list_env_vars	10	60 s
create_file, edit_file, patch_file, rename_file	10 each	120 s
edit_config_file	5	120 s
commit_application	5	120 s
delete_file	5	180 s
get_application_logs	10	60 s
get_application_status	20	60 s
get_metrics_history	10	60 s
get_network_analytics, get_network_errors, get_network_performance, get_network_logs	5 each	60 s
search_help_center	4	60 s
list_help_center	2	60 s
start_application, stop_application, restart_application	10 each	120 s

• Every tool call counts, including calls refused for a resource or for a scope that depends on the arguments (such as restart on set_env_vars).
• On HOBBY-1, for example, the MCP never goes past 15 tool calls a minute, and your CLI, SDKs and bots keep the plan’s whole API rate.
• Commits share one pace with the API, the CLI and the dashboard: one every 2 seconds per account and one every 5 seconds per application. Sooner, commit_application answers RATE_LIMITED.

Zips and files

• Zip: upload_application and commit_application take a zip of up to 1 MB, sent as base64, and up to 100 MB once unpacked. The dashboard and the CLI take zips of up to 100 MB: use them for a larger project.
• Files: commit_application takes up to 50 text files, up to 128 KB each and 512 KB in all. They can’t be hidden files, .env files, private keys or the configuration file, which changes through edit_config_file.

TOOL_RATE_LIMITED

A tool over a limit doesn’t run. The answer is a regular tool result marked isError: true, not an HTTP error, so the connection keeps working:

{
  "ok": false,
  "code": "TOOL_RATE_LIMITED",
  "summary": "read_file did NOT run: this action is on a short safety cooldown. Continue with what you already have, and tell the user it can run again in about 60 seconds."
}

When the tool budget is the limit reached, the summary says too many AI actions in a short time and every tool waits; otherwise only that tool does. If the client calls the same tool again while it is still limited, that second refusal in a row answers TOOL_EXECUTION_FAILED instead, which tells the client to stop and you to wait a few minutes or use the dashboard.

Errors

HTTP errors

These come back as the HTTP status of the request, with a JSON body carrying code.

Status	Code	When	What to do
401	ACCESS_DENIED	No key, or the key is wrong, revoked or expired. The answer carries the OAuth challenge, so Claude and ChatGPT ask you to sign in again.	Reconnect the client, or create a new API key.
403	ACCESS_DENIED	A dashboard session token was sent instead of an API key.	Connect with OAuth or with an API key.
403	MISSING_SCOPE	The key doesn’t have the mcp scope. Also returned when a Claude or ChatGPT key is used on the REST API.	Create a key with mcp.
403	UPGRADE_REQUIRED	The account has no active plan.	Subscribe to or renew a plan.
421	WRONG_HOST	The request went to another Square Cloud address, such as api.squarecloud.app.	Use https://mcp.squarecloud.app/mcp.
429	RATE_LIMITED	Over the MCP server’s request limit, or the account is blocked by its API rate limit.	Wait a minute and slow the client down.
400	JSON-RPC error	An unsupported protocol version (-32022, with the supported list) or a malformed request.	Update the client.

While connecting

What you see	Why	What to do
UNKNOWN_CLIENT or INVALID_REDIRECT_URI on a page of mcp.squarecloud.app	Only Claude, with its published identity, and ChatGPT sign in with OAuth.	In Claude, choose Use Claude’s published identity. In other clients, connect with an API key.
The account is at its API key limit	The account already has 10 keys.	Revoke a key in your account security settings and connect again.
The consent page says the request expired	It lasts 10 minutes.	Start the connection again from the client.
The consent page says the connection was started in another browser	Only the browser where you clicked Connect can approve it.	Click Connect again in the client and approve in the browser it opens.

Tool results

These come back inside a tool result, as code, next to a summary the client reads.

Code	Meaning	What to do
SNAPSHOT_NOT_READY	The safety snapshot taken before a deletion, a restore or a commit_application with snapshot is still being generated. Nothing ran.	The client tries again with the same arguments in about 2 minutes.
MISSING_SCOPE	This call needs a scope the key doesn’t have, such as databases:read for the metrics of a database.	Use a key with that scope.
RESOURCE_NOT_ALLOWED	The key is restricted to other applications and databases, or none it covers matches that name.	Use a key that covers the resource.
TOOL_RATE_LIMITED	A limit was reached.	Wait for the time in the summary.
TOOL_EXECUTION_FAILED	The same tool hit a limit twice in a row, or it failed.	Wait a few minutes or use the dashboard.
APP_NOT_FOUND, DATABASE_NOT_FOUND	No application or database matches the name or ID.	Ask the client to list them first.
INVALID_ZIP	zip is not base64, or the zip is damaged.	Build the zip again and send it again.
ZIP_TOO_LARGE	The zip is over 1 MB, or over 100 MB once unpacked.	Send a smaller zip, or deploy the project with the CLI or the dashboard.
MISSING_MANIFEST	The zip of upload_application has no squarecloud.app at its root, often because the project sits inside a folder of the zip.	Zip the folder’s contents, with squarecloud.app (DISPLAY_NAME, MAIN, MEMORY, VERSION) at the root.
BLOCKED_PATH	A path points outside the destination folder, or the zip has files inside the .squarecloud folder, which belongs to the platform and can’t be modified. In files, hidden files, .env files, private keys and the configuration file are refused too.	Remove those files and send again.
INVALID_PATH	path is not a folder a commit can write to.	Choose another folder of the application.
RESTORE_IN_PROGRESS	A restore is running on the application.	Wait for it to finish and try again.
RATE_LIMITED	A commit came too soon after the previous one.	Wait a few seconds and try again.
COMMIT_FAILED	The new version couldn’t be written to the application.	Try again, or send it from the dashboard.

A tool your key can’t use, or one that doesn’t exist, answers the JSON-RPC error -32602 Unknown tool. Check the key’s scopes. Other codes come from the tool itself, and the summary explains them.