feat(agent-harness): authorize scoped MCP gateway connections

[iscekic]

No new behavior — this change prepares connection access checks without enabling them in the product.

---

Summary

The new server-only authorizeHarnessMcp binds mcp.discover and mcp.call to conversation capabilities for authorized Model Context Protocol (MCP) gateway connections in Personal or organization scope.
The strict Invocation schema rejects extra authority fields; discovery returns enabled or assigned configurations, and calls require one server with a current configuration version.
Connections use canonical Hypertext Transfer Protocol Secure (HTTPS) destinations and derived tokens; callers must keep authorization outside client and model state.

Files

• apps/web/src/lib/agent-harness/mcp.ts — added source (+113/-0 lines). Validates identifier formats and binds the capability audience, conversation, dispatch, tool version, argument digest, and backend target. Requires matching canonical routes without embedded credentials and checks configuration versions before and after token issuance. Returns only serverId, string configurationVersion, url, and derived bearer authorization, excluding provider metadata and credentials.

The adapter returns sanitized TRPCError states: BAD_REQUEST for invalid_input or unsafe_destination, FORBIDDEN for access_revoked, and PRECONDITION_FAILED for definition_changed or reauthorization_required.
unavailable_server distinguishes unmatched calls (NOT_FOUND) from failed gateway dependencies (SERVICE_UNAVAILABLE), while discovery with no available configurations returns an empty list.
Tests preserve these recovery states, reject missing gateway configuration, and check that failures omit sensitive messages, credentials, and causes.

Files

• apps/web/src/lib/agent-harness/mcp.test.ts — added test (+283/-0 lines). Covers both scopes, forged or substituted authority, scoped calls, unsafe destinations, stale versions, mint-time version changes, credential isolation, and failures across dependency stages.

Tests: 1 test file added, mcp.test.ts (+283/-0 lines).
Generated: 0 files changed.

---

Visual Changes

Visual Changes: N/A

Verification

No manual test results are attached. This level does not activate the harness, so runtime verification remains pending at the stack tip.

Reviewer Notes

Human steps: None required before merge or after merge.

• The five captured commands passed: formatting, format validation, scoped lint, focused tests, and git diff --check.
• The focused tests passed 31 cases using capability and gateway doubles. These results do not prove live authorization or provider connectivity.
• Continuous integration (CI) owns repository-wide type and build checks.

Transport and runtime remain in a19-transport and a19-runtime.
Composition belongs to A21/A22, presentation to A28–A31, and live evidence to A32 and bot-e2e.

Runtime verification remains pending at the stack tip. This level adds scoped MCP authorization without activating the harness.

Stacked PRs — merge bottom to top. Each level shows only its own diff.

Runtime verification (E2E, user advocacy, simplify) runs on the tip PR over every level.
Every level keeps its own checks, its own bot review, and its own threads; each one is answered on its own PR.
Each level is its own deliverable: it builds and passes its own checks alone.
A finding on a level is repaired on that level, then carried upward with stack.sh forward.

1. shared-agent-harness-3bb0 — chore(agent-harness): register workspaces and enforce CI boundaries #5632
2. shared-agent-harness-3bb0-s2 — feat(agent-harness): define portable domain and snapshots #5637
3. shared-agent-harness-3bb0-s3 — feat(agent-harness): define commands tools and permission policy #5639
4. shared-agent-harness-3bb0-s4 — feat(agent-harness): share client state and cursor recovery #5643
5. shared-agent-harness-3bb0-s5 — feat(agent-harness): persist command intents and execution receipts #5647
6. shared-agent-harness-3bb0-s6 — feat(db): add harness ingress grants and retirement fences #5655
7. shared-agent-harness-3bb0-s7 — feat(agent-harness): deliver legacy history and project durable text #5659
8. shared-agent-harness-3bb0-s8 — feat(agent-harness): authorize durable grants and registered clients #5662
9. shared-agent-harness-3bb0-s9 — feat(agent-harness): fence retirement and retry payload cleanup #5667
10. shared-agent-harness-3bb0-s10 — feat(agent-harness): persist authoritative state in SQLite #5675
11. shared-agent-harness-3bb0-s11 — feat(agent-harness): admit durable runs and revisioned commands #5678
12. shared-agent-harness-3bb0-s12 — feat(agent-harness): recover queued runs and stream checkpointed steps #5688
13. shared-agent-harness-3bb0-s13 — feat(agent-harness): resolve interactions and dispatch tools sequentially #5693
14. shared-agent-harness-3bb0-s14 — feat(agent-harness): fence designated client tool execution #5697
15. shared-agent-harness-3bb0-s15 — feat(agent-harness): synchronize durable snapshots and legacy history #5701
16. shared-agent-harness-3bb0-s16 — feat(agent-harness): reuse authorized invitations with durable replay #5704
17. shared-agent-harness-3bb0-s17 — feat(integrations): bound repository transport for harness reads #5710
18. shared-agent-harness-3bb0-s18 — feat(integrations): expose bounded authorized repository reads #5714
19. shared-agent-harness-3bb0-s19 — feat(agent-harness): expose named authorized resource reads #5718
20. shared-agent-harness-3bb0-s20 — feat(sessions): bound history transport for harness reads #5724
21. shared-agent-harness-3bb0-s21 — feat(agent-harness): read scoped Cloud Agent context and progress #5726
22. shared-agent-harness-3bb0-s22 — fix(agent-harness): preserve ordered Cloud Agent dispatch identity #5731
23. shared-agent-harness-3bb0-s23 — feat(agent-harness): hand coding work to authorized Cloud Agent sessions #5733
24. shared-agent-harness-3bb0-s24 — feat(agent-harness): authorize scoped MCP gateway connections #5737 ← this PR
25. shared-agent-harness-3bb0-s25 — feat(agent-harness): bound MCP gateway transport in the Worker #5740
26. shared-agent-harness-3bb0-s26 — feat(agent-harness): execute validated remote MCP tools #5743
27. shared-agent-harness-3bb0-s27 — refactor(exa): share provider dispatch and usage recording #5746
28. shared-agent-harness-3bb0-s28 — feat(agent-harness): authorize bounded web provider requests #5747
29. shared-agent-harness-3bb0-s29 — feat(agent-harness): normalize web sources and preserve citations #5749
30. shared-agent-harness-3bb0-s30 — feat(agent-harness): define closed internal operation contracts #5753
31. shared-agent-harness-3bb0-s31 — feat(agent-harness): authorize internal maintenance operations #5754
32. shared-agent-harness-3bb0-s32 — feat(agent-harness): authorize named Kilo operation dispatch #5755
33. shared-agent-harness-3bb0-s33 — feat(agent-harness): authorize internal provider operations #5757
34. shared-agent-harness-3bb0-s34 — feat(agent-harness): secure the internal operations endpoint #5758
35. shared-agent-harness-3bb0-s35 — feat(agent-harness): bound and sanitize model streams #5767
36. shared-agent-harness-3bb0-s36 — feat(agent-harness): secure billed model inference #5776
37. shared-agent-harness-3bb0-s37 — test(agent-harness): cover model gateway security boundaries #5777 (tip)

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

Reviewed scoped MCP gateway authorization (authorizeHarnessMcp) and its tests with high confidence: capability binding, destination checks, version comparison, and sanitized recovery states match the stated contract.

Files Reviewed (2 files)

• apps/web/src/lib/agent-harness/mcp.ts
• apps/web/src/lib/agent-harness/mcp.test.ts

---

_{Reviewed by grok-4.6 · Input: 230.8K · Output: 24.4K · Cached: 864.8K}

_{Review guidance: REVIEW.md from base branch shared-agent-harness-3bb0-s23}

[iscekic]

Closing: the owner stopped this workflow section. The branch is retained.