Bytebase MCP 访问策略的 Disabled、Read-only 与 Read-write 三种模式怎么选？

Bytebase MCP 访问策略的 Disabled、Read-only 与 Read-write 三种模式怎么选？

【免费下载链接】bytebaseDatabase governance built for humans and agents — controlling changes and access across every major database.项目地址: https://gitcode.com/GitHub_Trending/by/bytebase

Bytebase 的 MCP 集成页里有一个 Access policy（访问策略）设置，管理员需要在 Disabled、Read-only 和 Read-write 三种模式之间选一个。它决定的是"工作区内任何 MCP 会话最多能做什么"——这是一个上限（ceiling），不是权限：模式本身不授予也不收回任何权限，每个 MCP 会话最终还能做什么，同时受连接用户自身 RBAC 权限的约束。选错方向，要么把数据库变更能力放给了不该有的 agent，要么让本可以只读探索的同事连不进来。这篇文章基于仓库内的设计文档与实现代码，给出每种模式实际放开了哪些能力、如何设置、以及如何验证设置已生效。

三种模式各自放开了什么

Bytebase 后端把每个 v1 API 方法标记为 READ、WRITE、FORBIDDEN 或 EXCLUDED 四类，天花板门禁（ceiling gate）按模式放行方法类别。放行表在 mcp_gate.go 中：

var mcpServingClasses = map[storepb.MCPSetting_Capability][]v1pb.MCPMethodClass{ storepb.MCPSetting_DISABLED: {}, storepb.MCPSetting_READ_ONLY: {v1pb.MCPMethodClass_READ}, storepb.MCPSetting_READ_WRITE: {v1pb.MCPMethodClass_READ, v1pb.MCPMethodClass_WRITE}, }

也就是说三种模式是严格嵌套的：Read-only 放行全部 READ 方法；Read-write 在此之上追加 WRITE 方法；Disabled 放行零个方法，任何 MCP 连接都会被拒绝（界面文案为 "No MCP session can connect to this workspace."）。

设计文档 把这三个模式能做的事整理成了一张 8 行能力表（read 3 行、write 5 行），可以把它当作选型时的对照清单：

Read-only 放开的（READ 层，共 56 个方法）：

• 读取 schema 与元数据：schemas、databases 与 instances、projects 与 database groups、catalogs、changelogs、revisions、SQL review 配置、自己的会话与工作区信息（31 个 READ 方法）
• 通过查询读取数据：执行只读查询、query history、saved queries 与 sheets（9 个 READ 方法）。这里有一条规则：如果请求中任何一条语句不是读，整个请求会被拒绝；只有在 PostgreSQL、CockroachDB 和 Redshift 上，数据库会话本身还会以只读方式打开，其他引擎仅按语句分类判断，而分类为读的语句仍可能调用有写副作用的函数——proto 注释把这一层称为 "classifier-enforced, not proven"
• 读取变更工作流：issues 与评论、plans 与 plan checks、rollouts、task runs 与日志、releases、回滚预览（16 个 READ 方法）

Read-write 追加的（WRITE 层，共 41 个方法 + 1 个语句级放开）：

• 提出变更：创建 sheets、创建和编辑 plans 与 issues、运行 plan checks 与 review、创建和删除 releases 与 revisions、生成 schema diff（22 个 WRITE 方法）。agent 永远无法批准自己的变更——批准类方法是 FORBIDDEN，是否需要人工批准由项目的审批策略（require_issue_approval）决定
• 运行 rollouts 与 tasks：CreateRollout、BatchRunTasks、BatchSkipTasks、BatchCancelTaskRuns（4 个 WRITE 方法），仍受项目审批策略约束
• 运行 DML 与 DDL 语句：INSERT、UPDATE、DELETE、CREATE、ALTER、DROP 经由查询执行。这一项对应的不是某个方法，而是mcp_sql_clamp.go中的语句级钳制——Read-write 把这道钳制放开
• 导出查询结果：SQLService/Export，数据会离开 Bytebase
• 管理数据库维护操作：同步 instances 与 databases、database 设置与标签、在 projects 间移动 databases、database groups、saved queries（14 个 WRITE 方法）

任何模式都不放开的（floor，121 个方法：35 个 FORBIDDEN + 86 个 EXCLUDED）：

Never, in any mode: approve issues, administer the workspace, or handle credentials.

FORBIDDEN 与 EXCLUDED 的区别值得管理员知道：FORBIDDEN 是"永远不会被任何 MCP 模式放行"（例如会发回登录 token 的方法、会驱动凭证重置流程的方法、四个审批方法）；EXCLUDED 是"本版本发布的不含工作区管理能力的模式都不放行，未来可能放行"（例如读取他人 SQL、以管理员凭证打开数据库连接的方法）。mcp_gate.go 中为每种拒绝原因维护了面向 agent 的说明文案，拒绝时 agent 会收到形如 "<procedure>is not available to MCP sessions because …" 的错误。

按团队角色做选型判断

设置页对每个模式给出的 "Best for" 描述（来自 en-US 文案，与 设计文档 中的 Copy 一节一致）：

模式	界面描述	Best for
Disabled	No MCP session can connect to this workspace.	keeping MCP off until you are ready to turn it on
Read-only	Sessions can explore schemas and run read-only queries. Bytebase classifies every statement before it runs and refuses a request whole if any statement is not a read. Where the engine's driver has one, the database session is opened read-only as well. How deep this goes varies by engine.	querying and exploring data, including by people who do not write SQL
Read-write	Sessions can also change data and schemas, as far as the connecting user's own permissions allow.	making database changes through an AI agent, still capped by each user's own permissions

据此，文档支撑的选型路径是：

1. 还没准备好让任何 AI 客户端接入（包括评估期、或者临时需要一键切断所有 agent 访问）：选 Disabled。它同时是工作区的 MCP kill switch——/mcp端点每次请求都会读这个设置，DISABLED 时连接直接被拒绝。
2. 用户只读（查询、探索 schema，尤其是"不写 SQL 的人"通过自然语言查数据）：选 Read-only。注意两个边界：写入语句会导致整个请求被拒；导出（Export）属于 WRITE 层，Read-only 下 agent 无法把查询结果下载为文件，数据不会经由 MCP 离开 Bytebase。
3. 需要 agent 执行数据库变更（提变更、跑 rollout、跑 DML/DDL）：选 Read-write。前提是你要接受两条事实：agent 的写操作上限是"用户自身权限 ∩ WRITE 方法集合"，数据导出被放开；但审批、工作区管理、凭证相关操作依然完全不可达。

两个模式之间不是功能开关而是包含关系，Read-write 并不替换 Read-only 的行为，只在其上追加 WRITE 层。

在哪里设置

这是工作区级设置，存储为独立的MCP设置项（setting.proto 中的MCPSetting）：

message MCPSetting { // Capability is the ceiling: a session runs at this level or lower. enum Capability { CAPABILITY_UNSPECIFIED = 0; // MCP connections are rejected. DISABLED = 1; // Was MCP_METADATA_ONLY; the Metadata-only tier is deferred out of the design. reserved 2; // MCP may inspect metadata and run read-only queries. (Enforced from P1b.) READ_ONLY = 3; // MCP may perform mutations, still bounded by the user's RBAC. READ_WRITE = 4; } Capability capability = 1; // Whether a request that arrived over MCP stops applying the caller's own // unmasking provisioning. bool ignore_masking_exemptions = 2; }

通过控制台设置的操作路径（对应 MCPAccessPolicySection.tsx）：

1. 打开工作区的 MCP Integration 页面，找到Access policy区块。该区块的描述是 "The most any MCP session may do in this workspace. Every session is also capped by the connecting user's own permissions."
2. 点击Edit policy。此按钮由PermissionGuard保护，需要bb.settings.set权限，普通成员看不到可用的编辑入口。
3. 在三张模式卡片中选择目标模式（Disabled / Read-only / Read-write），保存按钮仅在表单有实际改动时启用。
4. 可选：同页有Ignore masking exemptions开关。开启后，MCP 请求会忽略该用户的 masking 豁免与 access grant 携带的 unmask——有 masking 策略的列对 agent 保持脱敏。注意它的边界：它只在 Bytebase 本身做 masking 的引擎上有效，"where Bytebase does not mask, this changes nothing"；若工作区没有 Data masking 许可，页面会直接提示 "Data masking is not licensed for this workspace, so nothing is masked whatever this is set to."
5. 点击Save policy。保存成功后页面提示 "Policy saved. {模式} applies to every session's next request."

保存走的 API 是UpsertSetting：name为MCP设置项，更新value.mcp.capability（模式变化时）和value.mcp.ignore_masking_exemptions（开关变化时）两个 mask 路径，由 mcpPolicy.ts 中的MCP_CAPABILITY_CHOICES限定可选值就是上述三种。

验证设置已生效

文档与实现给出的可核对点按下面顺序检查：

1. 设置页状态行：保存后，Access policy 区块的 "In force" 行会显示模式徽章——Read-only 为 success（绿）、Read-write 为 warning（黄）、Disabled 为 destructive（红）。这是文档明确的展示规则（设计文档 D3）。
2. 连接层面：设为 Disabled 后，任何 MCP 连接被拒绝，界面上只剩一句 "No MCP session can connect to this workspace."。
3. 方法层面：在 Read-only 下让 agent 尝试一个 WRITE 操作（例如创建 sheet），会收到PermissionDenied错误，文案形如 "<procedure>is a WRITE method and this workspace's MCP capability ceiling is READ_ONLY, which serves READ methods. Ask a workspace admin to raise the MCP ceiling in the workspace settings, or perform this action signed in to the Bytebase console instead"。FORBIDDEN/EXCLUDED 方法的拒绝文案会附带具体原因。
4. 审计层：页面底部常驻一句 "MCP policy denials are recorded in the audit log." 策略拒绝（policy denial）无论目标方法是否带审计注解都会被记录；可以在审计日志中核对拒绝记录，确认门禁在按预期拦截。

两点关于生效时机的文档事实：天花板是逐请求实时读取、无缓存的，因此"天花板变化作用于每个正在运行的会话的下一个请求；agent 已被放行的工作会执行完"（页面文案：A ceiling change applies to the next request of every running session. Work an agent has already been admitted to runs to completion.）。收紧是立即的，但已放行的操作不会被中途撤销。

另外两个边界情况，设置页会明确报出：存储了当前版本无法解析的 capability 值时，所有 MCP 连接被拒绝，页面显示 "The stored access policy cannot be read" 并要求选择一个模式后保存来修复；读取失败（read-failed）时所有 MCP 连接同样被拒绝，先刷新重试，持续失败则说明存储的策略行无法解析，需要运维直接修复该行。

限制与不能做的事

• 三种模式都不能让 agent：批准 issue（四个审批方法 FORBIDDEN）、管理工作区（EXCLUDED）、接触任何凭证类方法（FORBIDDEN）。这一层与模式无关，是 MCP 边界的底线。
• 模式不是权限：effective = ceiling ∩ RBAC。Read-write 下的 agent 仍需要连接用户本身具备对应权限才能完成写操作；反过来，一个全权限用户在 Read-only 下同样无法写入。
• Read-only 的"只读"深度因引擎而异：PostgreSQL、CockroachDB、Redshift 之外，只靠语句分类保证，分类为读的语句仍可能调用有写副作用的函数。
• Read-write 下导出（Export）意味着查询结果可以离开 Bytebase；如果数据安全要求数据不出工作区，Read-only 是文档给出的边界。
• 目前只有这三种预设模式，自定义访问策略在设计文档中列为 out of scope（后续会让能力表的行变成可勾选的项，卡片变成预设按钮）。

设置本身就是一个随时可回退的开关：任何时候都可以把 Read-write 收紧回 Read-only 或 Disabled，作用于所有运行中会话的下一个请求，且收紧动作本身产生的拒绝会进入审计日志，便于事后核对谁在什么时候触到了边界。

【免费下载链接】bytebaseDatabase governance built for humans and agents — controlling changes and access across every major database.项目地址: https://gitcode.com/GitHub_Trending/by/bytebase