feat(mcp)!: support both MCP protocol revisions (2025-11-25 and 2026-07-28)

[LukasParke]

@openrouter/mcp now works against any MCP server, whether it speaks 2025-11-25 or the new 2026-07-28 revision. Previously it only spoke the 2025 handshake.

// No configuration needed — the right revision is negotiated per server.
const mcp = await createMCPTools({ url: 'https://mcp.example.com/mcp' });

Correcting this PR's original premise

This PR started as deprecation prep, on my conclusion that no released SDK could speak 2026-07-28. That was wrong. I checked only @modelcontextprotocol/client@2.0.0's default wire behavior — which is indeed 2025-11-25 — and never looked for an opt-in. There is one: ClientOptions.versionNegotiation. So instead of annotating three surfaces as doomed, this PR makes both revisions work.

How it works

protocolNegotiation?: 'legacy' | 'auto' | { pin: string }, defaulting to 'auto'. The SDK itself defaults to 'legacy'; a library whose job is "point it at a server" should reach both eras with nothing configured.

Server	What goes on the wire (verified)
2026-07-28	server/discover, then requests with the _meta envelope + Mcp-Method header. No initialize — the handshake is removed (SEP-2575).
2025-11-25 and earlier	server/discover, then fallback to initialize + notifications/initialized, byte-equivalent to a 2025-only client.

'legacy' skips the probe, which matters on flaky servers: over HTTP a probe timeout is an outage and rejects, where 'legacy' may still connect. { pin } fails loudly rather than falling back.

A silent bug this caught

callTool lost its middle argument in v2. The old three-arg call would have put signal and onprogress in a slot the SDK doesn't read — disabling cancellation and progress streaming with every other test still passing. tests/unit/call-tool-shape.test.ts guards it; mutation-verified that restoring the old shape fails all 3 tests.

Commits

1. chore(mcp)! — dependency swap; all compile-forced changes (specifiers, callTool arity, guard deletion, method-name-first handlers)
2. test(mcp) — dual-era coverage over InMemoryTransport, before behavior changes
3. feat(mcp)! — protocolNegotiation, default 'auto'
4. fix(mcp) — pre-existing staleness gap on the direct rehydrate path
5. docs(mcp) — retire the deprecations this made false
6. chore(mcp) — changeset for 1.0.0

Breaking changes

• OAuth providers must satisfy v2's OAuthClientProvider: change the import specifier; tokens() now returns StoredOAuthTokens (same fields, so most providers compile unchanged). Now re-exported as MCPOAuthClientProvider so consumers stop depending on our dependency's path.
• major → 1.0.0, per @LukasParke's call. Two breaking notes and a dependency major justify declaring the API stable rather than shipping a pre-1.0 minor.
• protocolNegotiation defaults to 'auto' (SDK default: 'legacy'), so every connection's first request is a server/discover probe. Not a connectivity break: with protocolNegotiation unset, a failed connect retries once with 'legacy', so a probe-hostile proxy/WAF/gateway still connects as before. Setting it explicitly — including to 'auto' — opts out of that retry.

Also fixed

• Self-reported clientInfo said 0.1.0 while the package was 0.0.1 — live in the published tarball. Now generated from package.json so it can't drift.
• staleness.maxAgeMs was only checked by createMCPTools; a direct rehydrateMCPTools() replayed snapshots of any age.
• onElicitation un-deprecated — it works on both revisions, since the multi-round-trip driver (SEP-2322) routes input_required through the same handler.

API example

import {
  createMCPTools,
  rehydrateMCPTools,
  MCPCacheWriteError,
  MCPStaleSnapshotError,
  type MCPOAuthClientProvider,
  type MCPProtocolRevision,
} from '@openrouter/mcp';

// Default: probes with `server/discover`, then speaks whichever revision the
// server offers. If the probe is refused — a gateway that rejects unknown
// methods — this retries once with the 2025-era handshake, so a server that
// worked before still connects. No configuration needed.
const mcp = await createMCPTools({ url: 'https://mcp.example.com/mcp' });

// Skip the probe. A performance choice now, not a compatibility one.
const legacy = await createMCPTools({
  url: 'https://mcp.example.com/mcp',
  protocolNegotiation: 'legacy',
});

// Explicit modes are honoured exactly — this fails rather than degrading.
const strict = await createMCPTools({
  url: 'https://mcp.example.com/mcp',
  protocolNegotiation: 'auto',
});

// New export: the two known revisions autocomplete and typo-check, while any
// other string still compiles, so pinning a future revision needs no cast.
const revision: MCPProtocolRevision = '2026-07-28';
await createMCPTools({
  url: 'https://mcp.example.com/mcp',
  protocolNegotiation: { pin: revision },
});

// New export: `staleness.maxAgeMs` is now enforced on every rehydrate path,
// including `reconnectOnExpiry: false`, which previously replayed silently.
try {
  await rehydrateMCPTools({
    snapshot,
    staleness: { maxAgeMs: 60_000 },
    reconnectOnExpiry: false,
  });
} catch (err) {
  if (err instanceof MCPStaleSnapshotError) {
    // Connection was fine, only the re-list failed — accept the cached tools.
    await rehydrateMCPTools({ snapshot, reconnectOnExpiry: false });
  } else {
    throw err;
  }
}

// OAuth providers: type against the new export rather than the SDK path.
const provider: MCPOAuthClientProvider = myProvider;
await createMCPTools({
  url: 'https://mcp.example.com/mcp',
  auth: { kind: 'oauth', provider },
});

// New option: probe ceiling (default 30s) — raise for slow cold starts.
await createMCPTools({ url: 'https://mcp.example.com/mcp', probeTimeoutMs: 60_000 });

// New export: cache writes are best-effort; catch MCPCacheWriteError from
// refresh() to treat a store outage as fatal anyway.
try {
  await mcp.refresh();
} catch (err) {
  if (!(err instanceof MCPCacheWriteError)) throw err;
}

Verification

• 626 tests pass (521 agent + 105 mcp), lint + typecheck + structural gate clean
• New protocol-era.test.ts runs a hand-rolled MCP server over InMemoryTransport — no network, no fixture process, no MCP_TEST_URL gate
• Every new suite mutation-tested, including the review-driven fixes: removing the legacy retry fails 4 degradation tests and removing its explicit-mode guard fails 6 transport tests; reverting closeQuietly to a bare .catch() fails all four sync-throw tests; cacheMode: 'use' fails the forced-re-read test; re-adding sessionId forwarding fails the replay test; swapping the list_changed key for another valid method fails all four dispatch tests

Two field names I got wrong first and corrected: server/discover returns supportedVersions (not protocolVersions), and inputRequests is an object keyed by request id (not an array).

Tracked in DEV-738.

🤖 Generated with Claude Code

[cortex-github-agent]

Summary

Non-breaking MCP groundwork: corrects the self-reported client version, adds the first real coverage for connect()'s transport selection and Streamable HTTP → SSE fallback, and adds @deprecated/README notes for surfaces that revision 2026-07-28 removes. Deferring the migration is well argued and the new tests are structured correctly (SDK transports faked, real connect() executed); the findings below are advisory, not blocking.

Findings (4)

🟡 minor · packages/mcp/src/mcp-connection.ts:21
The version fix is immediately re-broken by its own changeset: .changeset/mcp-2026-07-28-prep.md is a patch bump, so this ships as 0.0.2 while DEFAULT_CLIENT_INFO.version reads '0.0.1'. The "keep in sync" comment is unenforced — no test, typecheck, or lint rule catches divergence. Read the version from package.json or add a guard test asserting DEFAULT_CLIENT_INFO.version === pkg.version.

🟡 minor · packages/mcp/tests/unit/mcp-connection.test.ts:1-241
The 9 new cases never assert anything about clientInfo — neither the default value (the field this PR fixes) nor that options.clientInfo overrides it. The behavior being corrected is the one part of connect() left untested.

🟡 minor · packages/mcp/src/types.ts:98
@deprecated is applied to onElicitation (and SerializedMCPServer.sessionId, cache-types.ts:36) while they remain the only functional path under the pinned SDK and have no in-package replacement. This surfaces strikethrough/deprecation lint in consumers for correct usage; the explanatory prose conveys the same warning without that side effect.

🟡 minor · packages/mcp/src/mcp-connection.ts:150-160
Pre-existing, now newly covered: when the Streamable HTTP attempt fails, the half-initialized client/transport is discarded without close(), so any opened socket or abort controller leaks before the SSE fallback. The new fallback test asserts clientsCreated === 2 but nothing asserts the failed client was cleaned up — worth a follow-up assertion plus a close().catch(() => {}) in the catch block.

[LukasParke]

Migration tracked in DEV-738 (DevEx › Agent SDKs, Backlog).

It carries the full gap analysis — removals with SEP numbers, the new required fields, error renumbering, affected surface in this package, and the published-package constraints. The explicit trigger to start that work is a released SDK that negotiates 2026-07-28 by default, with a note to re-run the wire capture to confirm before committing to it.

[cortex-github-agent]

Summary

Update replaces the hardcoded client version with generated src/version.ts + a drift-guard test, which resolves my main prior finding and does it properly (committed output, documented rationale, turbo inputs updated for scripts/**). One new wrinkle: the changesets "Version Packages" PR will fail version.test.ts because CI's test task only builds upstream deps, so nothing regenerates the file after the bump. Remaining items are the same advisory ones as before; nothing blocking.

Findings (4)

🟡 minor · packages/mcp/scripts/gen-version.mjs:14
NEW: changeset version bumps package.json without regenerating src/version.ts, and CI's pnpm run test does not run mcp's own build (turbo test uses dependsOn: ["^build"] = upstream only, per turbo.json:26). The auto-generated Version Packages PR will therefore fail version.test.ts every release until someone regenerates by hand. Fix at the source: version: pnpm exec changeset version && pnpm --filter @openrouter/mcp gen:version in .github/workflows/publish.yaml, so the regenerated file lands in the changesets commit. The published tarball is unaffected (publish.yaml runs pnpm run build first).

🟡 minor · packages/mcp/tests/unit/mcp-connection.test.ts:96-125
PARTIALLY RESOLVED / still open: version.test.ts now guards constant-vs-package.json drift, but no test asserts connect() actually passes DEFAULT_CLIENT_INFO to new Client(...), nor that options.clientInfo overrides it. The Client fake still discards its constructor argument, so a regression in the wiring (rather than in the constant) would go unnoticed.

🟡 minor · packages/mcp/src/types.ts:98
OPEN (unchanged): @deprecated on onElicitation, and on SerializedMCPServer.sessionId (cache/cache-types.ts:36-45), still marks the only functional path under the pinned SDK with no in-package migration target — strikethrough + downstream deprecation lint for correct usage. See my earlier thread for the suggested prose-only alternative.

🟡 minor · packages/mcp/src/mcp-connection.ts:150-165
OPEN (unchanged, pre-existing): the failed Streamable HTTP client/transport is discarded without close() before the SSE fallback, leaking any opened socket/abort controller; the new fallback test asserts clientsCreated === 2 but not cleanup.

[cortex-github-agent]

Summary

The PR has been rewritten from deprecation prep into a breaking SDK-v2 migration that supports both protocol revisions, with the title, body and changeset now honestly reflecting that scope. The engineering is largely solid — the callTool arity catch and the dual-era InMemoryTransport suite are real value — but two things block: the new 'auto' default can break connections that work today and isn't listed as breaking, and our own client wiring (notably the string-keyed tools/list_changed handler) is not exercised against the real SDK anywhere.

Findings (7)

🟠 major · packages/mcp/src/mcp-connection.ts:110
NEW: defaulting versionNegotiation.mode to 'auto' flips behavior for every existing consumer, and by this PR's own docs (transport-types.ts:16-18) a probe timeout over HTTP "is treated as an outage and rejects, where 'legacy' may still connect" — the SSE fallback re-probes and fails identically (mcp-connection.ts:177-190). Servers/proxies that hang or 5xx on an unknown method regress from working to failing. The changeset lists only the OAuth type change as breaking. Either retry once with 'legacy' on probe failure, default to 'legacy' for a release, or document this as a second breaking change with the escape hatch named.

🟠 major · packages/mcp/src/mcp-connection.ts:127
NEW: setNotificationHandler('notifications/tools/list_changed', …) replaced a compile-checked SDK schema value with a bare string, and nothing verifies it. tests/unit/mcp-connection.test.ts:96 mocks the entire @modelcontextprotocol/client module (handlers are no-ops), and protocol-era.test.ts constructs its own Client instead of calling connect(). A wrong key leaves default-on autoRefreshOnListChanged silently dead with every test green — the same silent-failure class as the callTool arity bug, without a guard. Needs one InMemoryTransport test through our own connect()/makeClient, or an assertion tying the literal to the SDK's exported name.

🟡 minor · packages/mcp/scripts/gen-version.mjs:14
STILL OPEN (raised on the previous head): changeset version bumps package.json without regenerating src/version.ts, and CI's test task is dependsOn: ["^build"] (upstream only, turbo.json:26), so the auto-created Version Packages PR fails version.test.ts — now bumping 0.0.1 → 0.1.0, so it will fail on this release. Fix by appending && pnpm --filter @openrouter/mcp gen:version to the version: command in .github/workflows/publish.yaml.

🟡 minor · packages/mcp/tests/unit/mcp-connection.test.ts:265-306
STILL OPEN: the negotiation suite now records versionNegotiation.mode per client, but the fake Client still discards its first constructor argument, so nothing asserts DEFAULT_CLIENT_INFO reaches the SDK or that options.clientInfo overrides it — the behavior the generated version.ts exists to protect.

3 more finding(s)

🟡 minor · packages/mcp/src/mcp-connection.ts:177-190
STILL OPEN (pre-existing, now sharper): the failed Streamable HTTP client/transport is discarded without close() before the SSE fallback, leaking any socket or in-flight probe request; under 'auto' there is now an extra probe round trip in that window.

🟡 minor · packages/mcp/src/transport-types.ts:29-31
MCPProtocolNegotiation's { pin: string } accepts any string, so { pin: '2026-07-08' } typechecks and fails only at connect time. A literal union with a (string & {}) escape hatch would catch typos at compile time for the two known revisions.

🟡 minor · packages/mcp/tests/unit/protocol-era.test.ts:1-379
This suite characterizes the third-party SDK against a hand-rolled server, so the fake defines the contract it verifies: if v2 changes server/discover's shape, the tests keep passing while real servers diverge. Valuable as documentation of the negotiation model, but it exercises no src/ code — it should not be counted as coverage of this package's dual-era behavior.

[cortex-github-agent]

Summary

This update only touches the release plumbing — root version script, publish.yaml, and a turbo gen:version task — which cleanly resolves the Version-PR breakage I raised. Both blocking findings from the previous review are untouched: the 'auto' negotiation default can still fail where today's behavior succeeds and isn't listed as breaking, and the string-keyed notifications/tools/list_changed registration is still verified nowhere.

Findings (7)

🟠 major · packages/mcp/src/mcp-connection.ts:110
UNCHANGED / STILL OPEN: versionNegotiation.mode still defaults to 'auto', so every existing consumer starts probing with server/discover; per this PR's own docs a probe timeout over HTTP rejects where 'legacy' would have connected, and the SSE fallback re-probes identically (mcp-connection.ts:177-190). Still absent from the changeset's Breaking section. Fix per my inline thread: retry once with 'legacy' on probe failure, or default to 'legacy', or document it as breaking with the escape hatch named.

🟠 major · packages/mcp/src/mcp-connection.ts:127
UNCHANGED / STILL OPEN: setNotificationHandler('notifications/tools/list_changed', …) replaced a compile-checked SDK schema with a bare string that no test exercises — tests/unit/mcp-connection.test.ts:96 stubs the handler as a no-op and protocol-era.test.ts never calls our connect(). Default-on autoRefreshOnListChanged can be silently dead with the whole suite green.

🟡 minor · package.json:15
NEW: the version script appends pnpm install --lockfile-only, which re-resolves all ranges during changeset version. Since the bump changes no dependency ranges (internal deps are workspace:*), its only effect is to smuggle unrelated transitive resolution bumps into the auto-generated release commit. Drop it, or bump the lockfile in a separate reviewable PR.

🟡 minor · packages/mcp/tests/unit/mcp-connection.test.ts:265-306
STILL OPEN: the fake Client records versionNegotiation.mode but discards its first constructor argument, so nothing asserts DEFAULT_CLIENT_INFO reaches the SDK or that options.clientInfo overrides it — the behavior the new generated version.ts exists to protect.

3 more finding(s)

🟡 minor · packages/mcp/src/mcp-connection.ts:177-190
STILL OPEN (pre-existing): the failed Streamable HTTP client/transport is discarded without close() before the SSE fallback; under 'auto' that window now also contains an in-flight probe request.

🟡 minor · packages/mcp/src/transport-types.ts:29-31
STILL OPEN: { pin: string } accepts any string, so a mistyped revision typechecks and fails only at connect time.

⚪ nit · turbo.json:1-88
The file was reformatted to one array element per line, turning a 2-line functional change (gen:version task) into a ~50-line diff in a shared root config that pnpm lint does not cover. Worth reverting the cosmetic churn so the release-plumbing change reads on its own.

[devin-ai-integration]

Re-review at e4c0273

Verified locally at this head: pnpm typecheck, pnpm lint, pnpm test all clean (590 tests: 521 agent + 69 mcp).

The release fix is correct

The chain publish.yaml → pnpm run version → changeset version && turbo run gen:version closes the Version-PR breakage: packages/mcp/src/version.ts is regenerated in the same commit that bumps package.json, so tests/unit/version.test.ts can't fail on the release PR. The gen:version turbo task (uncached, package.json in / src/version.ts out) generalizes it to any future package with committed generated output. packages/mcp is the only package with a gen:version script today, so turbo run gen:version is a no-op elsewhere.

Two nits on that commit:

1. pnpm install --lockfile-only — agreeing with the suggestion to drop it, but for a weaker reason than "it re-resolves every range". All internal deps are workspace:*, so changeset version cannot change a single specifier, and pnpm install does not upgrade specifiers that the existing lockfile already satisfies. So the step is a no-op in the expected case rather than a silent-bump hazard — but a no-op in the release commit is still worth deleting, since the failure mode it does have (a lockfile diff nobody is reviewing) has no upside.
2. turbo.json was reformatted wholesale — every array expanded to one element per line, turning a 5-line addition into a 61-line diff. pnpm run lint is biome check packages/*/src packages/*/tests, so nothing in CI formats root turbo.json; the reformat isn't required by any tool. Restoring the original compact style would make the diff show only the gen:version task.

setNotificationHandler('notifications/tools/list_changed', …) — this one is a false positive

The concern was that a compile-checked SDK schema value was replaced by a bare string that no test verifies, so an SDK rename could silently kill tools/list_changed auto-refresh with the suite green. The string is compile-checked. SDK v2's two-arg overload is generic over a literal union:

setNotificationHandler<M extends NotificationMethod>(
  method: M,
  handler: (notification: NotificationTypeMap[M]) => void | Promise<void>,
): void;

(NotificationMethod = Exclude<ClientNotification['method'] | ServerNotification['method'], TaskNotificationMethod>, index-D4xIIEF6.d.mts:708,2352.) The three-arg overload is the only one that takes method: string, and it requires a schema bundle as its second argument, which this call does not pass. Empirically, mutating the literal in the worktree and running tsc --noEmit:

src/mcp-connection.ts(127,33): error TS2345: Argument of type '"notifications/tools/list_changedX"'
  is not assignable to parameter of type 'NotificationMethod'.
src/mcp-connection.ts(120,5):  error TS2345: Argument of type '"elicitation/createX"'
  is not assignable to parameter of type 'RequestMethod'.

So a rename in the SDK breaks the build exactly as the old schema-value import did — this is not the callTool-arity class of silent failure, and the proposed "assert the literal equals whatever the SDK exports" guard is already enforced by the type system. The residual gap is narrower and worth stating precisely: nothing proves the handler fires, so an SDK change that keeps the method in the union but stops routing tool-list changes through notification handlers would go unnoticed. That's an InMemoryTransport test driving connect(), and it's a nice-to-have, not a blocker.

The 'auto' default — still open, and I agree it needs an answer

versionNegotiation.mode defaults to 'auto' where the SDK defaults to 'legacy', so every existing consumer's first request after upgrading becomes a server/discover probe. By this PR's own documentation a probe timeout over HTTP is an outage and rejects, and the SSE fallback re-probes and fails the same way — so a gateway that hangs or 5xx's on an unknown method goes from working to failing on a version bump.

The current head answers this with a code comment at mcp-connection.ts:174-178. That documents the failure mode where a reader of the fallback path will find it, but .changeset/mcp-dual-protocol-revision.md still lists only the OAuth type change under Breaking, so the consumer who reads the changelog and not the source learns nothing. At minimum that changeset needs a second Breaking bullet naming protocolNegotiation: 'legacy' as the escape hatch.

My preference is the retry: on connect failure under 'auto' when the caller didn't set protocolNegotiation explicitly, retry once with 'legacy' before surfacing MCPConnectionError. That makes 'auto' strictly additive — modern servers get the new era, everything else lands exactly where it does today — and it preserves the "point it at a server and it works" premise that motivated the non-SDK default in the first place. Defaulting to 'legacy' also resolves it, but contradicts that premise for a release. The cost of the retry is one extra attempt on the already-failing path, which is the path where latency matters least.

Changeset code example

.changeset/mcp-dual-protocol-revision.md adds a public option (protocolNegotiation) and a new export (MCPOAuthClientProvider) with no fenced code block. .agents/skills/public-api-examples/SKILL.md requires one in the changeset ("Always") for any public-API change. A three-line ts block showing createMCPTools({ url, protocolNegotiation: 'legacy' }) satisfies it and makes the generated CHANGELOG self-documenting.

structural-gate — the failure is inherited baseline drift, not this PR

Reproduced locally with sentrux 0.5.7. The gate compares against the committed .sentrux/baseline.json, not against main or HEAD~1, and v0.5.7's threshold is a coupling increase greater than 0.05.

tree	baseline coupling	measured	delta	gate
origin/main	0.4286	0.47	+0.043	✓ passes (just under 0.05)
this PR	0.4286	0.4837	+0.055	✗ DEGRADED

The baseline on both trees is the same stale file (133 import edges, recorded when the repo was less than half its current size). Main has already drifted +0.043 against it; this PR adds ~+0.005 more and tips it over.

That +0.005 is also not new coupling. Holding non-source files constant, base source measures 151 cross-module edges over 309 import edges (0.4790) and head measures 151 over 306 (0.4837) — the numerator is unchanged and the ratio moves because consolidating six @modelcontextprotocol/sdk/* subpath imports into one @modelcontextprotocol/client import removed three resolved edges. A denominator effect. The PR also takes cycles 1 → 0 and quality 5094 → 6088.

So the gate is firing on accumulated main drift with this PR's rounding error on top. The mechanism sentrux offers is sentrux gate --save (no delta allowance, no per-rule suppression, no baseline subcommand); precedent for using it is #73's fcbf9aa. Cleanest sequencing, and the human call I'd ask for:

• refresh the baseline on main in its own one-file PR, which retires the +0.043 that main has already accumulated and is reviewable as exactly that;
• then this PR's own +0.005 passes on its merits and the gate keeps its regression-detecting power here.

Refreshing on this branch instead also turns the check green, but folds main's drift into an MCP PR where nobody is looking for it.

Verdict

The release fix is right. Blocking on the 'auto' default being documented as breaking (or fallback-retried); the notification-handler finding is refuted and shouldn't hold the PR. structural-gate needs the baseline decision above, not a code change.

[cortex-github-agent]

Summary

This update closes the 'auto' default finding the way I said would be acceptable — a second explicit Breaking bullet in the changeset naming the failure mode (gateways that hang or 5xx on unknown methods) and protocolNegotiation: 'legacy' as the exact opt-out — and drops the lockfile side effect plus the turbo.json reformatting churn. One blocking item is left untouched: the notifications/tools/list_changed handler key is verified by no test, so default-on auto-refresh can be silently dead.

Findings (4)

🟠 major · packages/mcp/src/mcp-connection.ts:127
STILL OPEN, now the only blocker: setNotificationHandler('notifications/tools/list_changed', …) replaced a compile-checked SDK schema value with a bare string that nothing exercises — tests/unit/mcp-connection.test.ts:96 stubs it as a no-op and protocol-era.test.ts drives its own Client, never our connect(). If the key or the dispatch path is wrong, default-on autoRefreshOnListChanged fails silently with all 590 tests green, the same class of bug as the callTool arity fix this PR guards. Narrowed ask: expose a seam (export makeClient, or let connect() accept a transport) and add one InMemoryTransport case where the fake server emits the notification and the setToolListChangedHandler callback fires. If v2 types the method parameter as a literal union, say so — mutating the string and showing typecheck fails would satisfy the key half, but the dispatch half still needs the test.

🟡 minor · packages/mcp/tests/unit/mcp-connection.test.ts:265-306
STILL OPEN: the fake Client records versionNegotiation.mode but discards _info, so nothing asserts DEFAULT_CLIENT_INFO reaches the SDK or that options.clientInfo overrides it — the behavior the generated version.ts exists to protect.

🟡 minor · packages/mcp/src/mcp-connection.ts:177-190
STILL OPEN (pre-existing): the failed Streamable HTTP client/transport is discarded without close() before the SSE fallback; under the new 'auto' default that window also holds an in-flight probe.

🟡 minor · packages/mcp/src/transport-types.ts:29-31
STILL OPEN: { pin: string } accepts any string, so a mistyped revision typechecks and only fails at connect time. A literal union with a (string & {}) escape hatch would catch the two known revisions' typos at compile time.

[cortex-github-agent]

cortex panel verdict: comment — details in the consolidated review comment.

[cortex-github-agent]

cortex panel verdict: request changes — details in the consolidated review comment.

[LukasParke]

Re: cortex review on 75740cc —

README Node 20 (fixed, 328c23a): the install section now states the Node 20+ floor and where it comes from, so consumers learn it during setup rather than from an install warning.

cacheCredentials JSDoc (fixed, 328c23a): the hover doc no longer promises a persisted "session". It now says exactly what is stored (bearer/header values or the OAuth provider's current tokens) and that session ids are never serialized — SEP-2567 removed protocol sessions and a rehydrate always performs a fresh handshake.

list_resources cacheMode configurability (nit — not taking): keeping 'refresh' unconditional is deliberate, and the comment block above listRequestOptions carries the full reasoning. A listing's one job is to say what exists now: a model that creates a resource and immediately lists must see it, or the write reads as silently failed. Making that configurable adds a public API surface whose only use is opting into confusing-the-model, to save a round trip on a call that is already cheap (name + URI + metadata — the contents, which are the expensive part, still honour the server's ttlMs). If a real workload surfaces where listing volume matters, a scoped option can ship then without a breaking change — the default would stay 'refresh' either way.

[cortex-github-agent]

cortex panel verdict: comment — details in the consolidated review comment.

[cortex-github-agent]

cortex panel verdict: comment — details in the consolidated review comment.

[cortex-github-agent]

cortex panel verdict: approve — details in the consolidated review comment.