Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
docs(design): shorten the Access policy section around the ladder
zchpetercc1dbe7c1e8b
diff --git a/docs/design/mcp-capability-ladder.md b/docs/design/mcp-capability-ladder.mdindex c05cfe9979..6fdcdb1902 100644--- a/docs/design/mcp-capability-ladder.md+++ b/docs/design/mcp-capability-ladder.md@@ -1,6 +1,6 @@# MCP access policy — show what a mode allows-Status: proposal · 2026-09-09+Status: proposal · 2026-09-10The MCP settings page offers three modes (Disabled, Read-only, Read-write) and describes each inone sentence. Since [#21324](https://github.com/bytebase/bytebase/pull/21324) removed the per-mode@@ -8,10 +8,12 @@ method drawer, nothing on the page says what a mode actually serves, and an admiRead-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 eight capability rows inwhich each mode is a prefix, collapsed by default inside the existing Access policy section, and-following the picked mode while editing.** The product change is frontend-only. One backend lint-binds the row wording to the method classification, so the list cannot drift from what the gate-serves. A custom access policy is out of scope, but the list is shaped so that it becomes that-editor later without a redesign.+following the picked mode while editing.** The page also gets shorter: the mode cards become a+slider with the selected mode's "Best for" under it, the disclosure line is the mode's description,+and row details sit behind one toggle. The product change is frontend-only. One backend lint binds+the row wording to the method classification, so the list cannot drift from what the gate serves. A+custom access policy is out of scope, but the list is shaped so that it becomes that editor later+without a redesign.## Problem@@ -34,6 +36,10 @@ ceiling gate (`backend/api/v1/mcp_gate.go`) removes *methods* by class before thruns, and under Read-only the SQL clamp removes *statements*. So the page has to say what an agentcan 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, backed by an exact set of served methods in@@ -47,6 +53,9 @@ What follows from it:- Rows a mode does not serve stay visible and muted, so comparing modes never needs a secondsurface.- 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 slider; the+ description in the disclosure line; the audience in the "Best for" line; the detail behind one+ toggle.## The rows@@ -102,11 +111,12 @@ One verb for the whole write tier was tried and rejected:exist to protect.- **Manage** for all five: hides the hazard on exports and on SQL.-Per row: *Propose* over Create (Create fits the method names but hides that a human still-approves); *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). 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.+Per row: *Propose* over Create (Create fits the method names but hides that the project's approval+policy may still require a human); *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). 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.@@ -114,41 +124,51 @@ The tier is named once, by the dividers, so no row repeats it in its title.**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). One trigger line, "What Read-only allows · Read schemas, data and the change-workflow; nothing is written or exported", expands inline into the list. In view state it sits-under the mode sentence; in edit state it sits under the three mode cards, above the masking-toggle, so the cause and its effect are adjacent. The open state persists per browser and carries-across the view-to-edit transition within a page visit.--**D2 — Content: rows and sub-items only.** 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 121 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 goes.** 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), the "Masking exemptions ignored" chip when set, Edit policy-on the right; then the mode's one sentence; then the disclosure. "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 carries `aria-label="Current policy: Read-only"`. The icon-also leaves the mode cards, so color appears in exactly two places: the chip in view, the selected-border in edit.--**D4 — The two notes under the card move.** "A ceiling change applies to the next request…" shows-only while editing, and it names the change when the form is dirty: "Changing Read-only to-Read-write applies to the next request of every running session; work already admitted runs to-completion." "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: "The most any MCP session may do in-this workspace. Every session is also capped by the connecting user's own permissions, and every-refusal is recorded in the audit log."--**D5 — Edit state renders the pick, and only the pick.** The disclosure under the cards shows-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 mode cards lose their visible radio; the card is the control, with the selected card-carrying the accent border and a faint accent tint, hover lightening the border, and keyboard focus-drawing the shared ring on the card. The radio group semantics stay.+policy it describes). Collapsed, the trigger line *is* the mode's description: "▸ Read everything,+and propose, run, export and manage". It never repeats the mode name, which the chip (view) or the+slider (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 slider and its "Best for" line, above the masking toggle, so the cause and its+effect are adjacent. The open state persists per browser and carries across the view-to-edit+transition within a page visit.++**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 eight; 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 121 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), the "Masking exemptions ignored"+chip when set, Edit policy on the right; then the disclosure line, which carries the description.+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 carries `aria-label="Current policy: Read-only"`.++**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, which becomes: "The+most any MCP session may do here. Sessions are also capped by each user's permissions, and refusals+are audited."++**D5 — Edit state: a slider, the selected mode's "Best for", and the pick's ladder.** The three+mode cards and their descriptions are gone; they duplicated the ladder. The selector is the shared+segmented control with three equal-width segments, Disabled · Read-only · Read-write, so the+control reads as one setting rather than three labels of different sizes. Under it, one line: the+"Best for" of the selected mode. "Best for" survives because it answers a different question from+the ladder — who the mode is for — and it is now 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 100 words collapsed and 150+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@@ -156,16 +176,18 @@ shows —, muted text, and no badge. Under Read-only the write rows are unservednever 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 disclosure slot-holds a static line in the floor's soft error tone, "Disabled · nothing, no MCP session can-connect", so red means "no capability" everywhere on the card. It is not a button.--**D8 — Copy that shrinks.** The Read-only card drops to two sentences plus its "Best for" line:-"Sessions can explore schemas and run read-only queries. Every statement is checked before it-runs." The classifier and driver-depth detail it carried moves to docs; the "refused whole" rule-lives in row 2's sub-item. The masking toggle's two paragraphs become one sentence: "If enabled, a-user's masking exemptions and access-grant unmasks do not apply in MCP sessions; masked data stays-masked. The console is unaffected."+workspace." are the whole answer; no disclosure. In edit with Disabled picked, the slider sits on+Disabled, 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.++**D8 — Copy that shrinks.** The masking toggle's two paragraphs become one sentence: "If enabled,+masked data stays masked in MCP sessions even for users with exemptions or unmask grants. The+console is unaffected." The engine caveat it carried moves to docs. The three "Best for" lines keep+their current wording. 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.**D9 — The Authentication Required alert on the MCP page is removed.** Its two sentences alreadyexist on the page: "approve access in the browser" in the Connect a client description, and@@ -190,11 +212,11 @@ shows no counts, so the frontend needs only the static tier of each row.| State | What the section shows ||---|---|-| View · Read-only or Read-write | Chip line with Edit policy; the mode sentence; the disclosure, collapsed. Nothing below it. |+| View · Read-only or Read-write | Chip line with Edit policy; the disclosure line as the description, collapsed. Nothing below it. || 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 | Three selectable cards; the disclosure for the picked mode, collapsed by default, rendering the post-save view; masking toggle; separator; footer sentence (naming the change when dirty), Cancel, Save (enabled only when dirty). |-| Edit · Disabled picked | As above, with the disclosure slot holding the static soft-error line. |+| Edit · Read-only or Read-write picked | Slider on the pick; the pick's "Best for" line; the disclosure for the pick, collapsed by default, rendering the post-save view, with "Show details" once expanded; masking toggle; separator; footer sentence (naming the change when dirty), Cancel, Save (enabled only when dirty). |+| Edit · Disabled picked | Slider on Disabled; its "Best for" line; the static soft-error line in the disclosure slot. || Consent page | Served row titles with ✓, the ✕ line under Read-only, then the existing constants and caution. |## Copy@@ -203,21 +225,23 @@ All strings, so the change and the locale files have one source. 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 in this workspace. Every session is also- capped by the connecting user's own permissions, and every refusal is recorded in the audit log."-- Trigger: "What {mode} allows". Summaries — Read-only: "Read schemas, data and the change- workflow; nothing is written or exported". Read-write: "Read everything, and propose, run, export- and manage". Disabled (static): "Disabled · nothing, no MCP session can connect".+- Section description: "The most any MCP session may do here. Sessions are also capped by each+ user's permissions, and refusals are audited."+- Disclosure line, collapsed — Read-only: "Read schemas, data and the change workflow; nothing is+ written or exported". Read-write: "Read everything, and propose, 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."+- "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".- Row titles and sub-items: the table above, verbatim.- Dividers: "Read-only stops here", "Read-write stops here".- Floor: "Never, in any mode: approve issues, administer the workspace, or handle credentials."- Tier badges: "read", "write".-- Read-only card: "Sessions can explore schemas and run read-only queries. Every statement is- checked before it runs." Best-for line unchanged.- Masking toggle: the one sentence in D8.-- Footer, clean: "Changes apply to the next request of every running session; work already- admitted runs to completion." Dirty: "Changing {from} to {to} applies to the next request of every- running session; work already admitted runs to completion."+- 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 or exports".@@ -226,30 +250,37 @@ All strings, so the change and the locale files have one source. Keys under### Frontend- New `MCPCapabilityLadder` beside `MCPAccessPolicySection.tsx`, props `mode`, `expanded`,- `onToggle`. 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.+ `details`, `onToggle`, `onToggleDetails`. 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`Collapsible` in `frontend/src/components/ui/` today; add one wrapping Base UI's Collapsible(trigger with `aria-expanded`, panel region) rather than hand-rolling it in the feature.+- The mode selector is the shared `SegmentedControl` at size `md`. It sizes each segment to its+ label today; add an equal-width option to the primitive (equal grid columns, or a shared+ minimum width per segment) rather than styling it in the feature. The `RadioGroup` cards and+ their `radioClassName` go away.- The ladder is an unframed region: the trigger row and the rows are separated by`border-block-border` hairlines, with no outer frame, so the change adds no card inside thesection's existing framed card. (Design mocks draw a light border around the ladder forlegibility; the implementation does not.)-- Marks use the shared `Badge` (`success` for read, `warning` for write). The floor line uses the- `error` semantic tokens at low opacity; no raw palette colors, no `dark:` variants.-- `MCPAccessPolicySection.tsx`: remove the `Rows3` icon and the in-force string; render the chip as- the sentence subject with the aria-label; move the audit sentence to the section description;- show the tightening sentence only while editing and interpolate both modes when dirty; replace the- masking copy; pass `radioClassName="sr-only"` to `RadioGroupItem` and verify the item shows the- shared focus ring with the radio hidden.+- Marks use the shared `Badge` (`success` for read, `warning` for write). The floor line and the+ Disabled static line use the `error` semantic tokens at low opacity; no raw palette colors, no+ `dark:` variants.+- `MCPAccessPolicySection.tsx`: remove the `Rows3` icon, the in-force string, the mode cards and+ the mode sentence; render the chip with its aria-label; add the slider and the "Best for" line;+ move the audit sentence to the section description; show the footer sentence only while editing+ and interpolate both modes when dirty; replace the masking copy.- `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 thesame table.- Locale: keys under `settings.mcp.ladder.*` in all five locale files;- `frontend/scripts/check-react-i18n.mjs` guards them.+ `frontend/scripts/check-react-i18n.mjs` guards them. The retired mode-description keys are+ removed, not left empty.- Tests: the served set per mode; the disclosure collapsed by default, opens, persists, and follows- the pick; Disabled renders the static line in edit and nothing 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.+ the pick; the details toggle reveals sub-items on every row and persists with the open state; the+ "Best for" line follows the slider; 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 legacybaseline.@@ -265,8 +296,8 @@ All strings, so the change and the locale files have one source. Keys under## Out of scope-- A custom access policy. When it comes, the rows become checkboxes, the three cards become preset- buttons that select a prefix, and a policy matching no prefix shows a Custom chip; the backend+- A custom access policy. When it comes, the rows become checkboxes, the slider becomes a preset+ picker that selects a prefix, and a policy matching no prefix shows a Custom chip; the backendrow table is what the gate would read. The ladder needs no redesign.- A docs page listing the methods per row, generated from the inventory. Worth doing; not linkedfrom the card until it exists.@@ -276,8 +307,8 @@ All strings, so the change and the locale files have one source. Keys under## Open questions-- The Access policy section is a framed card containing the mode cards, which predates the "no- cards inside cards" rule. This change does not add nesting, but unframing the section is a+- 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 anatural follow-up.- Whether the consent page should also show the sub-items. The proposal shows titles only, to keepthe approval screen short.