fix(mcp): state the rule an MCP denial enforces and a next step that works - #21535

Rewords the refusals an MCP agent, and the person it acts for, can receive. The trigger: ApproveIssue on an issue someone else created was refused with "an agent does not move its own change through that gate". That sentence tells the reader that approving someone else's change is fine, when the gate refuses approval decisions on every issue. An audit of every MCP-facing message found 36 with problems; this PR fixes the wording defects and the design gap behind them.

What a reader sees

Also:

• The prompt that asks a person to pick between ambiguous databases now names what the pick is for, such as "Which one should this change target?". The same prompt used to ask "Which one do you want to query?" before a change that may run.
• A 30-second timeout is named as one, with a way to shorten the query. It used to say "check network connectivity" for a call that never leaves the process, and it showed an internal URL.
• A database that is not found points to DatabaseService/ListDatabases rather than search_api, which lists API operations.
• On the consent page, the Read-write caution reads "Approve only if you started this connection from an AI client you trust", since hosted clients don't run on the user's machine. The settings ladder's "Propose changes" detail no longer says "its own change".

Why they were wrong

The denials followed one rule, "state what the method does", and nothing more:

1. Too narrow. A reason described a method's worst case, such as "its own change" or "the settings that bound this session". The gate refuses the whole method, for every caller, every argument and every resource owner.
2. One next step for everything. Every refusal ended with "do it in the console". That's unsafe for a masked write: the same statement run in the console overwrites real data, because the guard only runs for MCP sessions. It's also wrong for sign-in flows, for switching workspace (the MCP way is reauthorize), and for approvals, which only an approver can make.
3. Internal words. "Ceiling", READ_ONLY, ROLE_GRANT and "principal" appeared where the UI says "MCP access policy: Read-only / Read-write".

How it is kept true

• The rules live on the reason table in mcp_gate.go.
  • A reason says what the method can do at the gate's grain.
  • Each reason carries its own next step, and a method its step would misdirect overrides it.
  • Messages use the Access policy page's words.
  • The templates say which kind of refusal it is: unavailable whatever the policy, available under no policy, or needing Read-write. Only the last is worth asking an admin about.
  • Every gate refusal keeps the phrase "not available to MCP sessions", which tests and anyone searching the audit log rely on.
• docs/design/mcp-capability-ladder.md D13 records the decision. The doc's own "never approves its own change" is corrected, along with its approval sentence: whether a human must approve depends on the workspace's approval rules and the project's settings.
• TestMCPDenialWording renders every reason and refusal path and checks what a check can. A reason must continue "because", a next step must be its own sentence, a rendered denial must be complete sentences, and banned words such as "ceiling", enum names and "own change" must not appear. Put the old ApproveIssue sentence back and the test fails.
• The classification inventory now prints each reason's rendered denial beside every method it covers. A reviewer reads the sentence where it has to be true.
• TestMCPRefusalsNameThemselvesToTheQueryTool now also covers the permanently-refused and no-policy templates, an unsupported policy value, and Disabled. IsPolicyRefusal keys on "MCP session" or "MCP access policy".
• The ceiling verdicts are complete ASCII sentences. Every door but the gate shows them alone, and two of those doors carry them in an OAuth error_description.

Verification

• go test passes for backend/api/v1, backend/api/auth, backend/api/oauth2, backend/api/mcp and backend/utils.
• The 43 integration tests in backend/tests that pin or exercise MCP refusal wording pass. They span the gate, the credential and workspace-escape guards, the SQL clamp, the capability setting, OAuth2 grants, migration, denial audit and read-path redaction.
• golangci-lint v2.13.2 (the CI version) is clean, gofmt is applied, and the server builds.
• buf format, buf lint and buf generate ran for the enum comments.
• The frontend gate is green: biome, the guard scripts, tsc, the release bundle, and 531 files / 5790 tests.

Not included

These findings need logic changes rather than wording, so they're left for follow-ups:

• query_database reads only the first result, so an error in a later statement is dropped.
• Permission advice should be keyed on the error's PermissionDeniedDetail rather than on missing wording, which would let the tools stop matching text.
• SQLService/AdminExecute answers "unknown operation" because it's never indexed.
• A missing external URL returns a 503 "discovery is unavailable" instead of saying what to configure.
• Loopback redirect URIs are matched exactly, including the port, where RFC 8252 §7.3 allows any port.
• search_api still describes a refused operation as if it were callable.
• CreateAccessGrant is classed as workspace administration, but its real risk is an auto-approved grant.

Audit-log rows record the refusal text, so rows written after this change carry the new wording. Searching the audit log for the old phrases won't find them.

🤖 Generated with Claude Code