MCP 服务器

将 Claude Desktop、Claude Code、Cursor 或任何 MCP 兼容客户端连接到 sh0，通过自然语言管理您的部署。

什么是 MCP

Model Context Protocol (MCP) 是一个将 AI 助手连接到外部工具和数据源的开放标准。MCP 让您的 AI 助手可以直接与 sh0 交互——列出应用、读取日志、触发部署和诊断问题——而无需将终端输出复制粘贴到聊天窗口。

sh0 包含一个内置 MCP 服务器，通过 Streamable HTTP 传输暴露在 POST /mcp。任何支持 MCP 的客户端只需一个 URL 和一个 API 密钥即可连接。

连接 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件 ~/.claude/claude_desktop_config.json 中：

~/.claude/claude_desktop_config.json

{
  "mcpServers": {
    "sh0": {
      "type": "url",
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer sh0_your_api_key"
      }
    }
  }
}

将 your-server.com 替换为您的 sh0 服务器地址，将 sh0_your_api_key 替换为有效的 API 密钥。重启 Claude Desktop 以应用新配置。

连接 Claude Code

对于 Claude Code（CLI 版），将相同的配置添加到 ~/.claude.json 的 mcpServers 键下：

~/.claude.json

{
  "mcpServers": {
    "sh0": {
      "type": "url",
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer sh0_your_api_key"
      }
    }
  }
}

配置完成后，Claude Code 将在与提示相关时自动发现并使用 sh0 工具。

连接 Cursor

在 Cursor 中，打开 Settings → MCP 并使用相同的 JSON 配置添加新服务器：

Cursor MCP Settings

{
  "mcpServers": {
    "sh0": {
      "type": "url",
      "url": "https://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer sh0_your_api_key"
      }
    }
  }
}

三个客户端的配置完全相同。任何支持 Streamable HTTP 传输的 MCP 兼容工具都可以使用相同的 URL 和凭证。

Tip

您可以使用以下命令测试 MCP 连接：

curl -X POST https://your-server/mcp -H 'Authorization: Bearer sh0_xxx' -H 'Content-Type: application/json' -d 'undefined,"clientInfo":undefined}}'

API 密钥作用域

API 密钥控制 AI 助手可以访问哪些工具。每个密钥被分配一个决定其权限的作用域：

作用域	工具	描述
`read`	37 个工具	列出和检查应用、服务、域名、日志和指标。不允许修改。
`standard`	读取 + 写入	包含读取的所有功能，外加创建应用、触发部署、更新环境变量和管理域名。
`admin`	全部 103 个工具	完全访问权限，包括服务器设置、用户管理、备份操作和销毁操作。

要创建 API 密钥，请在控制台中导航至 Settings → API Keys。根据您需要 AI 执行的操作选择适当的作用域。对于大多数开发工作流，standard 提供了功能和安全之间的最佳平衡。

Warning

仅在 AI 需要执行服务器级操作时才使用 admin 作用域。日常开发建议使用 standard。

自动发现

所有 103 个工具会被 MCP 客户端自动发现。无需手动注册工具。当客户端连接时，它会调用 tools/list 方法，sh0 会响应完整的工具目录——名称、描述和 JSON Schema 参数定义。

工具列表会根据 API 密钥作用域进行过滤。read 作用域的密钥只能看到 37 个只读工具，而 admin 密钥可以看到全部 103 个。

会话管理

MCP 服务器使用会话在对话中的多个请求之间维护状态。每个会话由 initialize 调用后 Mcp-Session-Id 响应头中返回的 UUID v4 标识。

客户端必须在所有后续请求中包含此头部。会话详情：

ID 格式：UUID v4（例如 a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d）
TTL：1 小时无活动
清理：惰性清理——过期会话在创建新会话时被清理
作用域：每个会话继承初始化时使用的 API 密钥作用域

故障排除

连接 MCP 服务器时的常见问题：

连接被拒绝

验证 sh0 服务器正在运行且端口可访问。如果从本地网络外连接，请确保防火墙允许 sh0 API 端口（默认 9000）的入站流量。

需要 HTTPS

MCP 客户端通常要求远程连接使用 HTTPS。如果您通过互联网访问 sh0，请确保服务器有有效的 SSL 证书。连接到 localhost 或 127.0.0.1 的本地连接可以使用纯 HTTP。

工具未出现

如果连接成功但没有工具出现，API 密钥的作用域可能对您期望的工具来说太窄。请在 Settings → API Keys 中检查密钥的作用域。同时验证 Authorization 头的格式是否正确（Bearer sh0_...）。

会话已过期

会话在 1 小时无活动后过期。如果收到会话错误，客户端应自动重新初始化。如果没有，请重启 MCP 客户端以创建新会话。

Getting Started

AI Sandbox