MCP 服务器

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

什么是 MCP

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

sh0 包含一个内置 MCP 服务器，通过 Streamable HTTP 传输暴露在 POST /api/v1/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/api/v1/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/api/v1/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/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer sh0_your_api_key"
      }
    }
  }
}

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

Tip

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

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

API 密钥作用域

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

作用域	工具	描述
`read`	45 个读取工具	列出和检查应用、服务、域名、日志和指标。不允许修改。
`deploy`	读取 + 部署	包含 read 的全部权限，另可对已有应用执行部署、回滚、重启、启动、停止和扩缩容。不能创建或删除应用、修改其配置或域名、执行命令或创建 API 密钥。
`admin`	全部 106 个工具	完全访问：创建应用（`create_app`、`upload_app`、`deploy_template`、`deploy_compose`）、沙箱工具、服务器设置、用户管理、备份和破坏性操作。任何密钥（包括 admin 密钥）都不能创建新的 API 密钥。

要创建 API 密钥，请在面板中打开 设置 → API 密钥。根据 AI 需要执行的操作选择权限范围。对于已有应用的日常工作，deploy 在能力与安全之间取得了合适的平衡。v1.10.2 之前以 standard 范围创建的密钥将按 deploy 处理。

Warning

仅当 AI 需要创建或删除应用、修改配置或执行命令时才使用 admin 范围。部署和重启已有应用推荐使用 deploy。

自动发现

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

所有密钥看到的列表相同：tools/list 返回全部 106 个工具（45 个读取、45 个写入、16 个破坏性）。密钥的权限范围在调用工具时检查：read 密钥调用写入工具会收到 “API key scope 'read' cannot execute 'write' risk tools”。

会话管理

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 客户端以创建新会话。

入门指南

AI 沙箱