> ## 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.

# 将 AI 客户端连接到 Square Cloud MCP 服务器

> 使用 OAuth 连接 Claude 和 ChatGPT，或使用 API 密钥连接 Claude Code、VS Code 和 Cursor，接入 Square Cloud MCP 服务器，并了解连接的有效期。

所有客户端都使用同一个地址 `https://mcp.squarecloud.app/mcp`。登录方式取决于客户端：

| 客户端 | 连接方式 |
| - | - |
| [Claude](#claude)（claude.ai 和 Claude 应用） | OAuth：粘贴地址并在 Square Cloud 上授权 |
| [ChatGPT](#chatgpt) | OAuth：粘贴地址并在 Square Cloud 上授权 |
| [Claude Code](#claude-code) | 在 `Authorization` 请求头中发送 [API 密钥](#创建-api-密钥) |
| [VS Code](#vs-code) | 在 `Authorization` 请求头中发送 [API 密钥](#创建-api-密钥) |
| [Cursor](#cursor) | 在 `Authorization` 请求头中发送 [API 密钥](#创建-api-密钥) |
| [其他客户端](#其他客户端) | 在 `Authorization` 请求头中发送 [API 密钥](#创建-api-密钥) |

两种方式都要求你的账户拥有有效的[套餐](https://docs.squarecloud.app/zh/platform/plans.md)。

## Claude

**1. 添加自定义连接器**

在 Claude 中，打开 **Customize > Connectors**，点击 **+ Add**，然后点击 **Add custom connector**。在 Team 和 Enterprise 套餐中，需要先由组织所有者在 **Organization settings > Connectors**（**Add > Custom > Web**）中添加，然后每位成员再从 **Customize > Connectors** 连接它。

**2. 输入地址**

将其命名为 `Square Cloud`，输入 `https://mcp.squarecloud.app/mcp`，然后点击 **Continue**。

**3. 保留 Claude 自己的身份**

保留一个登录选项（**Sign in now** 或 **Sign in when needed**），并将 OAuth 客户端设为 **Use Claude's published identity (Recommended)**。将 **Request headers** 留空，然后点击 **Add**。

**4. 在 Square Cloud 上授权**

Claude 会打开一个 Square Cloud 页面。如有需要请先登录，查看 Claude 请求的权限，然后点击授权。你可以取消勾选部分权限，减少 Claude 的访问权限；`mcp` 始终保留，因为连接靠的就是它。

**5. 在聊天中使用**

回到 Claude，点击聊天框中的 **+**，打开 **Connectors** 并开启 **Square Cloud**。

> [!NOTE]
>
> Square Cloud 只接受 Claude 的公开身份。**Register automatically** 和 **Use your own OAuth client** 在这里都无法使用。

## ChatGPT

**1. 添加自定义 MCP 服务器**

打开 [ChatGPT Plugins](https://chatgpt.com/plugins)，选择 **+**，然后选择 **Add custom MCP server**。视你的 ChatGPT 套餐而定，可能需要 workspace 管理员先允许自定义 MCP 服务器。

**2. 输入地址**

将其命名为 `Square Cloud`，连接方式选择公开端点，并输入 `https://mcp.squarecloud.app/mcp`。身份验证选择 OAuth。

**3. 创建**

查看警告，选择 **I understand and want to continue**，然后选择 **Create as a plugin**。

**4. 在 Square Cloud 上授权**

当 ChatGPT 要求你登录时，它会打开一个 Square Cloud 页面。如有需要请先登录，查看权限，然后点击授权。你可以取消勾选部分权限；`mcp` 始终保留。

**5. 在聊天中使用**

开始一个新对话，输入 `@` 并选择 **Square Cloud**。

> [!NOTE]
>
> ChatGPT 会不时更改这些菜单的名称。如果名称不同，请按照 [OpenAI 关于连接 MCP 服务器的指南](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt)操作。

## Claude Code

Claude Code 通过请求头中的 [API 密钥](#创建-api-密钥)连接，而不是通过 OAuth。将密钥保存在 `SQUARECLOUD_API_KEY` 环境变量中，然后运行：

```bash theme={"system"}
claude mcp add --transport http squarecloud https://mcp.squarecloud.app/mcp \
  --header "Authorization: Bearer $SQUARECLOUD_API_KEY"
```

运行命令时，你的 shell 会填入密钥，Claude Code 会将其保存在自己的配置中。若要在项目中共享该服务器而不共享密钥，请改为将其添加到项目的 `.mcp.json` 中；Claude Code 每次启动时都会读取该变量：

```json .mcp.json theme={"system"}
{
  "mcpServers": {
    "squarecloud": {
      "type": "http",
      "url": "https://mcp.squarecloud.app/mcp",
      "headers": {
        "Authorization": "Bearer ${SQUARECLOUD_API_KEY}"
      }
    }
  }
}
```

使用 `claude mcp list`，或在 Claude Code 中使用 `/mcp` 检查连接。

## VS Code

将服务器添加到项目中的 `.vscode/mcp.json`，或通过命令面板中的 **MCP: Open User Configuration** 添加到你的用户配置中：

```json .vscode/mcp.json theme={"system"}
{
  "inputs": [
    {
      "type": "promptString",
      "id": "squarecloud-api-key",
      "description": "Square Cloud API key",
      "password": true
    }
  ],
  "servers": {
    "squarecloud": {
      "type": "http",
      "url": "https://mcp.squarecloud.app/mcp",
      "headers": {
        "Authorization": "Bearer ${input:squarecloud-api-key}"
      }
    }
  }
}
```

VS Code 会在服务器启动时询问 [API 密钥](#创建-api-密钥)，因此密钥永远不会写在文件里。使用 **MCP: List Servers** 启动、停止或重启服务器。

> [!TIP]
>
> 这与[适用于 VS Code 的 Square Cloud 扩展](https://docs.squarecloud.app/zh/vscode-extension/installation.md)是两回事，后者在侧边栏中管理你的应用。两者可以同时使用。

## Cursor

将服务器添加到项目中的 `.cursor/mcp.json`，或添加到 `~/.cursor/mcp.json` 以用于所有项目：

```json .cursor/mcp.json theme={"system"}
{
  "mcpServers": {
    "squarecloud": {
      "url": "https://mcp.squarecloud.app/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SQUARECLOUD_API_KEY}"
      }
    }
  }
}
```

打开 Cursor 之前，请在环境中设置 `SQUARECLOUD_API_KEY`。在 Cursor 的 **Customize** 菜单中开启该服务器；如果无法连接，输出面板中的 **MCP Logs** 频道会显示原因。

## 其他客户端

任何支持通过 Streamable HTTP 连接远程 MCP 服务器并可设置自定义请求头的客户端，都可以用同样的方式连接：使用地址 `https://mcp.squarecloud.app/mcp`，并在 `Authorization` 请求头中发送 API 密钥。`Bearer ` 前缀是可选的。

```http theme={"system"}
Authorization: Bearer <your API key>
```

## 创建 API 密钥

在你的[账户安全设置](https://squarecloud.app/zh/account/security)中创建密钥：

* **为其授予 `mcp` 权限范围**，以及你希望客户端使用的工具所需的权限范围。完全访问权限的密钥也可以。参见[权限范围](https://docs.squarecloud.app/zh/mcp/permissions-and-safety.md#权限范围)。
* **如需只读访问**，请选择 `mcp`、`apps:read`、`files:read`、`envs:read`、`snapshots:read` 和 `databases:read`。
* **如需将客户端限制在部分应用和数据库**，请将密钥限定到这些资源。参见[受限密钥](https://docs.squarecloud.app/zh/mcp/permissions-and-safety.md#限定到应用和数据库的密钥)。

密文只会显示一次。请将其保存在环境变量或客户端的机密存储中，切勿放在聊天中或你会 commit 的文件里。你创建的密钥不会过期：不再使用时请吊销它。每个账户最多可拥有 10 个密钥。

## 连接的有效期

**Claude 和 ChatGPT（OAuth）。** 授权会为该客户端创建一个以其命名的 API 密钥（`Claude` 或 `ChatGPT`）：

* 有效期为 **90 天**，且没有刷新令牌。过期后，客户端会要求你重新登录并授权。
* 它只能在 MCP 服务器上使用。在 REST API 上会返回 `403 MISSING_SCOPE`。
* **再次连接同一客户端会吊销其之前的密钥。** 每个账户只保留一个 Claude 连接和一个 ChatGPT 连接，因此连接第二个 Claude 账户会断开第一个。

如需同时保留多个连接，请为每个额外的连接单独提供一个 API 密钥。在 Claude 中，自定义连接器也可以发送 API 密钥：在 **Authentication** 下选择 **No sign in**，并在 **Request headers** 下添加 `Authorization` 请求头。在 Team 和 Enterprise 套餐中，使用该连接器的每个人都共享该密钥的访问权限。

**你创建的 API 密钥**不会过期。无论以何种方式接入，同一账户的所有 MCP 连接都共享相同的[限制](https://docs.squarecloud.app/zh/mcp/limits-and-errors.md)。

## 断开连接

在你的[账户安全设置](https://squarecloud.app/zh/account/security)中吊销密钥：OAuth 连接对应 `Claude` 或 `ChatGPT` 密钥，其他连接对应你创建的密钥。访问会在客户端的下一个请求时终止。在客户端中移除连接器或服务器会让它停止调用，但只有在 Square Cloud 上吊销密钥才能使其失效。


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