[FEATURE] Make the remote MCP client spec-compliant and dual-era: initialize fallback and 2026-07-28 request metadata #5192

Activity

1. kwakayama commented on Oct 16, 2026

   

   kwakayama

   on Oct 16, 2026 – with Claude

   Contributor

   More actions

   This was generated by AI during triage.

   Agent Brief

   Category: enhancement

   Summary:
   Make the remote MCP HTTP client interoperate with both MCP eras: send 2026-07-28 request metadata, and fall back to an initialize handshake with session tracking when a server rejects the modern request.

   Current behavior:

   • src/tool/remote-mcp.ts posts tools/list and tools/call as bare JSON-RPC requests. Only caller-supplied headers plus Content-Type and Accept are sent.
   • A code search found no initialize call, no Mcp-Session-Id handling, no MCP-Protocol-Version, Mcp-Method or Mcp-Name header, and no DELETE of a session in this module. The only protocol-version and session-header handling in src/ is in the MCP server code (src/mcp/), not the client.
   • Any non-2xx response surfaces as Remote MCP request failed (<status>).
   • I did not reproduce the gateway failure. The report's Envoy AI Gateway behavior is the author's observation and is unverified here.
   • No duplicate issue was found.

   Desired behavior:

   • Every POST carries MCP-Protocol-Version, Mcp-Method, Mcp-Name (for tools/call) and _meta.io.modelcontextprotocol/protocolVersion in the body, as the 2026-07-28 Streamable HTTP binding requires.
   • On a 400 whose body is not a recognised modern JSON-RPC error, the client:
     • sends initialize, negotiating 2025-06-18 or 2025-11-25;
     • sends notifications/initialized;
     • stores Mcp-Session-Id per origin and sends it on later requests;
     • re-initialises on 404 and retries once;
     • sends DELETE for the session when the run ends.
   • The negotiated era is cached per origin.
   • Servers that accept unlabelled requests keep working. Existing caller-supplied headers, listMeta, _meta and run-correlation behavior, size limits, timeouts and the outbound guard (guardedOutboundFetch) stay unchanged.
   • Bearer headers must not leak into new logs or errors. Session ids must stay scoped per origin and per run, not shared across tenants.

   Key interfaces:

   • remote-mcp tool source (RemoteMCPToolSourceConfig, tools/list and tools/call paths) behind an agent's mcpServers entry with transport.type: "http".
   • MCP Streamable HTTP transport, revisions 2025-06-18, 2025-11-25 and 2026-07-28.
   • Error behavior through the VeryfrontError registry.

   Acceptance criteria:

   • A modern server receives all required headers and _meta fields on tools/list and tools/call.
   • A session-requiring server that answers 400 to the first request gets initialize, notifications/initialized, then the original request with Mcp-Session-Id.
   • 404 on a session triggers one re-initialisation and retry.
   • The session is deleted when the run ends, and the era and session are cached per origin.
   • A modern 400 JSON-RPC error (for example HeaderMismatch) does not trigger the fallback.
   • Regression tests in src/tool/remote-mcp.test.ts use withMockFetch and cover the paths above.
   • Relevant formatting, lint, typecheck, and CI checks pass.
   • Existing behavior outside this issue remains unchanged.

   Out of scope:

   • Unrelated refactors of remote-mcp.ts
   • Server-side MCP changes
   • Gateway-specific workarounds
   • New dependencies

   Verification plan:

   • deno task test:file src/tool/remote-mcp.test.ts
   • deno fmt --check
   • deno task lint:ci
   • deno task typecheck
   • The standard cicd.yml PR checks (lint, typecheck, unit tests)

   Open point for maintainers: the exact definition of a "recognised modern error body" and the session lifetime relative to a run should be confirmed against the 2026-07-28 specification during implementation.

   Handoff: ready for agent

   Thanks @dberesford. I reviewed the report against the current Veryfront Code implementation and reduced it to the Agent Brief above. The remaining work is bounded by the acceptance criteria and verification plan.

   ---

   Generated by Claude Code
2. kwakayama

   added

   enhancementNew feature or requestNew feature or request

   mediumMedium priorityMedium priority

   on Oct 16, 2026
3. dberesford commented on Oct 16, 2026

   

   dberesford

   on Oct 16, 2026

   Author

   More actions

   Correction from the author, after further testing on the same setup (veryfront 0.1.1276, Envoy AI Gateway v1.1.0):

   • "cannot use mcpServers at all today" is too broad. The auth: { type: "headers", headers: () => ... } callback can itself POST initialize and notifications/initialized to the server and return the Mcp-Session-Id it was given, and with that the built-in client's tools/list and tools/call go through a session-requiring gateway. It is a workaround with a cost (one session per request, never closed), not a fix, but it means the gap is in the default lifecycle rather than a hard block.
   • "a local proxy ... hides the client from the gateway's identity and policy checks" was an opinion, not a tested fact: a forwarding intermediary can preserve the bearer. Please read that line as a preference against another hop.
   • Agent Router's stateless 2026-07-28 support: the era detection and fanout pull requests (Resolve Mistral through Veryfront Cloud catalog #2518, chore: bump veryfront for coverage ci release #2545 there) are merged; Tag eval runs for gateway billing reconciliation #2692 is still open, and the v1.2.0 notes say the feature is not yet enabled. I wrote "merged" too loosely.

   The request stands as written in "Proposed Solution": a dual-era client that completes the handshake and carries the session, or sends the 2026-07-28 request metadata.