> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.squarecloud.app/en/api-reference/limitations-and-restrictions.md#api-limits) 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](https://docs.squarecloud.app/en/cli-reference/deploy.md) 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:

```json theme={"system"}
{
  "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](https://docs.squarecloud.app/en/mcp/connect.md#create-an-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](https://docs.squarecloud.app/en/platform/plans.md). |
| `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](https://docs.squarecloud.app/en/mcp/connect.md#create-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](https://squarecloud.app/en/account/security) and connect again. |
| The consent page says the request expired | It lasts 10 minutes. | Start the connection again from the client. |

### 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](https://docs.squarecloud.app/en/mcp/permissions-and-safety.md#deletions-and-restores) 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](#limits) 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](https://docs.squarecloud.app/en/cli-reference/deploy.md) 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](https://docs.squarecloud.app/en/mcp/permissions-and-safety.md#scopes). Other codes come from the tool itself, and the `summary` explains them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.