feat(agent-harness): execute validated remote MCP tools

[iscekic]

No new behavior — the new remote tool checks are not active in the product.

---

Summary

executeMcp adds bounded Model Context Protocol (MCP) discovery and execution through mcp.discover, mcp.call, McpConnection, and RunLimits, without activating the harness.
The maintained CfWorkerJsonSchemaValidator validates a restricted schema vocabulary; invalid arguments block dispatch, and changed configurationVersion or definitionVersion values require rediscovery.
ToolOutcome returns validated data or sanitized failures, preserves the first failure during cancellation, and reports post-dispatch failures as outcome_unknown without replay.

Files

• services/agent-harness/src/tools/mcp.ts — Source; added, 199 lines (+199/-0). Exports the runtime and re-exports McpConnection; consumes ephemeral gateway authorization without copying it into discovery records or failures. Uses ToolRequestSchema to accept only the two MCP requests. Checks both schemas, rejects malformed schemas, references, and unknown keywords, requires output schemas, and rejects tools that require task execution. Supports checked types, object and array rules, enums, constants, numeric and size bounds, and metadata. Paginates discovery, rejects repeated cursors, hashes canonical tool definitions with SHA-256, and returns an empty list when no connections exist. Calls rediscover the selected tool, compare both versions, validate arguments, and return only schema-checked content and structuredContent. A missing server or tool returns an unavailable failure. Shares one deadline and aggregate response budget across connections; separately limits input, discovery records, and result bytes, without timeout resets on progress. Closes clients and clears timers; classifies protocol, parsing, and software development kit (SDK) Zod Mini or Classic errors without provider diagnostics. Only pre-dispatch unavailability or reauthorization failures allow retry.
• services/agent-harness/src/tools/mcp.test.ts — Test; added, 198 lines (+198/-0). Confirms that Ask approval still applies despite read-only hints and trusted-read dispatch input. Covers successful discovery and calls, credential exclusion, schema and argument rejection, stale versions, and sanitized Hypertext Transfer Protocol (HTTP) failures. Exercises malformed or missing results, remote errors, lost or stalled responses, response and output limits, one-time effects, and empty discovery.

Tests: 1 test file added, mcp.test.ts, with 198 added lines and no deleted lines.
Generated: 0 changed files.

---

Visual Changes

Visual Changes: N/A

Verification

No manual tests ran in this round because this level does not activate the harness.
Adapter doubles do not prove live provider behavior.

Reviewer Notes

Human steps: None before merge or after merge.

• The reviewer passed scoped runtime tests, lint, format, and whitespace checks.
• The implementer reported 56 passing tests across the runtime and consumed transport suites.
• Continuous integration (CI) owns repository-wide type and build checks.
• Scope: Level 26 adds only the validated runtime and its tests.
• Composition belongs to A21/A22, presentation to A28–A31, and live evidence to A32 and bot-e2e.
• Repository: Kilo-Org/cloud. Worktree: /Users/igor/Projects/.worktrees/shared-agent-harness-3bb0.
• Review range: shared-agent-harness-3bb0-s25...shared-agent-harness-3bb0-s26.

Runtime verification remains pending at the stack tip. This level adds validated MCP discovery and execution 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
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 ← this PR
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

Files Reviewed (2 files)

• services/agent-harness/src/tools/mcp.ts
• services/agent-harness/src/tools/mcp.test.ts

---

_{Reviewed by grok-4.6 · Input: 397.9K · Output: 29.6K · Cached: 559.1K}

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

[iscekic]

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