连接 MCP 客户端

hs-sql-agent 在 /mcp 提供 Streamable HTTP MCP 端点。使用内置管理界面时，正常的接入方式不是手动拼 endpoint 和 header，而是在签发密钥后直接复制 hs-sql-agent 生成好的 MCP 客户端配置。

推荐接入流程

1. 签发 MCP 密钥

   进入 Runtime → MCP Keys，为目标数据库创建密钥，并只开放客户端真正需要的工具和表。

2. 使用一次性的 Save and connect 对话框

   点击 Issue Key 成功后，hs-sql-agent 会立即显示明文密钥和生成好的客户端配置。这是管理界面唯一能取得该明文值的时机。

3. 选择 MCP 客户端并复制配置

   切换到 Claude Desktop、Cursor、Visual Studio Code 或 Generic HTTP 标签页，再点击对应的 Copy … config。复制出的 JSON 已经包含 MCP endpoint 和 X-MCP-Server-Key，不需要手动再拼请求头。

4. 粘贴到客户端并验证

   把复制的 JSON 粘贴进 MCP 客户端配置后连接。如果这把密钥可以执行 DML，生产使用前还要验证 form Elicitation 的拒绝和接受两条流程。

生成配置时使用的公开端点

客户端配置中的 URL 来自服务器的公开端点设置：

{
  "Mcp": {
    "PublicEndpoint": "https://sql-agent.example.com/mcp"
  }
}

对应的环境变量是 Mcp__PublicEndpoint；项目提供的 Compose 配置会把 MCP_PUBLIC_ENDPOINT 映射到这个值。

生产环境请在签发正式 MCP 密钥之前先把它设置为客户端真正能访问、且包含 /mcp 的 URL。管理界面会从 GET /api/runtime/client-config 读取该值，并直接放进复制出的配置。

对话框目前会生成什么

Issue、Rotate 或 Duplicate 成功后，当前管理界面提供四种配置：

• Claude Desktop — 直接 HTTP 的 mcpServers 项；
• Cursor — HTTP mcpServers 项；
• Visual Studio Code — servers 项；
• Generic HTTP — Streamable HTTP 连接对象。

四种输出都会带入服务器配置的 endpoint 和本次生成的 MCP 密钥。一般不需要手动重建这些 JSON。

Generic / 手动验证参考

如果某个 MCP 客户端需要不同的外层配置格式，可以使用 Generic HTTP 标签页作为参考。协议层的验证方式是：

X-MCP-Server-Key: <MCP key>

DML 兼容性需要单独确认

成功连接 /mcp，不代表客户端支持 DML 审批。

execute_dml_sql 和已发布的 DML Custom Tools 需要 form Elicitation。生产环境允许 DML 前，请使用实际安装的客户端版本验证以下两种情况：

1. 拒绝 Elicitation 请求，确认数据修改没有提交。
2. 接受 Elicitation 请求，确认只有已批准的数据修改能够完成。

接下来阅读