Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

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.md
index 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-10
The MCP settings page offers three modes (Disabled, Read-only, Read-write) and describes each in
one 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 admi
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 eight 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 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 th
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, 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 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 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 unserved
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 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 already
exist 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 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` (`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 the
same 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 legacy
baseline.
@@ -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 backend
row 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 linked
from 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 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.