> ## 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 权限与安全

> 权限范围和受限 API 密钥如何决定 AI 客户端在 Square Cloud MCP 服务器上能做什么，删除和恢复如何保留安全 snapshot，以及活动记录。

对 MCP 服务器的每个请求都携带一个密钥：Claude 或 ChatGPT 在你授权时获得的密钥，或你创建的 [API 密钥](https://docs.squarecloud.app/zh/mcp/connect.md#创建-api-密钥)。密钥需要 `mcp` 权限范围才能连接，其他权限范围决定客户端能看到哪些[工具](https://docs.squarecloud.app/zh/mcp/tools.md)。密钥权限范围之外的工具不会被列出，调用它会被当作未知工具处理。

## 权限范围

| 权限范围 | 解锁的工具 |
| - | - |
| `mcp` | 连接所必需。仅凭它即可使用无需其他权限范围的工具：`get_platform_knowledge`、`search_help_center`、`list_help_center`、`get_platform_status` 和 `get_discord_status`。 |
| `apps:read` | `list_applications`、`get_application_status`、`get_all_applications_status`、`get_application_logs`、`get_deployments`、`get_metrics_history`（应用）、`list_account_domains`、`list_dns_records`、`get_network_analytics`、`get_network_errors`、`get_network_performance`、`get_network_logs` |
| `apps:control` | `start_application`、`stop_application`、`restart_application` |
| `apps:write` | `create_application`、`upload_application`、`purge_network_cache`、`set_custom_domain`、`delete_application` |
| `files:read` | `list_files`、`read_file`、`search_files` |
| `files:write` | `create_file`、`edit_file`、`patch_file`、`rename_file`、`delete_file`、`edit_config_file`、`commit_application` |
| `envs:read` | `list_env_vars` |
| `envs:write` | `set_env_vars`；与 `databases:credentials` 一起时：`connect_database`、`rotate_database_credentials` 以及带 `connect_to_app` 的 `create_database` |
| `snapshots:read` | `list_snapshots` |
| `snapshots:write` | `create_snapshot`、`restore_snapshot`，以及带 `snapshot` 的 `commit_application` |
| `databases:read` | `list_databases`、`get_metrics_history`（数据库） |
| `databases:write` | `create_database`、`start_database`、`stop_database`、`update_database`、`delete_database` |
| `databases:credentials` | 与 `envs:write` 一起时：`connect_database`、`rotate_database_credentials` 以及带 `connect_to_app` 的 `create_database` |
| `workspaces:manage` | `list_workspaces` |

有些调用会根据参数检查权限范围。`get_metrics_history` 用于应用时需要 `apps:read`，用于数据库时需要 `databases:read`。带 `connect_to_app` 的 `create_database` 还需要 `databases:credentials` 和 `envs:write`，带 `restart` 的 `set_env_vars` 还需要 `apps:control`，带 `snapshot` 的 `commit_application` 还需要 `snapshots:write`。缺少所需的权限范围时，该调用会返回 `MISSING_SCOPE`，且不会执行任何操作。

Claude 和 ChatGPT 会请求上述所有权限范围。在 Square Cloud 授权页面上，你可以取消勾选其中除 `mcp` 以外的任何一项，但永远无法添加新的权限范围。连接永远不会获得 `account:read`、`apps:deploy`、`ai:chat` 或 Blob Storage 的权限范围，因为没有任何 MCP 工具使用它们。

> [!WARNING]
>
> 有些权限范围的影响超出其名称所示。`files:write` 会更改应用运行的代码，`envs:write` 会更改其配置和机密信息，`databases:credentials` 会轮换数据库密码。只给客户端授予它所需的权限：如需只读访问，请使用 `mcp` 加上各个 `:read` 权限范围。

## 限定到应用和数据库的密钥

[API 密钥](https://docs.squarecloud.app/zh/api-reference/authentication.md#将密钥限定到特定资源)可以限定到部分应用和数据库。通过 MCP 使用时，这样的密钥：

* **只能访问这些资源。** 指定其他任何应用或数据库的调用都会在执行前返回 `RESOURCE_NOT_ALLOWED`，`list_applications` 和 `list_databases` 也只返回该密钥的资源。
* **无法使用账户级工具：** `get_all_applications_status`、`list_account_domains`、`list_workspaces`、`create_application`、`upload_application`、`create_database`、`connect_database` 和 `rotate_database_credentials`（轮换会更新使用该数据库的每个应用）。
* **必须指定目标：** `list_snapshots` 和 `restore_snapshot` 需要指定应用或数据库，因为账户级概览涵盖了密钥范围之外的资源。

Claude 和 ChatGPT 的连接涵盖整个账户。若要将 AI 客户端限制在部分应用上，请使用受限 API 密钥连接它。

## 所有更改都会立即执行

所有工具都会在第一次调用时直接执行，包括删除应用或数据库以及恢复 snapshot。Square Cloud 不会事先询问你：何时调用工具由你的 AI 客户端决定。每个工具都会告诉客户端它是只读的还是可能造成破坏，大多数客户端在调用破坏性工具前会征求你的许可：请保持该提示开启。

## 删除与恢复

`delete_application`、`delete_database` 和 `restore_snapshot` 无法撤销，因此 Square Cloud 会在执行前为应用或数据库创建一个安全 snapshot，除非最近几分钟内已有 snapshot。结果中的 `safety_snapshot` 会说明属于哪种情况：

| `status` | 含义 |
| - | - |
| `created` | 已创建安全 snapshot。 |
| `recent` | 最近几分钟内已有 snapshot。 |
| `none` | 无法创建 snapshot，操作仍然照常执行。当你套餐的每日 snapshot 上限已用完时，`reason` 为 `daily_limit`，否则为 `failed`。 |

在安全 snapshot 仍在生成期间，不会执行任何操作：调用会返回 `SNAPSHOT_NOT_READY`，客户端会在大约 2 分钟后使用相同的参数重试。

安全 snapshot 会计入你套餐的每日 snapshot 上限。删除后，它会保留在控制面板中，可以下载并作为新应用上传：`restore_snapshot` 只能恢复仍然存在的应用和数据库。

## 机密信息

* `list_env_vars` 只返回变量名，对于连接 URL 只返回其协议和主机。
* 文件工具永远不会读取、写入或删除 `.env` 文件（包括 `*.env`、`.env-*` 和 `.envrc`；可以读取 `.env.example` 这样的模板），也永远不会读取私钥或证书（`.pem`、`.key`、`.p12`、`.pfx`、`.ppk`、`.jks` 以及 `id_rsa` 这类 SSH 密钥）。
* 应用日志中识别出的机密信息会被遮盖。
* 永远不会发送 snapshot 和证书的下载链接。

> [!NOTE]
>
> 应用的日志和文件是模型会读取的内容，其中的文字可能试图操纵模型。在允许之前，请仔细检查客户端的提议。

## 活动记录

通过 MCP 进行的更改会出现在你的[活动记录](https://squarecloud.app/zh/dashboard/activity)中（Standard 及以上套餐），来源标记为 **MCP**，操作名称与控制面板中相同：重启、文件上传、环境变量更改。读取操作不会被记录。授权 Claude 或 ChatGPT 会显示为一次客户端授权。


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