背景概述

火山引擎 PostgreSQL CLI 提供基于 Model Context Protocol（MCP）的 PostgreSQL 资源访问能力。AI Agent 可以通过 MCP 查询AI 原生 BaaS 平台 Supabase 版 PostgreSQL 引擎的Workspace、Branch、 Compute、Database、Role 和 Operation，而不需要自行实现火山引擎 API 的认证、签名和资源关联逻辑。

MCP Server 通过标准输入输出（stdio）与 MCP Client 通信：

当前 CLI 提供的是 stdio MCP Server，不直接启动 HTTP 或 SSE MCP 服务。

核心能力

资源发现：分页查询当前账号可访问的 PostgreSQL Workspace。

工作区查询：读取 Workspace 详情和 Operation 记录。

分支查询：分页查询 Branch，或读取指定 Branch 详情。

数据库资源：查询 Branch 下的 Compute、Database 和 Role。

范围收敛：启动时设置默认 Workspace，减少 Agent 重复传参。

认证复用：复用 CLI 已保存的 Console Login、AK/SK Profile 或进程环境变量，不在 MCP 配置中重复保存凭证。

准备工作

开始前请确认：

本机已安装 Node.js 和 npm。

当前账号具备访问火山引擎 AIDAP PostgreSQL API 的权限。

byted-postgresql-cli 已加入 PATH，AI 客户端能够直接启动该命令。

AI 客户端支持本地 stdio 类型的 MCP Server。

安装认证

安装 CLI

配置认证

推荐使用浏览器 Console Login：

也可以配置 AK/SK Profile：

自动化环境可以通过环境变量提供凭证：

MCP Server 在启动握手阶段不会预先访问云端；凭证缺失或权限不足通常会在首次业务工具调用时返回。凭证解析优先使用进程环境变量，其次使用选中的 ~/.volcengine/config.json Profile；地域优先级为命令行 --region、环境变量、Profile，未设置时默认为 cn-beijing。

版本更新

启动服务

最小启动命令如下：

该命令会持续等待 MCP 客户端通过 stdin 发送请求。在普通终端直接执行后没有交互输出属于正常现象；推荐将它配置到 AI 客户端，由客户端负责启动和管理进程。

如需指定 Profile、地域和默认 Workspace：

参数	默认值	说明
--workspace-id	未设置	为需要 Workspace 的工具提供默认值。工具显式传入 workspace_id 时，以工具入参为准。
--read-only	false	声明仅暴露只读工具。当前版本的 8 个业务工具本身全部只读，因此是否设置该参数不会改变工具列表；建议在 AI 客户端配置中保留，以明确安全意图并兼容后续版本。
--profile	当前 Profile	选择 ~/.volcengine/config.json 中的凭证 Profile。
--region	环境变量、Profile 或 cn-beijing	指定火山引擎地域。
--debug	false	启用调试日志。排障时使用，避免将日志或敏感信息分享给无关人员。

协议方法

MCP 协议方法由所使用的 MCP SDK 实现，AI 客户端通常会自动完成调用。常见生命周期包括：

协议方法	用途
initialize	建立会话并协商协议版本、服务端信息和能力。该阶段不要求先完成云端 API 请求。
notifications/initialized	客户端通知服务端初始化已经完成。
tools/list	获取当前 Server 暴露的工具及其输入 Schema。
tools/call	调用具体 PostgreSQL 业务工具并获取结构化 JSON 结果或错误。

协议方法与下文业务工具是两个层次：前者负责 MCP 会话和工具调用机制，后者负责具体的 PostgreSQL 资源查询。

工具列表

当前版本提供以下 8 个只读业务工具：

Tool	读写	主要入参	说明
workspaces_list	只读	project_name、search、limit、offset	分页列出当前账号可访问的 PostgreSQL Workspace，可按 Project 名称、Workspace 名称或 ID 筛选。
workspace_get	只读	workspace_id	查询指定 Workspace 的详细信息。未传时可使用 Server 启动参数中的默认 Workspace。
branches_list	只读	workspace_id、search、limit、offset	分页列出 Workspace 下的 Branch，可按名称或 ID 筛选。
branch_get	只读	workspace_id、branch_id	查询指定 Branch 的详细信息；branch_id 必填。
computes_list	只读	workspace_id、branch_id	列出 Branch 下的 PostgreSQL Compute。省略 branch_id 时自动解析默认 Branch。
databases_list	只读	workspace_id、branch_id	列出 Branch 下的 Database。省略 branch_id 时自动解析默认 Branch。
roles_list	只读	workspace_id、branch_id	列出 Branch 下的数据库 Role。省略 branch_id 时自动解析默认 Branch。
operations_list	只读	workspace_id	列出 PostgreSQL Workspace 的 Operation 记录；未传时使用 Server 启动参数中的默认 Workspace。

分页规则

workspaces_list 和 branches_list 支持 search、limit 和 offset。

limit 默认返回 10 条，最大 100 条；工具显式传入 limit=0 时返回上限 100 条。

分页响应包含 total、limit、offset、has_more 和可选的 next_offset。

单次工具响应上限为 256 KiB；结果过大时应缩小分页大小或增加筛选条件。

接入方式

通用配置

Cursor、Trae、Claude Desktop 和 Windsurf 等采用 mcpServers 结构的客户端，可以使用以下最小配置：

如果希望减少 Agent 每次调用时传入 Workspace，可追加 --workspace-id：

优先让客户端通过 PATH 解析 byted-postgresql-cli。只有客户端无法继承 Shell PATH 时，才将 command 改为实际可执行文件的绝对路径。

Trae

打开 Trae 的 MCP 设置，新增本地 stdio Server，将上面的通用配置写入 mcp.json，保存后刷新 MCP Server。

保存后刷新 MCP 服务，在新会话中询问“列出当前 Workspace 的 Branch”，验证 Agent 是否可以发现并调用 PostgreSQL 工具。

在 Trae 的 MCP 设置中新增本地 stdio 服务。

Cursor

在 Cursor 的 MCP 配置中新增 volcengine-postgresql，使用上面的 mcpServers 配置。保存后重载窗口或刷新 MCP Server。

VS Code

VS Code 使用 servers，并要求显式声明 type: "stdio"。可在项目的的 mcp.json 中配置：

Claude Code

可以使用 Claude Code 命令注册用户级 stdio Server：

自研 Agent

自研 Agent Runtime 需要将 byted-postgresql-cli mcp serve 作为子进程启动，并保持 stdin、stdout 与进程生命周期可用。不要在 CLI 与 Agent 之间增加会修改 stdout 的 Shell 包装器，也不要给 MCP 命令追加 --json 或将普通日志写入 stdout，否则可能破坏 JSON-RPC 帧。

使用示例

查询工作区

查询分支资源

查询操作记录

当前工具不支持执行 SQL。若用户要求查询表数据、修改 Schema 或创建资源，Agent 应明确说明 MCP 能力边界，不得把只读资源查询误解为数据库数据面操作。

验证流程

执行 byted-postgresql-cli --version，确认 CLI 可被 PATH 解析。

执行 byted-postgresql-cli status，确认认证状态和地域正确。

在 AI 客户端中添加 stdio 配置并刷新 MCP Server。

检查客户端是否显示 volcengine-postgresql 已连接，并发现 8 个工具。

在新会话中询问“列出我可以访问的 PostgreSQL Workspace”。

确认 Agent 调用了 workspaces_list，并返回包含分页元数据的结构化结果。

常见问题

现象	处理方式
客户端提示找不到命令	先在同一用户环境执行 byted-postgresql-cli --version。若客户端没有继承 Shell PATH，再将配置中的 command 改为可执行文件绝对路径。
Server 启动后终端一直等待	这是 stdio Server 的正常行为。不要手工交互，改由 MCP 客户端启动进程。
初始化成功但工具调用提示缺少凭证	运行 byted-postgresql-cli login 或 configure set，再用 status 验证。若客户端环境与终端不同，确认客户端进程可读取同一用户的 ~/.volcengine。
提示 workspace_id is required	在工具调用中提供 workspace_id，或在 Server 启动参数中增加 --workspace-id <workspace-id>。
工具数量不是 8 个	确认客户端启动的是当前 byted-postgresql-cli，执行 byted-postgresql-cli --version 并重启客户端。工具集合可能随后续版本演进，以客户端实时 tools/list 为准。
返回结果过大	对 workspaces_list 或 branches_list 使用更小的 limit，并结合 search、project_name 和 offset 分页查询。