MCP 限制与错误

限制

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

对 MCP 服务器的请求。 每个账户每分钟最多 60 个；如果你套餐的 API 速率限制更低，则以它为准。这些请求与你的 API 调用分开计算，因此繁忙的智能体不会阻塞你的其他集成。超出后，请求会在 60 秒内返回 429 RATE_LIMITED。
在 API 上被封锁的账户在这里也会被封锁。 账户超出 API 速率限制期间，MCP 服务器也会返回 429 RATE_LIMITED。
工具预算： 每分钟的工具调用次数，为你套餐 API 速率的一半，最多 60 次，因为一次工具调用要做的工作远多于一次请求。
单个工具的上限，适用于在你的应用内部读写或查询边缘网络的工具。
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 秒
`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 速率。

TOOL_RATE_LIMITED

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

{
  "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 密钥。
`403`	`ACCESS_DENIED`	发送的是控制面板会话令牌，而不是 API 密钥。	通过 OAuth 或 API 密钥连接。
`403`	`MISSING_SCOPE`	密钥没有 `mcp` 权限范围。在 REST API 上使用 Claude 或 ChatGPT 的密钥时也会返回此错误。	创建一个带有 `mcp` 的密钥。
`403`	`UPGRADE_REQUIRED`	账户没有有效套餐。	订阅或续订套餐。
`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 密钥连接。
`The account is at its API key limit`	账户已有 10 个密钥。	在你的账户安全设置中吊销一个密钥，然后重新连接。
授权页面提示请求已过期	请求的有效期为 10 分钟。	从客户端重新开始连接。

工具结果

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

代码	含义	处理方法
`SNAPSHOT_NOT_READY`	删除或恢复前创建的安全 snapshot仍在生成中。没有执行任何操作。	客户端会在大约 2 分钟后使用相同的参数重试。
`MISSING_SCOPE`	此调用需要密钥没有的权限范围，例如查看数据库指标所需的 `databases:read`。	使用带有该权限范围的密钥。
`RESOURCE_NOT_ALLOWED`	密钥被限定到其他应用和数据库，或者它涵盖的资源中没有该名称。	使用涵盖该资源的密钥。
`TOOL_RATE_LIMITED`	达到了某个限制。	等待摘要中给出的时间。
`TOOL_EXECUTION_FAILED`	同一工具连续两次触及限制，或执行失败。	等待几分钟或使用控制面板。
`APP_NOT_FOUND`、`DATABASE_NOT_FOUND`	没有与该名称或 ID 匹配的应用或数据库。	让客户端先列出它们。

密钥无法使用的工具或不存在的工具会返回 JSON-RPC 错误 -32602 Unknown tool。请检查密钥的权限范围。其他代码来自工具本身，summary 会对其进行说明。

CLI

VS Code

MCP

SDKs

限制

TOOL_RATE_LIMITED

错误

HTTP 错误

连接时

工具结果

​限制

​TOOL_RATE_LIMITED

​错误

​HTTP 错误

​连接时

​工具结果

限制

TOOL_RATE_LIMITED

错误

HTTP 错误

连接时

工具结果