feat(mcp): Control Center - read-only grant matrix (who holds which MCP tool)

[Weegy]

Part of the Control Center scope in epic #459 (Wave 2, item 3 of the epic's UX list) - the piece that would have surfaced #457's dead grants without a code trace.

Scope

A read-only cross-tab inside the /admin/mcp Control Center (#460): which agent / sub-agent currently holds which MCP tool grant, sourced from agent_tool_grants joined with agents, sub-agents, servers, and current verdicts.

• Backend: GET /operator/mcp-grants returning all grants with resolved agent/sub-agent names, server name, normalized tool name, and the tool's current verdict + ack state.
• Frontend: matrix pane in the Control Center; rows = grant holders (agents, sub-agents grouped under their parent), columns/cells = server:tool with verdict badge. No mutations in v1 (grants stay canvas-managed) except revoke, which reuses the existing edge-delete route.
• Blocked-by-policy grants (runtime blocklist from security: extend content-security scanning to MCP tool discovery #454's fold) render visibly struck/flagged, so an operator sees "granted but not callable" instead of silence.

Scoped to the grant types that exist as of Waves 0/1 (agent + sub-agent). Skill bindings (#456) and plugin grants (#458) extend this matrix in Wave 6, consuming the caller taxonomy from the audit foundation.

[Weegy]

Wave 2 implementation is on branch worktree-mcp-epic-459-waves (commit dfd2dd1).

• GET /operator/mcp-grants: every MCP grant with resolved holder (agent or sub-agent under its parent), server, normalized tool name, current verdict, ack validity, and blocked state
• Matrix pane in /admin/mcp: verdict badge per grant, state column distinguishes active / blocked by policy / not scanned (blocked at dispatch)
• Revoke with confirm dialog, via the existing edge-delete route
• "Granted but not callable" is now visible instead of silent - the exact bug: top-level-agent MCP tool grants are silently inert (only sub-agent grants work) #457 failure class

Skill and plugin grant rows extend this matrix in Wave 6, consuming the caller taxonomy from #462.

[Weegy]

Triage

Priority: P1 · Category: feature · Effort: S (remaining: review + merge + post-merge verify) · Status: Implemented on open PR #464 — not yet on main

The Wave 2 comment above is accurate: the grant matrix is built on branch worktree-mcp-epic-459-waves, which is now open as PR #464 (ready-for-review, mergeable: true, base = current main@1e5b24d, no drift). Nothing from this issue is on main yet — main has neither web-ui/app/admin/mcp/ nor any mcp-grants route. All remaining work is review/merge of #464 plus a post-merge functional check; no new implementation is needed here.

Implementation notes

Verified on PR #464 head (worktree-mcp-epic-459-waves):

• middleware/src/routes/agentBuilder.ts — GET /mcp-grants (line 1920; the router is mounted at /api/v1/operator behind requireAuth in middleware/src/index.ts), plus PUT /mcp-grants and DELETE /mcp-grants/:grantId (revoke deletes via the same underlying deleteToolGrant the canvas edge-delete uses, with an MCP-only scope guard)
• web-ui/app/admin/mcp/page.tsx — GrantsPane under the section marker "Grants (read-only matrix, issue feat(mcp): Control Center - read-only grant matrix (who holds which MCP tool) #461)"; groupGrants() collapses the flat holder × server × tool rows into per-holder+server cards; revoke goes through a confirmRevoke dialog; tabs are servers | marketplace | grants | plugins | audit
• web-ui/app/_lib/agentBuilder.ts — McpGrantMatrixRow type, listMcpGrants() / revokeMcpGrant() calling /v1/operator/mcp-grants

Verified absent on main@1e5b24d: no admin/mcp page, no mcp-grants routes (main's agentBuilder.ts has pre-existing /mcp-servers routes, but nothing from this issue), migrations end at 0007_skill_verdict.sql.

Suggested approach:

1. Review and merge PR feat(mcp): MCP as a first-class capability across Orchestrator/Sub-Agent/Skill/Plugin + Control Center (epic #459) #464 (it carries this issue together with the rest of epic epic: MCP as a first-class capability across Orchestrator/Sub-Agent/Skill/Plugin + Control Center UX #459's waves; the grant matrix is not separable without cherry-picking, and the epic comment structure assumes one PR).
2. After merge + deploy, run the verification checklist below against /admin/mcp → Grants tab.
3. Close this issue referencing feat(mcp): MCP as a first-class capability across Orchestrator/Sub-Agent/Skill/Plugin + Control Center (epic #459) #464's merge commit.

Risks / dependencies:

• Migration numbering: main's next free slot is 0008; PR feat(mcp): MCP as a first-class capability across Orchestrator/Sub-Agent/Skill/Plugin + Control Center (epic #459) #464 carries 0008–0019. No collision with main today, but any other PR adding a new migration before feat(mcp): MCP as a first-class capability across Orchestrator/Sub-Agent/Skill/Plugin + Control Center (epic #459) #464 merges will collide — merge order matters. Separately, the long-open PR feat(agent-builder): editable visual canvas for channels/sub-agents/skills/tools/MCP/schedules #264 (agent-builder canvas, stale since June) modifies middleware/src/routes/agentBuilder.ts and would conflict with feat(mcp): MCP as a first-class capability across Orchestrator/Sub-Agent/Skill/Plugin + Control Center (epic #459) #464's changes there.
• The "blocked by policy" state in the matrix depends on middleware/src/services/mcpGrantPolicy.ts (the security: extend content-security scanning to MCP tool discovery #454 fold) shipping in the same PR — it does, so no cross-PR ordering issue.
• Skill (feat: allow Skills to declare/bind MCP tool capabilities (capability-contract model) #456) and plugin (feat: expose MCP tool access to Plugins via ctx.mcp (PluginContext) #458) grant rows are explicitly Wave 6 scope per this issue's scope note; plugin grants already have separate /v1/operator/plugin-mcp-grants routes in the PR, but they render in a separate Plugins tab, not merged into this matrix — that extension stays open under feat(mcp): Control Center v2 - test-call sandbox, bulk actions, periodic re-scan, matrix extension #463 (Wave 6), not here.
• Auth is the requireAuth gate applied at the /api/v1/operator mount in middleware/src/index.ts, same as the other agent-builder endpoints; no new auth surface.

Acceptance criteria (post-merge verification):

• GET /api/v1/operator/mcp-grants returns holder (agent or sub-agent grouped under parent), server, normalized tool name, verdict, ack validity, blocked state — and 401s without an operator session
• Grants tab in /admin/mcp renders one card per holder+server with a verdict badge per tool
• A grant whose tool is on the runtime blocklist renders visibly as "blocked by policy" (the bug: top-level-agent MCP tool grants are silently inert (only sub-agent grants work) #457 failure class is not silent)
• Revoke shows a confirm dialog and deletes via DELETE /api/v1/operator/mcp-grants/:grantId; the canvas edge disappears after reload
• No mutation surface beyond revoke exists in the Grants tab (grants stay canvas-managed per the issue's v1 scope)

---

Automated triage against main@1e5b24d; posted after adversarial fact-check review.

[Weegy]

Triage

Priority: P1 · Category: feature · Effort: S (verify + close) · Status: Shipped — merged to main via #464

Status delta since the previous comment (posted before the merge, when this was "on open PR #464 — not yet on main"): PR #464 is now merged. The current main HEAD 327ddf8 is the merge commit of worktree-mcp-epic-459-waves, so the grant matrix is live on main. The Wave 2 checklist and the earlier implementation notes are accurate and verified against the merged tree — no new implementation is needed. Recommend a functional check on the deployed environment, then close.

Implementation notes

Verified present on 327ddf8 (merge commit of #464):

• middleware/src/routes/agentBuilder.ts — GET /mcp-grants (line 1920), PUT /mcp-grants (line 1525), DELETE /mcp-grants/:grantId (line 1559); router mounted at /api/v1/operator behind createRequireAuth in middleware/src/index.ts
• middleware/src/services/mcpGrantPolicy.ts — the security: extend content-security scanning to MCP tool discovery #454 fold that feeds the "blocked by policy" cell state
• web-ui/app/admin/mcp/page.tsx — GrantsPane + groupGrants() (section marker line 1213, "Grants (read-only matrix, issue feat(mcp): Control Center - read-only grant matrix (who holds which MCP tool) #461)"); tabs are servers | marketplace | grants | plugins | audit; revoke via confirmRevoke dialog
• web-ui/app/_lib/agentBuilder.ts — McpGrantMatrixRow (line 625), listMcpGrants() (GET), revokeMcpGrant() (DELETE) against /v1/operator/mcp-grants

Suggested approach:

1. Deploy main (middleware + web-ui) if not already, then run the acceptance checks below against /admin/mcp → Grants tab.
2. Close this issue referencing merge commit 327ddf8 (PR feat(mcp): MCP as a first-class capability across Orchestrator/Sub-Agent/Skill/Plugin + Control Center (epic #459) #464).

Risks / dependencies:

• Migration collision risk from the epic PR is now resolved (merged); no open action.
• Skill (feat: allow Skills to declare/bind MCP tool capabilities (capability-contract model) #456) and plugin (feat: expose MCP tool access to Plugins via ctx.mcp (PluginContext) #458) grant rows remain Wave 6 scope; plugin grants currently render in a separate Plugins tab, not merged into this matrix — tracked under the Wave 6 issue, not here.

Acceptance criteria (post-deploy verification):

• GET /api/v1/operator/mcp-grants returns holder (agent or sub-agent under parent), server, normalized tool name, verdict, ack validity, blocked state — and 401s without an operator session
• Grants tab renders one card per holder+server with a verdict badge per tool
• A grant whose tool is on the runtime blocklist renders visibly as "blocked by policy" (the bug: top-level-agent MCP tool grants are silently inert (only sub-agent grants work) #457 failure class is not silent)
• Revoke shows a confirm dialog and deletes via DELETE /api/v1/operator/mcp-grants/:grantId
• No mutation surface beyond revoke exists in the Grants tab (grants stay canvas-managed per v1 scope)

---

Automated triage against 327ddf8; posted after adversarial fact-check review.