> ## 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 限制与错误

> Square Cloud MCP 服务器各套餐的请求和工具限制、TOOL_RATE_LIMITED 的返回形式，以及客户端可能遇到的每个错误的处理方法。

## 限制

限制按账户计算，由该账户的所有 MCP 连接共享。每一层都叠加在上一层之上：

1. **对 MCP 服务器的请求。** 每个账户每分钟最多 60 个；如果你套餐的 [API 速率限制](https://docs.squarecloud.app/zh/api-reference/limitations-and-restrictions.md#api-限制)更低，则以它为准。这些请求与你的 API 调用分开计算，因此繁忙的智能体不会阻塞你的其他集成。超出后，请求会在 60 秒内返回 `429 RATE_LIMITED`。
2. **在 API 上被封锁的账户在这里也会被封锁。** 账户超出 API 速率限制期间，MCP 服务器也会返回 `429 RATE_LIMITED`。
3. **工具预算：** 每分钟的工具调用次数，为你套餐 API 速率的一半，最多 60 次，因为一次工具调用要做的工作远多于一次请求。
4. **单个工具的上限**，适用于在你的应用内部读写或查询边缘网络的工具。
5. **Cubic 的单个工具限制**，Cubic 是 Square Cloud 的 AI 助手。MCP 和 Cubic 按账户共享这些限制。

第 3、4、5 层会返回 `TOOL_RATE_LIMITED` 工具结果，详见下文。

| 工具 | 每分钟调用次数 | 达到后暂停 |
| - | - | - |
| 所有工具，`HOBBY-1` | 15 | 60 秒 |
| 所有工具，`HOBBY-2` | 30 | 60 秒 |
| 所有工具，`STANDARD-4` 及以上 | 60 | 60 秒 |
| `list_files`、`read_file` | 各 20 | 60 秒 |
| `search_files` | 3 | 120 秒 |
| `list_env_vars` | 10 | 60 秒 |
| `create_file`、`edit_file`、`patch_file`、`rename_file` | 各 10 | 120 秒 |
| `edit_config_file` | 5 | 120 秒 |
| `commit_application` | 5 | 120 秒 |
| `delete_file` | 5 | 180 秒 |
| `get_application_logs` | 10 | 60 秒 |
| `get_application_status` | 20 | 60 秒 |
| `get_metrics_history` | 10 | 60 秒 |
| `get_network_analytics`、`get_network_errors`、`get_network_performance`、`get_network_logs` | 各 5 | 60 秒 |
| `search_help_center` | 4 | 60 秒 |
| `list_help_center` | 2 | 60 秒 |
| `start_application`、`stop_application`、`restart_application` | 各 10 | 120 秒 |

* **每次工具调用都会计数**，包括因资源或取决于参数的权限范围（例如 `set_env_vars` 的 `restart`）被拒绝的调用。
* **例如在 `HOBBY-1` 上**，MCP 每分钟永远不会超过 15 次工具调用，而你的 CLI、SDK 和机器人仍可使用套餐的全部 API 速率。
* **提交与 API、CLI 和控制面板共用同一节奏**：每个账户每 2 秒一次，每个应用每 5 秒一次。早于此时，`commit_application` 会返回 `RATE_LIMITED`。

### zip 与文件

* **zip：** `upload_application` 和 `commit_application` 接受以 base64 发送、最大 1 MB 的 zip，解压后最大 100 MB。控制面板和 [CLI](https://docs.squarecloud.app/zh/cli-reference/deploy.md) 接受最大 100 MB 的 zip，较大的项目请使用它们。
* **文件：** `commit_application` 最多接受 50 个文本文件，每个最大 128 KB，总计最大 512 KB。不能是隐藏文件、`.env` 文件、私钥或配置文件；配置文件通过 `edit_config_file` 更改。

### TOOL\_RATE\_LIMITED

超出限制的工具不会执行。返回的是一个标记为 `isError: true` 的普通工具结果，而不是 HTTP 错误，因此连接仍可继续使用：

```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."
}
```

如果达到的是工具预算限制，摘要会显示 `too many AI actions in a short time`，所有工具都需要等待；否则只有该工具需要等待。如果客户端在该工具仍受限时再次调用它，这第二次连续拒绝会改为返回 `TOOL_EXECUTION_FAILED`，告诉客户端停止，并让你等待几分钟或使用控制面板。

## 错误

### HTTP 错误

这些错误以请求的 HTTP 状态码返回，JSON 响应体中带有 `code`。

| 状态码 | 代码 | 何时出现 | 处理方法 |
| - | - | - | - |
| `401` | `ACCESS_DENIED` | 没有密钥，或密钥错误、已吊销或已过期。响应中带有 OAuth 质询，因此 Claude 和 ChatGPT 会要求你重新登录。 | 重新连接客户端，或创建新的 [API 密钥](https://docs.squarecloud.app/zh/mcp/connect.md#创建-api-密钥)。 |
| `403` | `ACCESS_DENIED` | 发送的是控制面板会话令牌，而不是 API 密钥。 | 通过 OAuth 或 API 密钥连接。 |
| `403` | `MISSING_SCOPE` | 密钥没有 `mcp` 权限范围。在 REST API 上使用 Claude 或 ChatGPT 的密钥时也会返回此错误。 | 创建一个带有 `mcp` 的密钥。 |
| `403` | `UPGRADE_REQUIRED` | 账户没有有效套餐。 | 订阅或续订[套餐](https://docs.squarecloud.app/zh/platform/plans.md)。 |
| `421` | `WRONG_HOST` | 请求发送到了其他 Square Cloud 地址，例如 `api.squarecloud.app`。 | 使用 `https://mcp.squarecloud.app/mcp`。 |
| `429` | `RATE_LIMITED` | 超出了对 MCP 服务器的请求限制，或账户因 API 速率限制被封锁。 | 等待一分钟，并降低客户端的请求频率。 |
| `400` | JSON-RPC 错误 | 不受支持的协议版本（`-32022`，附带受支持的版本列表）或格式错误的请求。 | 更新客户端。 |

### 连接时

| 你看到的内容 | 原因 | 处理方法 |
| - | - | - |
| `mcp.squarecloud.app` 的页面上出现 `UNKNOWN_CLIENT` 或 `INVALID_REDIRECT_URI` | 只有使用其公开身份的 Claude 和 ChatGPT 可以通过 OAuth 登录。 | 在 Claude 中，选择 **Use Claude's published identity**。在其他客户端中，使用 [API 密钥](https://docs.squarecloud.app/zh/mcp/connect.md#创建-api-密钥)连接。 |
| `The account is at its API key limit` | 账户已有 10 个密钥。 | 在你的[账户安全设置](https://squarecloud.app/zh/account/security)中吊销一个密钥，然后重新连接。 |
| 授权页面提示请求已过期 | 请求的有效期为 10 分钟。 | 从客户端重新开始连接。 |

### 工具结果

这些代码以 `code` 的形式出现在工具结果中，旁边附有供客户端读取的 `summary`。

| 代码 | 含义 | 处理方法 |
| - | - | - |
| `SNAPSHOT_NOT_READY` | 删除、恢复或带 `snapshot` 的 `commit_application` 之前创建的[安全 snapshot](https://docs.squarecloud.app/zh/mcp/permissions-and-safety.md#删除与恢复)仍在生成中。没有执行任何操作。 | 客户端会在大约 2 分钟后使用相同的参数重试。 |
| `MISSING_SCOPE` | 此调用需要密钥没有的权限范围，例如查看数据库指标所需的 `databases:read`。 | 使用带有该权限范围的密钥。 |
| `RESOURCE_NOT_ALLOWED` | 密钥被限定到其他应用和数据库，或者它涵盖的资源中没有该名称。 | 使用涵盖该资源的密钥。 |
| `TOOL_RATE_LIMITED` | 达到了某个[限制](#限制)。 | 等待摘要中给出的时间。 |
| `TOOL_EXECUTION_FAILED` | 同一工具连续两次触及限制，或执行失败。 | 等待几分钟或使用控制面板。 |
| `APP_NOT_FOUND`、`DATABASE_NOT_FOUND` | 没有与该名称或 ID 匹配的应用或数据库。 | 让客户端先列出它们。 |
| `INVALID_ZIP` | `zip` 不是 base64，或 zip 已损坏。 | 重新生成 zip 并再次发送。 |
| `ZIP_TOO_LARGE` | zip 超过 1 MB，或解压后超过 100 MB。 | 发送更小的 zip，或通过 [CLI](https://docs.squarecloud.app/zh/cli-reference/deploy.md) 或控制面板部署该项目。 |
| `MISSING_MANIFEST` | `upload_application` 的 zip 根目录中没有 `squarecloud.app`，通常是因为项目位于 zip 内的某个文件夹中。 | 压缩该文件夹的内容，让 `squarecloud.app`（`DISPLAY_NAME`、`MAIN`、`MEMORY`、`VERSION`）位于根目录。 |
| `BLOCKED_PATH` | 某个路径指向目标文件夹之外，或 zip 中包含 `.squarecloud` 文件夹内的文件，该文件夹属于平台，无法修改。在 `files` 中，隐藏文件、`.env` 文件、私钥和配置文件也会被拒绝。 | 移除这些文件后再次发送。 |
| `INVALID_PATH` | `path` 不是提交可以写入的文件夹。 | 选择应用的另一个文件夹。 |
| `RESTORE_IN_PROGRESS` | 该应用正在进行恢复。 | 等待恢复完成后重试。 |
| `RATE_LIMITED` | 提交与上一次提交间隔太短。 | 等待几秒后重试。 |
| `COMMIT_FAILED` | 无法将新版本写入应用。 | 重试，或通过控制面板发送。 |

密钥无法使用的工具或不存在的工具会返回 JSON-RPC 错误 `-32602` `Unknown tool`。请检查密钥的[权限范围](https://docs.squarecloud.app/zh/mcp/permissions-and-safety.md#权限范围)。其他代码来自工具本身，`summary` 会对其进行说明。


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