Skip to content

docs(rfc): record one live MCP Authorize card per server - #24872

Open
kyleseaman wants to merge 1 commit into
mainfrom
docs/rfc-mcp-authorize-cards-removed
Open

kyleseaman wants to merge 1 commit into
mainfrom
docs/rfc-mcp-authorize-cards-removed

Conversation

@kyleseaman

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record the product owner's decision that a chat shows one live MCP Authorize card per server, and removes replaced and ended cards instead of greying them out, so review lanes read it from main.

The fixes for #7580 and #7654 left a rule in a code comment in McpOAuthBanner.tsx: a retired Authorize card stays visible as a grey notice, because "a vanished banner ... is indistinguishable from the sign-in having succeeded." Kyle Seaman (product owner) decided on 2026-10-26 to reverse that. With rotating sign-in offers, the grey cards bury the one live button. The decision lives only in conversation and PR dispositions today, so the First Principles and UX lanes on #22907 block every head of it as reversing a pinned decision with no record.

Why it matters

#22907 and #24701 implement the decision and cannot reach readiness while their lanes see no recorded decision. The First Principles lane reads RFC status from the base branch only, so the record has to land on main before those PRs rebase.

Not a goal

What changed (motivation → approach → change)

New RFC docs/request-for-change/rfc-mcp-authorize-card-one-live-per-server.md, status: accepted on the product owner's decision of 2026-10-26 (#24871)
Index One row and one audit sentence in docs/request-for-change/README.md

The RFC states the decision: a replaced card and a timed-out card are removed from the transcript, a chat shows at most one live Authorize card per server, the dead-process recovery card from #7654 stays, and a late success still shows as the green authenticated card. It names what it replaces (the code-comment rule from #7580 and #7654), the consequences (users lose the visible history of failed attempts; the next offer mints a fresh card), and the two alternatives considered (greyed cards; a collapsed history line). It follows the shape of the other product-owner RFCs in the directory, such as rfc-fold-recorded-edit-cards.

Backwards compatibility

Compatible: documentation only; no code, config or contract changes.

Removes nothing: the diff adds one document and one index row.

Tests

Proof: not provable -- docs or config only

sh scripts/docs-lint.sh passes ("All documentation checks passed").

Manual verification

N/A — docs only. Every code claim in the RFC was checked against main at 2ec42c9dc1: renderMcpOAuthMessage and its superseded/expired branches in website/src/pages/chat/McpOAuthBanner.tsx, _supersede_open_mcp_oauth_banners in src/kiro_crew/dashboard/chat_turn/mcp_session.py, and _expire_dead_child_oauth_meta in src/kiro_crew/dashboard/chat_utils_display.py.

Related Issues

Closes #24871
Refs #22907
Refs #24701

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@kyleseaman
kyleseaman requested review from a team and KiroCrewCaptain as code owners October 27, 2026 12:26
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 27, 2026
@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 32de16b5699de33f424953dee8f24b9fb988937d touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 32de16b5699de33f424953dee8f24b9fb988937d ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 32de16b5699de33f424953dee8f24b9fb988937d — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: a docs-only change that puts a product-owner reversal on record, with its consequences and rejected alternatives written down. It takes nothing away and renders nothing new.

Notes

[DESIGN-REVIEWED] 32de16b

Description read

[DESCRIPTION-READ] 2efdf5b3df19db9a9ce8f0894645bafad8af92413ffb344fd6ece73a6f10aca6

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 32de16b5699de33f424953dee8f24b9fb988937d and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 32de16b

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 32de16b5699de33f424953dee8f24b9fb988937d false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 32de16b5699de33f424953dee8f24b9fb988937d — this comment is updated in place on each push.

Review details

No findings. Both candidates are true statements about the RFC's description of the current code, but the RFC's decisions and exit criteria still hold against main, so neither affects a user, an operator, data or a security boundary.

Notes:

  • The RFC says "fix(mcp): retire an Authorize card once its sign-in attempt ends #22907 adds this state as meta.expired_reason: attempt_ended", but main already sets it (src/kiro_crew/dashboard/chat_turn/mcp_session.py:652) and checks it (website/src/pages/chat/McpOAuthBanner.tsx:53), so the "verified at 2ec42c9dc1" reading is out of date.
  • Context line 56 says every retired card shows "a grey notice", but on main a timed-out card shows an ErrorNotice with pages.chat.mcpOAuthBanner.timed_out (McpOAuthBanner.tsx:178), and the RFC doesn't say what happens to that string.

[OPUS-REVIEWED] 32de16b

Verdict parsed from the review's SHA-scoped output markers for commit 32de16b5699de33f424953dee8f24b9fb988937d.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 32de16b5699de33f424953dee8f24b9fb988937d false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 27, 2026
@kyleseaman
kyleseaman force-pushed the docs/rfc-mcp-authorize-cards-removed branch from 4bbbddc to e42024d Compare October 27, 2026 14:25
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 27, 2026
@kyleseaman
kyleseaman enabled auto-merge (squash) October 27, 2026 15:43
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at e42024d.

The RFC is accurate against main: the cited functions and the code-comment rule it replaces are where it says, and #24871 records the same product-owner decision. CI is green and the GPT/Opus lanes report no findings.

One blocker: the Design Review's Notes bullet is unanswered. It asks what happens when a timed-out card is removed and no next offer arrives for that server (for example the user stops prompting), and wants Rollout exit 2 to say so, so #22907 does not decide it alone. The Consequences bullet (L47) says the card disappears "until the next offer", which assumes one comes.

To clear: add one sentence to Consequences or Rollout exit 2 (L59) stating the no-offer outcome as accepted, or reply on the PR explaining why an offer always follows a live-process timeout.

— crew-pr-reviewer (r129)

@kyleseaman
kyleseaman force-pushed the docs/rfc-mcp-authorize-cards-removed branch from e42024d to a3ef5eb Compare October 27, 2026 19:40
@kyleseaman

kyleseaman commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor Author

Addressed the HOLD in a7c8175f88 (amended, still one commit).

Consequences now reads:

A card that times out while the user is away disappears with nothing in its place. A fresh card for that server appears only if a later offer is made, and none may come; the authenticated card, not a missing card, is the success signal.

Rollout exit 2 adds:

When a card is removed and no later offer arrives for that server, the chat shows no card for it, and this outcome is accepted: with #24701 a card is offered only when the user's message names an unsigned server, so no follow-up offer is the normal case. To sign in, the user names the server in a message, which mints a fresh card; Settings -> MCP sign-in becomes a second path once #24693 lands.

No dead card is left behind in either case.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Oct 27, 2026
@kyleseaman
kyleseaman force-pushed the docs/rfc-mcp-authorize-cards-removed branch from a3ef5eb to a7c8175 Compare October 27, 2026 21:08
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Oct 27, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at a7c8175.

The r129 blocker is cleared: Consequences and Rollout exit 2 now say that a removed card may have no successor and that this is accepted (L47, L59). CI is green and the other lanes report nothing.

One item is still open: the Design Review on this head notes that Decision 3 (L37) follows from decisions 1 and 2. As written, it could read as a request for a second dedupe path in #22907 and #24701. To clear it, say in Decision 3 that it follows from 1-2, or reply on the PR explaining why it is a separate rule.

— crew-pr-reviewer (r131)

@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 7, 2026
@kyleseaman
kyleseaman force-pushed the docs/rfc-mcp-authorize-cards-removed branch from a68d3c3 to ba3b50b Compare November 9, 2026 19:04
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 9, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Maintainers confirmed the design direction on a68d3c3. The RFC file on this head is byte-identical to that one. The PR now waits for a maintainer approval on ba3b50b, because the force-push dismissed the earlier approval.

Review result on this head: no blocking findings. The change is docs only: one RFC and one row in the request-for-change index. The code anchors the RFC cites are all still on main: _supersede_open_mcp_oauth_banners in mcp_session.py, _expire_dead_child_oauth_meta in chat_utils_display.py, the "A vanished banner is the worse failure" comment in McpOAuthBanner.tsx, and the superseded locale string. The RFC names its own cost: a timed-out card can disappear with no successor. It also keeps the dead-process recovery card for the case where no new offer would come.

Optional:

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 10, 2026
@kyleseaman
kyleseaman force-pushed the docs/rfc-mcp-authorize-cards-removed branch from ba3b50b to 3e309ca Compare November 10, 2026 20:06
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 10, 2026
@kyleseaman
kyleseaman force-pushed the docs/rfc-mcp-authorize-cards-removed branch from 3e309ca to 32de16b Compare November 12, 2026 16:14
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 12, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: the decider estimates a 10% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes.

Docs-only RFC recording the product owner's decision to remove replaced and timed-out MCP Authorize cards instead of greying them out, keep the dead-process recovery card, and let a late success still turn the card green. I checked the decision and exit criteria against main: renderMcpOAuthMessage still keeps every retired card visible, the comment it replaces is quoted correctly, and the dead-process path sets no expired_reason, so decision 4 can be checked. Some context lines are stale (main already has attempt_ended and shows a timed-out card as a red error notice, not grey), but that is wording drift and does not change behaviour. No trust boundary moves; accepting an RFC on a product owner's decision matches existing index rows.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 32de16b569 · 62 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 12, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Remove replaced and ended MCP Authorize cards from the chat transcript

5 participants