Outbound MCP client needs protocol/version negotiation for current Streamable HTTP

[serge-ivo]

Problem

The outbound MCP connector currently behaves like a single-era MCP client:

• hardcoded protocol version 2025-06-18
• always sends an initialize request before the real call
• echoes Mcp-Session-Id from initialize into the follow-up request

That worked for earlier Streamable HTTP servers, but the MCP spec has moved. Current Streamable HTTP uses per-request metadata and headers, and the 2026-07-28 revision removes protocol-level sessions and the standalone GET stream. A PAGS agent that claims it can accept any MCP URL needs version negotiation and compatibility fallback, not one hardcoded transport shape.

Why this matters

Even after OAuth works (#258 / #180), authenticated modern MCP servers may still fail because PAGS is speaking the wrong protocol era. The user experience will look like “I connected successfully, but tools are broken.”

Expected behavior

PAGS outbound MCP should detect and interoperate with supported MCP server eras:

• modern Streamable HTTP with required request metadata
• earlier Streamable HTTP initialize/session flow where needed
• clear unsupported-version errors when no compatible path exists

Acceptance criteria

• Client advertises supported protocol versions rather than one hardcoded version.
• Modern Streamable HTTP requests include required MCP request metadata in the body and mirrored HTTP headers.
• Compatibility fallback handles legacy initialize/session servers.
• Server-era detection is cached per endpoint/origin with re-probe on failure.
• Tests cover a modern server, a legacy initialize/session server, version mismatch, and unsupported server response.

Related

• Outbound MCP connector needs OAuth/browser sign-in for authenticated MCP servers #258: OAuth/browser sign-in for authenticated MCP servers
• [connectors] dcr-oauth2 — discovery + dynamic client registration + PKCE for user-named endpoints #180: DCR/OAuth2 for user-named endpoints

Code pointers

• workers/api/src/lib/connectors/mcp.ts
• workers/api/src/lib/connectors/mcp.test.ts

[serge-ivo]

Shipped in 4f77f33 (renumber follow-up 4e88d80).

Verified against HEAD before building — every claim in this issue held:

• hardcoded PROTOCOL_VERSION = "2025-06-18" ✔
• always sent initialize before the real call ✔
• echoed Mcp-Session-Id into the follow-up ✔
• the 2026-07-28 revision is real, and does remove protocol-level sessions, the
  initialize/notifications/initialized handshake and the standalone GET stream, moving
  version + identity + capabilities into per-request _meta
  (io.modelcontextprotocol/protocolVersion / clientInfo / clientCapabilities) mirrored
  into MCP-Protocol-Version / Mcp-Method / Mcp-Name. Checked against the published spec
  rather than taken from the issue body.

The existing dual parsing (plain JSON and SSE-framed) and the Mcp-Session-Id echo were
both correct under the current spec and are kept — parsing is unchanged, and the session
echo is now scoped to the legacy path where it still applies.

What landed

workers/api/src/lib/connectors/mcp.ts is now a dual-era client.

• Modern first. One POST carrying _meta and the mirrored headers. No handshake, no
  session.
• Era detection is the spec's own procedure: attempt modern; on a 4xx inspect the body. A
  reserved MCP code (-32020 HeaderMismatch, -32021 MissingRequiredClientCapability,
  -32022 UnsupportedProtocolVersion) proves the server is modern, so we correct the request
  rather than downgrade it. Anything else — empty body, HTML error page, bare 404/405 — is
  legacy, and the call is redone through initialize.
• Negotiation, not a constant. SUPPORTED_VERSIONS = 2026-07-28, 2025-11-25,
  2025-06-18, 2025-03-26 — deliberately only versions this client can actually produce,
  since advertising an unspeakable version is worse than advertising none. On -32022 we take
  the newest version in both lists and retry, which is also how a modern attempt legitimately
  lands on the handshake path. Disjoint sets fail naming both lists.
• Era cached per endpoint (in-isolate, 10 min TTL, bounded), dropped on any failure, so
  the probe is paid once but a server that upgrades isn't pinned to last week's era.
• Mcp-Name uses the spec's =?base64?…?= sentinel when the remote tool name isn't
  header-safe — that is also a header-injection guard, since the name comes from the server.

Two legacy bugs surfaced while writing it down and are fixed:

1. the follow-up request sent the version we offered, not the one the server negotiated
   in the InitializeResult (the spec says carry the negotiated one);
2. notifications/initialized — a spec MUST — was never sent at all.

Acceptance criteria

• advertises supported versions rather than one hardcoded version
• modern requests include the required metadata in the body and mirrored headers
• compatibility fallback handles legacy initialize/session servers
• era detection cached per endpoint, re-probed on failure
• tests cover a modern server, a legacy initialize/session server, version mismatch (both
  resolvable and disjoint), and an unsupported/unparseable server response

Tests: 52 in mcp.test.ts, all green; full suite 3453/3453 green before the machine got
oversubscribed.

Not in scope here and still open: server/discover (we use the inline-probe path the spec
explicitly permits instead), subscriptions/listen, and the MRTR input_required flow — the
last is #264.