Database governance built for humans and agents — controlling changes and access across every major database.
MCP access policy — show what a mode allows
Status: accepted · 2026-09-10
The MCP settings page offers three modes (Disabled, Read-only, Read-write) and describes each in
one sentence. Since #21324 removed the per-mode
method drawer, nothing on the page says what a mode actually serves, and an admin choosing between
Read-only and Read-write has nothing to compare beyond two sentences. The rule this doc lands on:
show capabilities, not methods or permissions — one ordered list of twelve capability rows in
which each mode is a prefix, collapsed by default inside the existing Access policy section, and
following the picked mode while editing. The page also gets shorter: the mode cards shrink to an
icon, a label and a three-word caption, with the selected mode's "Best for" under them; the
disclosure line is the mode's description, and row details sit behind one toggle. The product change
is frontend-only, with one comment added to the mcp_method_class annotation and its generated
output; keeping the row wording true to the method classification is a rule in AGENTS.md
rather than a lint (D11). A custom access policy is out of scope, but the list is shaped so that it
becomes that editor later without a redesign.
Problem
The page today (frontend/src/routes/workspace/mcp/MCPAccessPolicySection.tsx) shows, in view
state, an "In force" line with the mode chip, the mode's description, and two notes; in edit
state, three mode cards and a footer. The consent page
(frontend/src/routes/auth/MCPConsentCeiling.tsx) renders three prose lines for the same policy.
None of these says what an agent can do.
The drawer that used to answer this listed every served method grouped by service, with the
permission each declares, plus per-engine read-only depth and masking. It went with the
GetMCPInfo fields it read, because a large API whose only reader was one drawer was not worth
keeping, and because a list served by the backend and rendered by the frontend drifts. It also
answered the wrong question. An admin does not think in DatabaseService/GetDatabaseSDLSchema,
and comparing two modes meant opening two drawers.
The gap, as raised in review: some admins need to understand what each mode really allows. The
word "permissions" is itself the trap here. A mode never grants or removes a permission; the
ceiling gate (backend/api/v1/mcp_gate.go) removes methods by class before the permission check
runs, and under Read-only the SQL clamp removes statements. So the page has to say what an agent
can do, in the admin's words, and say it in a form that stays true after the next release.
A second problem surfaced once the list existed: the edit state carried about 375 words, most of them duplicated. The three mode cards described what the list already showed, and every row's detail line was visible whether or not anyone wanted it.
Principle
A capability is a verb phrase an admin recognizes, standing for an exact set of served methods. The three modes are nested, so one ordered list with two dividers shows all three at once, and the mode in force — or the mode being picked — is a highlighted prefix of that list.
What follows from it:
- The unit shown is a capability row, never a method, a permission, or a count.
- The list is the same in view and in edit. Editing changes which prefix is served, nothing else.
- Rows a mode does not serve stay visible and muted, so comparing modes never needs a second surface.
- What no mode serves is one line under the list, never a row.
- Nothing on the section is said twice. The mode name appears in the chip or the selector; the description in the disclosure line; the audience in the "Best for" line; the detail behind one toggle.
The rows
Twelve rows: four read, eight write. Each has a title and a one-line list of sub-items in plain words. The right column records which classified methods the row's wording has to cover; it is documentation for whoever rereads these rows after a classification change, and never appears in the product.
| Tier | Row | Sub-items shown | Classified methods the wording must cover |
|---|---|---|---|
| read | Read schemas and metadata | Schemas · Databases and instances · Projects and database groups · Catalogs, changelogs and revisions · SQL review configs · Your own session and workspace facts | 31 READ methods: DatabaseService reads, projects, instances, database groups, catalogs, changelogs, revisions, review configs, session facts |
| read | Read data by running queries | Run read-only queries · Under Read-only, a request is refused whole unless every statement is shown to be a read that returns data; how deeply that can be checked varies by engine, and on some engines no statement can be shown to be a read at all · Your own query history · Saved queries and sheets you have access to | 9 READ methods: SQLService/Query, query history (4), saved-query reads (3), GetSheet |
| read | Read the change workflow | Issues and comments · Plans and plan checks · Rollouts, task runs and logs · Releases · Rollback previews | 17 READ methods: issue, plan, rollout and release reads |
| read | Read members, roles and policies | Who holds which role in the workspace and its projects · Groups and their members · Roles and their permissions · Masking rules and exemptions · Rollout, data query, tag and review policies · Approval rules, environments, semantic types and data classification · Access grants, including pending requests | 13 READ methods: GetIamPolicy on projects and the workspace, group reads (3), role reads (2), GetPolicy, ListPolicies, access-grant reads (3, with SearchMyAccessGrants), and GetSetting, which the gate serves for those four settings only |
| — | Read-only stops here | 70 methods | |
| write | Propose changes | Create sheets · Create and edit plans and issues · Run plan checks and reviews · Create, delete and restore releases · Create and delete revisions · Generate schema diffs. The project's approval policy decides whether a change needs approval | 22 WRITE methods: sheet, plan, issue, release and revision writes, RequestIssue, RunReview, DiffSchema, DiffMetadata |
| write | Request access grants | Ask for a time-boxed grant to run a specific statement, optionally with results unmasked or exported; the statement must be a read as far as the engine can check it · The grant starts only after it is approved, and a request that would need no one's approval is refused · A grant applies only where the project allows access grants · Revoke an active grant · Turn a project's "Allow access grants" on or off, after the user confirms | 3 WRITE methods: AccessGrantService/CreateAccessGrant and RevokeAccessGrant, served like any WRITE method; and ProjectService/UpdateProject, served only through the set_just_in_time_access tool, which asks the user to confirm and changes only that setting |
| write | Grant or revoke masking exemptions | Exempt one member from masking for a database, a schema, a table or a column, or for every database in a project, with an optional expiry · Each exemption and each removal is confirmed in the user's MCP client before it is made · Exempted data shows unmasked in query and export results | 1 WRITE method: OrgPolicyService/UpdatePolicy, served only through the grant_masking_exemption and revoke_masking_exemption tools, which ask the user to confirm, then add one exemption entry or remove one member from the entries whose condition matches exactly; other policy types and CreatePolicy and DeletePolicy stay refused |
| write | Approve or reject issues | Each decision is confirmed in the user's MCP client before it is made · Role requests are decided in the console · The approval rules and the project's self-approval setting apply, as in the console | 2 WRITE methods: ApproveIssue, RejectIssue, served only through the decide_issue tool, which asks the user to confirm each decision and refuses role requests |
| write | Run rollouts and tasks | Create a rollout · Run, skip or cancel its tasks, under the project's approval policy | 4 WRITE methods: CreateRollout, BatchRunTasks, BatchSkipTasks, BatchCancelTaskRuns |
| write | Run DML and DDL statements | INSERT, UPDATE, DELETE, CREATE, ALTER, DROP through queries, as far as the engine and the user's own permissions allow · Where the user's MCP client supports confirmations, a query that is not a read as far as the engine can check it runs only after the user confirms it · In other clients such a query can run without asking | Not a method: the statement clamp in mcp_sql_clamp.go, which Read-write lifts. A statement Bytebase cannot show is a read runs only through the query_database tool, which asks the user to confirm it when the client can show the form (mcp_sql_write.go) |
| write | Export query results | Export results as files. Data leaves Bytebase | 1 WRITE method: SQLService/Export, which requires the user's own bb.sql.export on the data it reads, from a role or a matching export grant, and runs only statements Bytebase can show are reads |
| write | Manage database housekeeping | Sync instances and databases · Saved queries | 9 WRITE methods: sync, saved-query writes |
| — | Read-write stops here | 112 methods | |
| floor | Never, in any mode: administer the workspace, handle credentials, open an Admin mode session, or read anyone else's query history. | 108 methods: 34 FORBIDDEN, 74 EXCLUDED |
Every row is displayed under every mode — served, or muted with a — — and against every engine a
workspace happens to hold, so every line on this card must be true on both axes: mode and engine.
That covers the twelve rows, and equally the collapsed summary, the card captions and the "Best for"
lines, which are not rows and were missed the first time the rule was applied. The summary is the
line most admins read and often the only one. A
claim whose truth depends on the mode names the mode as a condition; a claim whose truth depends on
the engine says so without naming engines, because per-engine depth is out of scope for this card
(see below) and an enumeration goes stale the release a driver changes.
Both axes have caught lines here, and the engine axis caught the same line twice. On the mode axis,
the read-only clamp holds only under Read-only (mcpReadOnlyClampApplies), so without its qualifier
row 2 promised a whole-request refusal under Read-write while the DML and DDL row on the same screen
offered INSERT and DROP.
On the engine axis, three drafts failed in three different ways, and the shape of the failure is the
lesson. Naming engines (PostgreSQL, CockroachDB, Redshift) went stale against the Redshift datashare
carve-out and was outright false where an engine has no query validator: refuseNonReadOnlyStatement
bails before classification and refuses every statement, so Read-only serves no query there rather
than a shallowly-checked one. Replacing that with a universal — "queries stay read-only where
Bytebase does not gate per statement" — was false in the permissive direction, because the real
predicate is a conjunction (HasQueryValidator && !EngineSupportQueryNewACL) that the sentence
collapsed: on Databricks, outside the ACL set and with no validator, ValidateSQLForEditor returns
its permissive default and the write executes. mcp_sql_clamp.go carries a comment warning against
exactly that call, eight lines from where the clamp reads it.
So: state the bound, never the behavior. Where a claim's truth varies along an axis the card cannot enumerate, say what limits it — "as far as the engine and the user's own permissions allow", "how deeply that can be checked varies by engine" — and let the reader learn the specifics from the docs. An enumeration is wrong the release a driver changes; a universal is wrong the release an engine is added.
Two further axes were found in review, each after it had already shipped a false line.
Effect. A refusal is a claim about what a session can cause, not about which methods it can
call, and the two come apart wherever a permitted method has an effect no annotation names.
CreateIssue is an ordinary WRITE; startIssueWorkflow calls emitIssueCreated, and the webhook
manager posts the issue title and description to whatever endpoint the project configured
(backend/component/webhook/manager.go). A Read-write session can put anything it has read into a
description, so the floor's "never … send data to a third party" was false while every method it
reasoned about was classified correctly. Reasoning from the annotation set cannot find this; only
following the effect can. Check a claim about effects against effects, including the ones no
annotation names.
The same axis caught a second verb in the same sentence one round later, and the tell was
vocabulary. "Never … open an admin connection" reads as a denial-reason
(OPENS_AN_ADMIN_CONNECTION, carried only by AdminExecute and GetTaskRunSession) and is false as
plumbing: resolveDataSourceID falls through to the ADMIN data source for any instance with no
read-only one, in either mode, and sql_service.go opens it with
ReadOnly: clamped || type == READ_ONLY — so under Read-write an ordinary MCP query runs on the
admin data source, not read-only. A verb that names a mechanism is a claim about the plumbing and
has to be checked against the plumbing; name the feature the reader knows instead — here Admin
mode, which really is refused.
Complement. A conditional line also asserts something about its complement, and a reader takes
the reassuring half. "Where Bytebase cannot check a statement, it is not verified before it runs" is
true as written and implies that where Bytebase can check, it does — but Read-write leaves
mcpReadOnlyClampApplies false and skips validateQueryRequest for every engine in
EngineSupportQueryNewACL, so on PostgreSQL, the engine with the most complete parser, nothing
checks the statement at all. The conditional pointed its reassurance exactly where the product is
weakest. If negating the condition yields a promise the product does not keep, drop the condition
or state the bound unconditionally.
Dropping it unconditionally was the next round's defect, and the two rounds after that are the more
useful half of this entry. "This mode does not require a statement to be a read" is what the MCP
ceiling does — the clamp is off — but not what the product does: Query runs validateQueryRequest
under every mode for engines outside EngineSupportQueryNewACL, and 13 of those 14 have a
registered validator, so a Read-write session there is still refused a write. The repair for the
complement axis had removed the engine axis from the one line that carried it, on a screen that
renders no row details. A line being fixed on one axis is still a line, and has to be rechecked
against every axis — the one being repaired crowds out the rest.
Method. The replacement kept the engine axis and named a consequence — lifted where Bytebase can
check, refused where it cannot — and that is still one variable too few. Query and Export do not
share a gate: Query skips the check for the ten EngineSupportQueryNewACL engines, while Export
skips it only for MySQL. So on PostgreSQL under Read-write the same write runs through Query and is
refused through Export, and Export is a served row on the same card. The fourteenth engine breaks
it the other way: Databricks is outside the ACL set and registers no validator, so
ValidateSQLForEditor returns its permissive default, GetQuerySpan returns no spans, and the
access check falls back to bb.sql.select — a DELETE that runs unrefused, unclassified, and
authorized by a read permission. The same statement, mode and engine can get different answers from
different RPCs; a claim about what runs has to name the operation as well as the engine.
Four wordings later, the line states the bound and stops: "Capped by your own Bytebase permissions, and by what Bytebase supports for each database engine and each operation". Its Read-only sibling keeps a consequence because there the clamp really is one rule with one outcome. Parallelism between the two is broken on purpose.
Two choices in the wording are deliberate. Row 2 says Read data by running queries rather than "Run queries" so the verb stays Read and the sub-item carries the rule that keeps it true under Read-only. The DML and DDL row is not a method at all: it names the statement clamp being lifted, because that is a real difference between the modes that no method name shows, and a future custom policy will want it as its own switch.
Every sub-item names only what the served methods can do. Sheets are created, never edited: there
is no update RPC. Releases and revisions are created and deleted: ReleaseService/UpdateRelease is
classified WRITE but answers Unimplemented, and Revision has no update RPC, so "edit" would
advertise an operation that does not exist. Housekeeping once also named database settings and
labels, moving a database between projects, and database groups. Those five methods
(UpdateDatabase, BatchUpdateDatabases and the three database-group writes) are EXCLUDED now,
for REDRAWS_GOVERNANCE_BOUNDARY: a database's project and environment decide which approval, SQL
review and access rules apply to a change, and which masking rules decide what a query returns; its
environment, its labels and the group expressions decide which databases a change that targets a
group runs on. An agent that could edit them would choose the checks on its own changes. Row 2
states the depth of the read-only check because only PostgreSQL, CockroachDB and Redshift open the
database session read-only; elsewhere the clamp is statement classification alone, and a statement
that classifies as a read can still call a function that writes. The proto calls the ceiling
"classifier-enforced, not proven", and the row says so in the admin's words.
Approval is stated as the project's policy, never as a promise. The backend requires an approved
issue before a rollout only when the project has require_issue_approval on and an issue is linked
(backend/api/v1/rollout_service.go); the MCP-origin guard there refuses an issueless rollout only
under that same flag, and an issue whose approval finding produced no template counts as approved
with no human acting. The console turns the flag on for new projects; the API default is off. A row
that said "of an approved change" would therefore promise more than the gate enforces, and the
wording an admin reads while choosing Read-write is the wrong place to be generous. What holds
unconditionally is that no approval decision is made over MCP without a confirmation in the client.
A Read-write session approves or rejects an issue only through the decide_issue tool. The tool
decides database changes and access requests. It refuses role requests, because approving one grants
a project role, and role grants stay in the console with the rest of access administration. It asks
the user through MCP form elicitation, inside the same tool call, and acts only on an accepted form
with the box checked. A client that cannot show the form gets the issue's console link. The gate
serves ApproveIssue and RejectIssue only to a request that carries the confirmation, so
call_api is refused. The workflow then decides as it does for a person: the step's role, and the
project's self-approval and last-editor settings. Bytebase records the decision as confirmed in the
client, not as proof that a person clicked: a hook in the user's own client can answer the form, and
that is the user's choice. Re-checking an issue's approval and activating an access grant directly
stay FORBIDDEN, because each can let a request pass with no approver deciding it. That is the half
the rows state. Whether MCP-originated rollouts should require approval regardless of the project
flag is a product question tracked separately (BOT-71), not one this doc decides.
Access requests are the exception, and the request row states the approval unconditionally. An
approved access grant is active at once, so an MCP session's request that would count as approved
on creation, with no approval template or one that names no approver, is refused
before any row is written (refuseUnattendedMCPAccessGrant in
backend/api/v1/access_grant_service.go). The finding is saved on the request's issue at
creation, so an approval-rule edit afterwards cannot change it. Every other way a request becomes
active goes through an approver: in the console, or through decide_issue with a confirmation in
the client. Activating a grant directly stays FORBIDDEN to the session. The approver can be the
requester where the project allows self-approval; the rows promise an approval, not a second
person.
The DML and DDL row states its confirmation with a condition, because it works unlike the confirmed
tools: query_database asks before a query that may write only in a client that can show the form,
and runs it at once in one that cannot, where decide_issue and the other confirmed tools refuse.
The confirmation covers queries only. A statement filed as an issue runs as a rollout task, under
the project's approval policy, as the rollouts row says.
The members row shows who holds which role, the groups and their members, each role's permissions
and every policy type, so an agent can tell which people an approval step waits on. Two choices in
its wording are deliberate. It says members, not users: UserService reads stay EXCLUDED, so a
member is the email in a binding, not an account record. And it names what it serves rather than
"other policies" or "settings". GetSetting serves four settings by name: the approval rules behind
the project's approval policy, which the propose and rollout rows speak of, and the environments,
semantic types and data classification. The gate refuses every other setting name, and
ListSettings stays EXCLUDED because it returns them all. An MCP read of the semantic types leaves
out the MD5 masking salt.
The row states no bound of its own; the section's shared line limits every session by the user's
Bytebase permissions. That line has to say permissions rather than what the console shows, because
the two differ at one edge: the console reads a policy only through GetPolicy, which asks for
bb.policies.getMaskingExemptionPolicy or bb.policies.getMaskingRulePolicy on those two types,
while ListPolicies asks only for bb.policies.list and returns every type. Every built-in role
that holds bb.policies.list also holds both masking permissions, so the edge reaches custom roles
only. An access grant carries the statement its requester asked to run, which is SQL another person
wrote; the floor's query-history promise still holds, because it rests on SearchQueryHistories
pinning the creator, which this row does not touch.
The verb rule
The verb names the row's effect on the customer's databases. Read: none. Propose: none until it is approved. Request: none until it is approved, and then access to one statement's results, unmasked or exported if asked for. Approve: none directly; the issue proceeds: a change rolls out as the project's rollout policy allows, and an access request takes effect. Role requests stay in the console. Grant: direct and standing: an exempted member sees the covered data unmasked in query and export results until the exemption ends or is revoked. Run: direct. Export: data leaves the product. Manage: configuration only, no data path. Within a tier the verb repeats; it changes only where the effect changes.
One verb for the whole write tier was tried and rejected:
- Write for every write row: "Write query results" (export writes nothing to a database), "Write change proposals" (nothing reaches a database until approval), "Write rollouts" (not English), "Write database housekeeping" (reads as a data change).
- Change for every write row: fails for exports and rollouts, and makes "Change proposals" and "Change data with SQL" read as the same thing — the distinction the approval step exists to protect.
- Manage for every write row: hides the hazard on exports and on SQL.
Per row: Propose over Create (Create fits the method names but hides that the project's approval policy may still require approval); Export over Read or Download (Read hides the egress hazard, which is why Export is WRITE-class in the first place); Manage over Update or Maintain (Update reads as a data change, Maintain is vague); Request over Propose (a proposal waits for approval only when the project's approval policy says so, a session's request always does, and what an approved request gives is access to data, not a change); Approve is a row of its own, not a sub-item of Propose, because deciding someone's proposal or request is a different effect from filing one. Rollouts and DML/DDL both take Run and stay two rows, because a custom policy will want "run approved rollouts, but no ad-hoc SQL" — the workflow the product exists for.
The tier is named once, by the dividers, so no row repeats it in its title.
Decisions
D1 — Placement: a disclosure inside the Access policy section, collapsed by default. Not a drawer (a second surface, one mode at a time) and not a separate section (it belongs to the policy it describes). Collapsed, the trigger line is the mode's description, the summary under Copy. The read half is the same phrase in both modes, because Read-write serves exactly the read rows Read-only serves; the EXCLUDED reads (audit logs, users, other people's query history, task-run sessions) are refused in every mode, so no summary may say "read everything". The line never repeats the mode name, which the chip (view) or the selector (edit) already shows. Expanded, it becomes the list heading "Read-write allows", with a "Show details" control on the right. In view state it sits under the chip line; in edit state it sits under the selector and its "Best for" line, so the cause and its effect are adjacent. The open state carries across the view-to-edit transition within a page visit, and starts collapsed on the next one. Remembering it per browser was cut in review as more machinery than a settings page visited this rarely earns.
D2 — Content: rows first, sub-items behind one toggle. Expanded, each row shows its title and its tier tag, nothing else. "Show details" reveals the sub-item line for every row at once, so there is one second-level control rather than one per row; per-row expanders were rejected as fiddly. No method names, no permission names, no counts, no link to a method list. The floor is kept as one short line because it is what a security-minded admin reads first, and it is what keeps the list honest about the 108 methods no mode reaches. There is no constants line under the list; the facts it would carry (capped by the user's own permissions, refusals audited) move into the section description.
D3 — The mode chip is the subject; the "In force" line and the mode sentence go. The
three-stripe icon and the words "In force" are removed. View state reads: the mode chip (success
for Read-only, warning for Read-write, destructive for Disabled), Edit policy on the right; then
the disclosure line, which carries the description.
The mode chip carries the mode's icon before its name — the same Lucide glyph as the card in edit
state (Unplug, Eye, PencilLine) — so the identity an admin picked is the identity shown in
force. The chip is the only place the mode's color appears; the cards stay neutral, because a
control must not look like a status badge and the accent must remain the one selected-state color.
The separate sentence under the chip is retired for Read-only and Read-write, since the disclosure
line says the same thing; Disabled keeps its sentence, "No MCP session can connect to this
workspace.", because it has no list. "Active" was considered and rejected as the label: "Active ·
Disabled" contradicts itself, and a chip under a section titled Access policy needs no label. The
chip announces "Current policy: Read-only" through visually hidden text, never through
aria-label: a chip is a bare span, whose implicit generic role ARIA forbids naming, so a
label put there is dropped and the deleted "In force" text is replaced by nothing. Tests assert
the rendered name rather than the attribute, which satisfies a DOM query while naming nothing.
D4 — The two notes under the card move and shrink. "A ceiling change applies to the next request…" shows only while editing, as "Applies to every running session's next request.", and names the change when the form is dirty: "Read-only → Read-write applies to every running session's next request." "MCP policy denials are recorded in the audit log" is a fact about the feature, not about the current state, so it joins the section description. Per audit-what-produces-a-row.md a refusal reaches stdout only when audit logging to stdout is enabled, so the description carries that condition rather than an unqualified "audited": "The most any MCP session may do here. Sessions are also capped by each user's permissions, and policy refusals are streamed to stdout when audit logging to stdout is enabled."
D5 — Edit state: icon cards, the selected mode's "Best for", and the pick's ladder. The
three mode cards lose their descriptions; they duplicated the ladder. What remains is the shape of
the instance engine selector: three bordered cards in a row, each with a Lucide icon, the mode name,
and a three-word caption — Disabled "No sessions connect", Read-only "Explore and query",
Read-write "Change data and schemas". The icons are Unplug, Eye and PencilLine from
lucide-react, which the frontend already ships: unplug says nothing connects, in the same
vocabulary as the Connect a client section below; eye is view only; pencil-line is write. Icons
are grey and turn accent on the selected card, which also carries the accent border, ring and
tint; no red, green or amber on the cards, so the mode's color keeps meaning one thing on the chip.
A label-only card was tried and read empty; the shared segmented control was tried and read as a
toggle. The caption costs nine words and gives back the at-a-glance comparison the old cards
provided. Under the cards, one line: the "Best for" of the selected mode, shown once instead of
three times. Under that, the disclosure for the picked mode, rendering exactly what the view would
show after saving. No "adds N over Read-only", no added or removed marks, no comparison against the
stored mode: the muted rows already show what a pick does not serve. The edit state is about 90
words collapsed and 140 expanded, down from about 215 and 375 in the first draft of this design.
D6 — Marks: ✓ or —, plus a tier tag on served rows only. A served row shows ✓, a success
"read" badge or a warning "write" badge after its title, and full-contrast text. An unserved row
shows —, muted text, and no badge. Under Read-only the write rows are unserved, so a "write" badge
never appears there.
D7 — Disabled. In view, the chip and the sentence "No MCP session can connect to this workspace." are the whole answer; no disclosure. In edit with Disabled picked, the Disabled card is selected, the "Best for" line reads "keeping MCP off until you are ready to turn it on", and the disclosure slot holds a static line in the floor's soft error tone, "Nothing is allowed; no MCP session can connect.", so red means "no capability" everywhere on the card. It is not a button and does not repeat the mode name.
D9 — The Authentication Required alert on the MCP page is removed. Its two sentences already exist on the page: "approve access in the browser" in the Connect a client description, and "appropriate permissions" in the section description. Connect a client gains the one clause that was useful: "Add Bytebase to your AI client and start asking. On first connection you sign in and approve access in the browser."
D10 — The consent page uses the row titles, and bounds them once. "This session may" lists the served rows with ✓, one ✕ line for the unserved tier under Read-only ( + NO_WRITE + ), then the existing capped and audit lines. Read-write keeps its caution. Its mode chip carries the same icon as the settings page's. One wording table serves both surfaces.
Titles alone carry no caveats, and the caveats live in the row details this screen does not render — so on a workspace whose engine refuses every statement, an unqualified "Read data by running queries ✓" promises a capability the session does not have. The screen cannot carry a detail line for every row and stay an approval screen, so it bounds the whole list once instead, on the line that already limits it by the reader's own permissions. That bound is per mode, because the statement clamp it describes runs only under Read-only: "Capped by your own Bytebase permissions, and by what Bytebase can check on each database engine — where it cannot show a statement is a read, no query runs at all" against "Capped by your own Bytebase permissions, and by what Bytebase supports for each database engine and each operation". The Read-only line names a consequence because the clamp is one rule with one outcome. The Read-write line does not: what runs there varies by engine and by operation, and every consequence clause written for it has been false once (see the complement and method axes in The rows). It states the bound and stops. One line either way, and the ✓ marks read as what the policy admits rather than what will succeed. It carries a neutral glyph and no "Allowed" mark, so a bound is not counted as a further grant.
D11 — The wording is bound to the classification by instruction, not by a lint. The row
titles claim to cover every READ and WRITE method, and a method annotated into either class is
served the moment it is annotated, whether or not a row names it. The first draft closed that with
a row table in backend/api/v1/mcp_gate.go and a lint in mcp_gate_test.go, so a class change
failed CI until the table — and therefore the row wording — was reviewed. That was dropped: it
bought a mechanical check at the cost of a second table to keep in step, on a set that changes
rarely and only in commits already about MCP classification. A later review pointed out that a
cheaper check exists and needs no second table: TestMCPClassificationInventory already renders the
annotations into backend/api/v1/testdata/mcp_method_classification.md, whose header carries the
same per-class counts this row table sums to, so asserting those integers would fail on exactly the
change that requires the reread. That is a real option and it is not the one taken; what it buys is
a prompt to reread, not proof that the wording is right, and the decision here is to spend the
reread on the instruction rather than on a gate. The cost of the trade is unchanged and stated
below. The rule instead lives under Metadata
and API conventions in the root AGENTS.md: annotating an RPC READ or WRITE means rereading the
rows and rewording one, or adding one, when none describes it. The cost of the trade is that a
reclassification which skips that reread is silent — the page keeps its old sentences and an admin
picks a ceiling on them. No new API and no field the frontend reads: the product shows no counts, so
it needs only the static tier of each row. The one code change is a comment on MCPMethodClass in
proto/v1/v1/annotation.proto, stating that the class is disclosed to admins as capability rows —
put where the annotation is typed, since that is where the reread has to happen. It is worded as a
fact rather than a chore, and names no repo path, because proto comments ship into the published API
reference.
D12 — MCP sessions follow the caller's own masking provisioning. On 2026-09-23, Vincent Huang
and Peter Zhu decided to retire the "Ignore masking exemptions" toggle (ignore_masking_exemptions,
field 2 of MCPSetting) before the 3.23.0 tag. The toggle came from the MCP design work in
#21216, and no customer stated a requirement for
it. The former D8 set the toggle's copy and is removed; its note on the Read-only description
sentence moved to Copy. An MCP session now applies the caller's own masking provisioning exactly as
the console does, including masking exemptions and the unmask carried by an access grant. There is
deliberately no setting that forces masking for MCP sessions. Field 2 is deleted without a
reserved entry, because no other field is expected to take the number. Stored rows need no
migration, because the store's unmarshaler discards the unknown key and the next save rewrites the
row without it. The masked-write guard stays, because it never depended on the toggle.
States
| State | What the section shows |
|---|---|
| View · Read-only or Read-write | Chip line with Edit policy; the disclosure line as the description, collapsed on every visit (D1). |
| View · Disabled | Chip line; "No MCP session can connect to this workspace." No disclosure. |
| View · unreadable, unserved, read failed | The existing warning or error, unchanged. No disclosure. |
| Edit · Read-only or Read-write picked | Icon cards with the pick selected; the pick's "Best for" line; the disclosure for the pick, collapsed by default, rendering the post-save view, with "Show details" once expanded; separator; footer sentence (naming the change when dirty), Cancel, Save (enabled only when dirty). |
| Edit · Disabled picked | Icon cards with Disabled selected; its "Best for" line; the static soft-error line in the disclosure slot (D7); separator; footer sentence (naming the change when dirty), Cancel, Save. |
| Edit · nothing picked | Only reachable from an unreadable or unserved ceiling: icon cards with no selection; "Pick a mode to save this policy." in the disclosure slot; Cancel, Save disabled. |
| Consent page | Served row titles with ✓, the ✕ line under Read-only, then the existing constants and caution. |
Copy
The strings as decided, with the reasoning that picked them. The locale files are what ships and
what to edit; this section is the record of why, and a copy edit is expected to update both. Keys
under
settings.mcp.ladder.* are new; the rest replace existing settings.mcp.* and
oauth2.consent.mcp.* values.
- Section description: "The most any MCP session may do here. Sessions are also capped by each user's permissions, and policy refusals are streamed to stdout when audit logging to stdout is enabled."
- Disclosure line, collapsed — Read-only: "Read schemas, data, the change workflow, members, roles and policies; a request carrying anything that cannot be shown to be a read is refused, and nothing is exported". Read-write: "Read schemas, data, the change workflow, members, roles and policies; propose, request and revoke access, grant masking exemptions, approve, run, export and manage". Expanded heading: "{mode} allows". Details control: "Show details" / "Hide details".
- Disabled — view sentence: "No MCP session can connect to this workspace." Edit static line: "Nothing is allowed; no MCP session can connect."
- Card captions: Disabled "No sessions connect"; Read-only "Explore and query"; Read-write "Change data and schemas".
- "Best for" lines, unchanged: Disabled "keeping MCP off until you are ready to turn it on"; Read-only "querying and exploring data, including by people who do not write SQL"; Read-write "making database changes through an AI agent, still capped by each user's own permissions".
- The Read-only description sentence ("Sessions can explore schemas and run read-only queries…") is retired everywhere; its content lives in the Read-only summary and in row 2's sub-item.
- Row titles and sub-items: the table above, verbatim.
- Dividers: "Read-only stops here", "Read-write stops here".
- Floor: "Never, in any mode: administer the workspace, handle credentials, open an Admin mode session, or read anyone else's query history."
"Approve issues" left the floor when approving and rejecting moved to the confirmed tool.
"Administer the workspace" still holds for role grants, because that tool refuses role requests.
The verbs cover every denial reason except three:
SENDS_DATA_TO_A_THIRD_PARTYfor the reason below,REDRAWS_GOVERNANCE_BOUNDARY, andDRIVES_THE_APPROVAL_DECISION, whose two remaining methods re-check an issue's approval and activate an access grant directly. The verbs claim only what is refused whatever the caller's permissions and by whatever effect a served method has. That second rule cost three drafts. MCP's ceiling removes methods by class; it never adds per-row privacy, so an ownership claim — "never read other people's SQL", then "never browse everyone's saved SQL" — is false at whatever permission level makes it true in the console:GetSavedQueryreaches SQL shared by a binding, andsearchScopedrops all scoping for a caller holding project-widebb.savedQueries.get. Query history is the one that qualifies, becauseSearchQueryHistoriespins the creator and nothing widens it. A fourth draft added "or send data to a third party" and was false on the effect axis:CreateIssueis served under Read-write and its webhook posts the title and description outward. It is not replaced by a row caveat — the webhook fires identically for an issue a human files in the console, so it is a property of the workspace's notification config rather than of this ceiling, and the "Propose changes" row already says the session can file issues. The fifth draft read "open an admin connection" and was false on the same axis for the opposite reason — it named the plumbing rather than the feature, and MCP does reach the admin data source. It names Admin mode now. - Tier badges: "read", "write".
- Footer, clean: "Applies to every running session's next request." Dirty: "{from} → {to} applies to every running session's next request."
- Connect a client: the sentence in D9.
- Consent: row titles; "No changes, rollouts, exports or database management"; the two capped lines above.
Implementation
Frontend
- New
MCPCapabilityLadderbesideMCPAccessPolicySection.tsx, propsmode,expanded,details,onExpandedChange,onDetailsChange. It derives the served set from the mode by tier: READ_ONLY serves the read rows, READ_WRITE both tiers, DISABLED none. No comparison logic. - Disclosure behavior belongs in a shared primitive per the UX contract. There is no
Collapsibleinfrontend/src/components/ui/today; add one wrapping Base UI's Collapsible (trigger witharia-expanded, panel region) rather than hand-rolling it in the feature. - The mode selector keeps the
RadioGroupandRadioGroupItemsemantics with the radio hidden (radioClassName="sr-only"), and renders each item the wayInstanceEngineRadioGridinInstanceFormBody.tsxrenders an engine:rounded-sm border px-3 py-2, selectedborder-accent bg-accent/5 ring-1 ring-accent, hoverborder-accent/50. Each item holds the Lucide icon atsize-5(text-control-light,text-accentwhen selected), the label at body size, and the caption at caption size. Verify the item shows the shared focus ring with the radio hidden. - The ladder is an unframed region: the trigger row and the rows are separated by
border-block-borderhairlines, with no outer frame, so the change adds no card inside the section's existing framed card. (Design mocks draw a light border around the ladder for legibility; the implementation does not.) - Marks use the shared
Badge(successfor read,warningfor write). The floor line and the Disabled static line use theerrorsemantic tokens at low opacity; no raw palette colors, nodark:variants. MCPAccessPolicySection.tsx: remove theRows3icon, the in-force string, the mode cards and the mode sentence; render the chip through the sharedMCPModeBadge, which the consent page also uses, so one component carries the glyph and the accessible name for both surfaces; strip the mode cards to icon, label and caption and add the "Best for" line under them; move the audit sentence to the section description; show the footer sentence only while editing and interpolate both modes when dirty.MCPPage.tsx: remove the Authentication Required alert; extend the Connect a client description.MCPConsentCeiling.tsx: replace the read, write and workflow lines with the row titles from the same table.- Locale: keys under
settings.mcp.ladder.*in all five locale files. The retired mode-description keys are removed, not left empty.frontend/scripts/check-i18n.mjsenforces cross-locale parity over all of them; the four template-keyed families (ladder.row.,.stops.,.summary.,.tier.) are registered in itsDYNAMIC_PREFIXES, which exempts them from both the missing-key and unused-key checks, as it does for every other template-keyed family in the product. A row id with no copy renders its raw key on the page, and the e2e spec, which reads every row's title fromen-US.json, fails to load; an orphaned line after a rename is dead weight in the locale files. Both need a row renamed, which is rare, so neither earns a check of its own. - Tests: the served set per mode; the disclosure collapsed by default, opens, follows the pick, and starts over on the next visit; the details toggle reveals sub-items on every row; the "Best for" line follows the selection; Disabled renders the static line in edit and the sentence in view; the consent page renders the row titles; one e2e case that edits Read-only to Read-write, saves, and sees the chip change.
- Run
node frontend/scripts/check-ui-guideline.mjs; the change must not add to the legacy baseline.
Backend
No behavior change. One comment on MCPMethodClass in proto/v1/v1/annotation.proto and its
regenerated output; the rule that keeps the row wording true is an instruction under Metadata and
API conventions in the root AGENTS.md (D11), not code.
Keeping the rows true
Nothing enforces the wording, so annotating an RPC mcp_method_class = READ or WRITE — a new RPC,
or a reclassified one — is also a change to what the Access policy page and the OAuth consent screen
promise. What to do:
- Read the row table above and judge whether a row still describes the method. The right column
records the method families each row stands for, not an exhaustive list, so this is a judgment
about the wording rather than a lookup.
backend/api/v1/testdata/mcp_method_classification.mdis the generated list of every method and its class, and CI forces a diff on it for the same change. - If none covers it, reword a row or add one. The copy is
settings.mcp.ladder.row.*infrontend/src/locales/— all five files — and the order and tier are infrontend/src/components/mcp/mcpCapabilityRows.ts. Update the table above in the same change. - Check the new wording on all five axes in The rows — mode, engine, effect, complement and method — against their rules: state the bound and never the behavior, name the feature and never the mechanism, and claim only what holds whatever the caller's permissions. A line you are changing to fix one axis still has to hold on the other four; every regression this page has shipped came from checking only the axis that prompted the edit.
- For any claim of the form "refused where X", check
HasQueryValidatorandEngineSupportQueryNewACLas a conjunction rather than either alone, and check each RPC that executes statements separately —SQLService/QueryandSQLService/Exportgate on different conditions, so a sentence true of one is not thereby true of the other.
The consent screen renders row titles only, so a caveat that belongs to one mode or one engine has to live in the bound line there (D10), not in a row's sub-items.
Out of scope
- A custom access policy. When it comes, the rows become checkboxes, the cards become preset
buttons that select a prefix, and a policy matching no prefix shows a Custom chip; the backend
row table is what the gate would read. The ladder needs no redesign. The one precondition before
rows become independently selectable is met:
SQLService/Exportruns only statements Bytebase can show are reads for an MCP session (mcp_sql_write.go). Export needed its own check because it skips statement validation on MySQL, and the driver executes non-query statements. The same split is why the consent card's Read-write bound names the operation as well as the engine (the method axis in The rows). - A docs page listing the methods per row, generated from the inventory. Worth doing; not linked from the card until it exists.
- Making the collapsed list findable by the browser's find-in-page. Base UI unmounts a closed panel,
so the rows and the floor line are absent from the DOM until the disclosure is opened, and
hiddenUntilFoundwould keep them mounted instead. Declined: collapsing by default is D1's decision, the summary line states what the mode allows and the trigger is beside it, and the attribute's browser support is uneven — the unmount also keeps the rows out of the accessibility tree while they are not shown. Revisit if the list stops being a disclosure. - Per-engine read-only depth and masking coverage. The removed drawer showed both; they belong in docs, not on the policy card.
- The ceiling gate itself, the classification, and the consent flow's mechanics.
Open questions
- The Access policy section is a framed card, which predates the "no cards inside cards" rule. This change adds no nesting and removes the nested mode cards, so unframing the section is a natural follow-up.
- Whether the consent page should also show the sub-items. The proposal shows titles only, to keep the approval screen short.