feat(mcp): support MCP 2026-07-28 stateless protocol (MCP v2)

[Yeachan-Heo]

Parent

Part of #4283. Coordinates with #4284 and #4291.

Owner directive

GJC's MCP client/runtime must support MCP v2, specifically the Model Context Protocol 2026-07-28 stateless specification.

References:

• https://aisparkup.com/wiki/mcp-v2
• https://blog.cloudflare.com/mcp-v2/
• canonical MCP specification/version documents linked from those references

The implementation must verify behavior against the canonical specification and official SDK conformance material rather than treating the summary articles as the protocol authority.

Current gap

The current HTTP transport is visibly session-oriented: it performs initialization and persists/sends Mcp-Session-Id; tests assert session renewal/reconnect behavior. MCP 2026-07-28 removes the required initialize/initialized handshake, protocol session, and open-stream dependency from the core request path.

Required client/runtime contract

Protocol negotiation and compatibility

• support MCP protocol version 2026-07-28 for remote Streamable HTTP servers;
• preserve a bounded compatibility path for older sessionful Streamable HTTP servers during the specification's deprecation/migration window;
• protocol selection/fallback must be deterministic, observable, and downgrade-safe—never silently reinterpret an auth/protocol/security failure as permission to downgrade;
• expose effective protocol generation/version through safe diagnostics and /extensions/doctor integration.

Stateless requests

For v2 servers:

• do not require initialize, initialized, Mcp-Session-Id, a sticky transport session, standalone SSE stream, or message replay for ordinary calls;
• include the required per-request protocol version, client identity, and client capability context;
• emit required Mcp-Method and Mcp-Name headers for Streamable HTTP requests where applicable;
• support optional server/discover without making it a mandatory handshake;
• preserve request cancellation, timeout, retry, auth refresh, redirects, SSRF/DNS policy, and connection cleanup without session-state assumptions.

Multi Round-Trip Requests / elicitation

• recognize v2 input_required results;
• convert the requested input into GJC's existing structured ask/workflow-gate surface without exposing private payloads;
• retry the original operation with the accepted input under a stable correlation/idempotency contract;
• handle rejection, cancellation, timeout, repeated input requests, resume/restart boundaries, and unavailable interactive UI explicitly;
• do not fall back to legacy server-initiated elicitation/create over a held stream when operating in strict v2 mode.

Discovery caching and lifecycle

• honor supported ttlMs and cacheScope hints for tools/prompts/resources catalogs without allowing stale authority or cross-server/cross-credential leakage;
• keep deterministic tool ordering and invalidate caches on config/auth/protocol/server identity changes;
• model Active/Deprecated/Removed protocol features in diagnostics so deprecated legacy SSE/session behaviors are visible rather than silently permanent.

Authorization

For v2 HTTP authorization support, implement or explicitly gate the applicable client responsibilities for:

• pre-registered clients and Client ID Metadata Documents (CIMD);
• DCR only as a deprecated compatibility fallback;
• RFC 9207 authorization issuer (iss) verification;
• RFC 8707 canonical MCP server resource audience on authorization/token requests;
• no credential, metadata document, token, query secret, or auth header leakage in diagnostics/UI.

If the current auth subsystem cannot safely deliver the complete v2 authorization contract in one PR, split it into an explicitly linked blocking child before claiming full MCP v2 support; do not label transport-only support as complete protocol support.

Configuration/UI integration

• project/global .gjc MCP entries must allow an explicit protocol preference such as auto, 2026-07-28, or bounded legacy mode using the final schema chosen by implementation;
• /extensions (feat(customization): add /extensions UI with project/global .gjc management and Claude/Codex import #4291) must display configured preference, negotiated effective protocol, compatibility/deprecation status, and v2 capability/diagnostic state without secrets;
• imported Claude Code/Codex MCP definitions should default to safe negotiation and preserve any representable protocol preference without inventing unsupported semantics.

Acceptance tests

1. strict v2 server fixture completes tools/list and tools/call without initialize, Mcp-Session-Id, or open SSE and receives required protocol/method/name/client context.
2. optional server/discover works and its absence does not block direct v2 calls.
3. legacy sessionful fixture still works under explicit/auto compatibility, with downgrade decisions and deprecation status observable.
4. auth/protocol/security failures do not cause unsafe automatic downgrade.
5. input_required produces a structured GJC question, accepted input retries the original request exactly once under correlation/idempotency fencing, and cancel/timeout/repeat/restart cases are covered.
6. ttlMs/cacheScope tests prove bounded caching and invalidation across server URL, credentials, config, protocol, and process/session boundaries.
7. RFC 9207 issuer mismatch and RFC 8707 audience mismatch fail closed; secrets remain redacted.
8. plugin-bundle MCPs, native project/global .gjc MCPs, exact-file config, ACP-supplied MCPs, and subagent inheritance share the same protocol implementation without duplicate ownership/leaks.
9. /extensions and customization doctor consume one authoritative protocol/status observation model.
10. focused transport/auth tests, aggregate coding-agent checks, package/build checks, and an official/conformance-compatible v2 server integration test pass.

Non-goals

• implementing an MCP server in GJC merely to prove client support;
• removing legacy support before its compatibility window and repository policy allow it;
• treating all v2 extensions (Apps, Tasks, enterprise-managed auth) as core support unless separately scoped;
• weakening existing SSRF, redirect, DNS rebinding, stdio, credential, or plugin confinement policy.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]

[Yeachan-Heo]

Implementation ownership started. A dedicated current-dev GJC worktree/session owns the MCP 2026-07-28 stateless transport, MRTR elicitation, caching, auth-conformance, compatibility, and shared protocol-status contract.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]

[Yeachan-Heo]

Owner routing update: this feature lane has been restarted on the current kimi-gpt preset as explicitly directed. The dedicated branch/worktree and all committed/uncommitted artifacts were preserved; the prior DeepSeek/GLM turn was retired. A fresh SDK turn.prompt was accepted and reached in_flight under the Kimi-routed session.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]

[Yeachan-Heo]

Ownership correction for issue #4292:

The current dedicated Kimi-routed tmux/SDK endpoint existed, but its authoritative state showed zero token activity and an unavailable goal snapshot, so the earlier “in_flight” statement was not counted as active execution evidence. The existing one-item lane has now received a fresh accepted SDK control turn with the complete MCP 2026-07-28 protocol, downgrade-safety, input_required, caching, authorization, conformance, and .gjc observation contract.

• base: 290fe1c9f58c4da43da9a40941ff96278379c418
• branch: feat/issue-4292-mcp-v2
• dedicated worktree retained
• accepted command: ec575054-e068-4261-8a07-0f307fc40922
• accepted turn: 9adc3d46-db14-4b6e-af36-7fa9effe930e

The lane must produce observable implementation/research progress before it is counted as fully active ownership. It remains non-terminal until one scoped PR merges to dev or the issue is explicitly closed with evidence.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]

[Yeachan-Heo]

Execution update (kimi-gpt lane, real progress this turn). The prior "in_flight" claim was not backed by token/tool activity; this comment is the first evidence-backed ownership. Worktree gajae-code-4292-mcp-v2 was clean (no uncommitted artifacts to preserve); branch feat/issue-4292-mcp-v2 had zero unique commits and has been fast-forwarded from stale 290fe1c9f5 onto current origin/dev 2067b93976f5bbbe996fd9ec70a997bb0668b527.

Canonical authority verified (primary sources, not the summary articles):

• https://modelcontextprotocol.io/specification/2026-07-28 + basic, basic/transports/streamable-http, basic/versioning, basic/patterns/mrtr, basic/authorization, server/discover, server/utilities/caching
• Source of truth schema: modelcontextprotocol/specification schema/2026-07-28/schema.ts
• Verified contract points: stateless per-request _meta (io.modelcontextprotocol/protocolVersion + clientCapabilities REQUIRED, clientInfo SHOULD), MCP-Protocol-Version/Mcp-Method/Mcp-Name headers with =?base64?...?= sentinel encoding, x-mcp-header param mirroring, no GET stream / Mcp-Session-Id / Last-Event-ID / initialize handshake in the modern era, MRTR input_required (+ opaque requestState echo, fresh JSON-RPC id on retry), server/discover optional-but-implementable, ttlMs/cacheScope caching hints, era detection via 400-body inspection (recognized modern errors -32022/-32021/-32020 never downgrade), auth = OAuth 2.1 + RFC 9728/8414 discovery + RFC 9207 iss validation table + RFC 8707 resource + CIMD preferred / DCR deprecated fallback.

Current-state inventory: runtime-mcp/client.ts is hardwired to protocol 2025-03-26 with a mandatory initialize + notifications/initialized + GET SSE listener; transports/http.ts persists/sends Mcp-Session-Id and DELETEs on close; tool-cache.ts is configHash-keyed with no ttlMs/cacheScope; no elicitation/create client capability exists (ACP maps ui.elicit only).

Bounded slices (durable ledger: 4 goals): (1) protocol preference config (auto|2026-07-28|legacy) + one authoritative observation model for #4288/#4291; (2) strict-v2 stateless transport + deterministic era negotiation + downgrade-safe legacy compatibility; (3) MRTR input_required → structured ask surface + ttlMs/cacheScope caching + auth conformance (RFC 9207/8707, CIMD vs deprecated DCR) or an explicitly linked blocking child; (4) conformance fixtures/tests, doctor + /extensions wiring, one PR to dev.

First concrete seam: runtime-mcp/protocol.ts (new) — protocol generation/version constants, per-request _meta construction, era detection + downgrade-decision types — consumed by client.ts and transports/http.ts without touching stdio or plugin confinement.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]