OSPP2: Add a stateless MCP tools entry to Agent Gateway

[BobSong-dev]

Background

Agent Gateway currently establishes request context for LLM traffic. This change adds an explicitly matched MCP tools entry in the same plugin, without replacing the legacy MCP server or AI Proxy.

This PR reuses the Agent Gateway foundation already merged into master in #7133. It does not include commits from, or require merging, another open PR.

The entry implements the tools-only subset of the fixed 2026-07-28 protocol snapshot. It is not a complete MCP Gateway or an OAuth implementation.

Changes

• Add request-local server/discover, tools/list and tools/call dispatch, returning JSON or one final SSE message.
• Validate UTF-8 JSON-RPC, mirrored headers, protocol metadata and Origin; bound request/encoded response sizes and execution deadlines.
• Register tools explicitly and intersect rule permissions with verified server-side grants. Check required client capabilities after authorization and before argument validation or invocation.
• Preserve immutable request/configuration snapshots and cancellation of the current reactive subscription, including concurrent calls using the same client RPC ID.
• Add shared MCP rule configuration, strict Admin save validation and opt-in Starter assembly. Missing identity adapters deny access.
• Provide a disabled-by-default loopback-only JWT/read-only order example and regression coverage. LLM forwarding and legacy MCP/AI Proxy source remain unchanged.

Accept contract

JSON-only clients are intentionally rejected by this entry. The 2026-07-28 Streamable HTTP specification requires clients to advertise and support both application/json and text/event-stream. responseMode selects successful server output, not a different client contract. HTTP 406 and explicit positive-quality media-type enforcement are this entry's strict policy; the specification does not itself mandate that rejection status. Preflight failures remain ordinary JSON. The README and 26 two-mode regression cases now make this distinction explicit, including rejection before body subscription, identity resolution or tool invocation.

Verification

Current local verification uses master 7925422b1, merged normally in 6c045d539, followed by the review clarification in 0c35745b9. Published history was not rewritten.

• Core/Admin: 326 targeted tests across a 48-module reactor, including 26 new Accept cases, 25 upstream registration regressions and 13 WebSocket namespace regressions; zero failures, errors or skips. Checkstyle/RAT passed; Javadoc was explicitly skipped in this run.
• Example: 28 targeted tests and Checkstyle passed; a separate explicit RAT check passed. These are targeted tests, not full-project Java tests.
• The normal-merge candidate was verified before the review-only amendment through real Bootstrap/Admin/H2/WebSocket: 39 entry checks and 12 legacy MCP/AI Proxy coexistence checks passed. The coexistence AI upstream is a controlled fixture.
• At that same candidate, OpenCode 2.0.18 with real DeepSeek V4 Flash successfully called order_status through JSON, SSE and client-side CodeMode. Each actual tool response was correlated with its request ID, the subsequent model request and final reply.
• The amendment changes README, tests and a handler comment only; production behavior is unchanged. The real-network suite was not rerun after this amendment.
• Earlier RISC-V/QEMU verification at a12aa3e59: 218 targeted tests and Checkstyle/RAT passed. RISC-V was not rerun for the updated baseline or the new Accept tests.
• git diff --check passed. Full-project tests, native RISC-V and complete OAuth verification were not run.
• New GitHub CI was triggered for 0c35745b9; the first snapshot has six workflows running and one queued. It is not yet a passing result. The merged master contains the ZooKeeper rollout-race fix from Wait for ZooKeeper deployment rollout in the Dubbo ingress CI #7427; this PR adds no duplicate CI-script patch. The PR remains draft pending the protocol-contract discussion and required checks.

Protocol scope and remaining gaps

The unmodified fixed conformance suite (7169291ec, requirements 2026-07-28) failed at 7c94ab887 and was not rerun in this round. Each transport ran 50 scenarios and 184 actual checks:

• JSON: 109 success, 63 failure, 4 warning, 7 skipped, 1 informational.
• SSE: 110 success, 63 failure, 4 warning, 7 skipped.

The remaining failures cover resources, prompts, completion, media, progress, MRTR, Tasks and custom parameter-header mirroring. These failures remain recorded, not waived or converted to skips. Prompts and resources are paused because there is no confirmed use case; the other extensions are candidates, not an automatic delivery queue. Future tools aggregation, result filtering and call statistics are evaluated separately and are not included here. Complete protocol acceptance remains outstanding.

This PR adds no session lifecycle, initialization handshake, progress stream, task store or remote-target aggregation. Cancellation propagates to the current reactive subscription; it does not guarantee interruption of blocking provider code or rollback of external side effects.

[Aias00]

Draft review note: the overall MCP entry boundary is promising, but the preflight path currently appears to require both JSON and SSE Accept values regardless of response mode. Please confirm JSON-only clients are intentionally rejected, and keep this in draft until the protocol contract and failing K8s check are resolved.

[BobSong-dev]

Thank you for reviewing this, @Aias00.

Yes, rejecting JSON-only clients is intentional for this entry. The 2026-07-28 Streamable HTTP client contract requires clients to advertise and support both JSON and SSE. responseMode only selects the successful server response format. HTTP 406 and explicit positive-quality Accept types are our strict entry policy, not a rejection status mandated by that client requirement.

I have clarified this distinction in the README and added 26 regression cases across both response modes, including checks that rejection happens before body subscription, identity resolution or tool invocation. Core/Admin (326 tests) and the example (28 tests) passed, with Checkstyle and RAT.

I also merged current master normally, including the ZooKeeper rollout-race fix already merged in #7427, and pushed 0c35745b9. New CI is running; I am not treating the earlier CI failure as resolved until this head passes its checks. I will keep the PR in draft pending the checks and your feedback on the clarified contract. No aggregation, prompts/resources or statistics were added.

[Aias00]

Draft review note: the JSON-plus-SSE Accept requirement is now explicit and covered by tests, so the earlier ambiguity is resolved. Please keep the PR in draft until that protocol choice and the broader Agent Gateway MCP contract are ready for stabilization.

[BobSong-dev]

Thank you for the clarification, @Aias00.

I have expanded the README into an explicit tools-only implementation contract covering the fixed version and legacy-client boundary, mirrored headers, authorization, result/error semantics, configuration limits, and cancellation. The protocol choice and strict Accept policy remain unchanged; this documentation is not a claim that the wider contract is finalized.

Commit 3882f857f changes only the README and HTTP tests. It adds 18 regression cases and strengthens the same-RPC-ID cancellation test with the same client-supplied session ID. Local verification passed: 262 targeted tests across a 13-module reactor, with zero failures, errors or skips; Checkstyle and RAT passed. These are local targeted results, not full-project tests or a passing result for the new GitHub CI.

No production behavior, aggregation, prompts/resources or statistics were added. I will keep the PR in draft until the protocol choice and wider contract are ready for stabilization. Thank you for your guidance.