feat: Serve 2026-07-28 MCP requests from a stateless adapter

[jirispilka]

Why

Closes #1140. Part of #1128.

The server speaks only the 2025-era stateful protocol. A 2026-07-28 client carries protocol version, client info and capabilities in a per-request _meta envelope and never handshakes, so it cannot talk to us at all.

What changed

• v2 SDK packages
• New root export createStatelessServer(actorsMcpServer): builds one v2 Server per request (the pattern createMcpHandler's per-request factory is designed for) and serves tools/*, resources/* and prompts/* from a read-only per-request snapshot of the shared facade
• Sibling of the private legacy adapter; each reads shared state only through its own narrow host interface.
• dev_server.ts serves both protocol revisions on one endpoint via the SDK's isLegacyRequest; the stateful path is untouched. Adds DNS-rebinding protection (Host/Origin validation) and framing-before-auth ordering per SEP-2243

Out of scope: Tasks on 2026-07-28 and subscriptions/listen (follow-ups tracked in one issue).

Notes for reviewers ("human"-written)

Tested using MCP Inspector (v2/main branch) — all tools, widgets, and resources work.

Claude below:

Stacked on #1164 → #1163 → #1155. The only PR in the stack touching what apify-mcp-server-internal consumes.

Deliberate behaviors worth knowing:

• subscriptions/listen is not refused — the SDK answers it upstream of our handlers, opening a stream that can never emit. The dev server closes it per request; refusing it outright is follow-up work.
• Stateless instructions omit report-problem — the SDK answers server/discover from constructor-time instructions, which cannot reflect a per-request mode. The tool itself is still gated per request.
• An anonymous stateless request is served report-problem by policy — client-info is optional on the 2026-07-28 envelope, and the blocklist only applies to declared client names.
• Telemetry reports an empty mcp_session_id on this path; what a stateless "session" means for analytics is internal's call.
• upsertTools()/removeToolsByName() bypass the retained sources, so they change the stateful tool list only (documented in code; no callers today).
• close() now resolves instead of throwing (from fix: Drop validator nulling in close() that threw on frozen entries #1163) — any hosted teardown workaround built around a throwing close() is dead code.

Proof it works

• Unit suite: 89 files, 1243 passed + 1 skipped (59 new tests). type-check, lint, format, check:agents clean.
• Stateful/stateless parity asserted per tool category (INTERNAL, ACTOR, ACTOR_MCP) for tools/list and tools/call, plus prompts, resources, telemetry fields, and v2 error projection. Concurrent requests with different identities resolve mode and gating independently. tasks/* answers method-not-found.
• Official conformance suite (@modelcontextprotocol/conformance@0.2.0-alpha.9, --spec-version 2026-07-28) run against the dev server; its two real findings (auth-before-framing, missing DNS-rebinding check) are fixed in this PR. Wiring it into CI with an expected-failures baseline is test: Add MCP 2026-07-28 integration and conformance coverage #1132.
• Live mcpc probe against the legacy stdio server confirmed no v1 regression (initialize instructions, Actor round trip, resources/read, error paths, prompts, logging, Tasks, apps-mode widgets).

---

Generated by Claude Code

[MQ37]

LGTM. I pushed a few small changes - one cosmetic, unifying the destructure to use const instead of let for every variable (only args actually mutates), and I removed removeToolsByName altogether since it's not used anymore. Otherwise no major blocking issues found and I think we can ship this.

[vojtechj-apify]

The Issue 5 requires check on apify-mcp-server-internal, I am running that now. I would consider 3 a merge blocker as a client can't discover the server without already holding a token, and the missing WWW-Authenticate means it can't learn where to get one seems serious.

The 1 and 4 should be fixed before merge. 2 is nice to have.

[vojtechj-apify]

Code review — revised

Scope: 1149d2c...HEAD — the ActorsMcpServer split into a shared facade plus two protocol adapters (legacy_server.ts for the 2025-era v1 SDK, stateless_server.ts for 2026-07-28 via @modelcontextprotocol/server 2.0.0-beta.5), engine modules made protocol-neutral, both eras routed through the dev server's single POST endpoint.

Verification: pnpm run type-check, lint, test:unit (1243 passed), check:agents all pass. Traced every extracted call site (prepareToolCall, executeSyncToolCall, dispatchToolCall, executeToolAndUpdateTask, telemetry) against its pre-PR form — the legacy path looks behaviour-preserving, including the emitLog proxy, sendNotification binding, task cancel-watcher signal, and payment decoration (no double-decoration: sources hold raw entries, toStoredTool clones).

Blocker

3. High — src/dev_server.ts:162: server/discover is answered 401 without a token. The SDK invokes the factory for every modern route before registering server/discover, so the in-factory auth throw blocks negotiation entirely: a client cannot discover the server without already holding a token, and the 401 carries no WWW-Authenticate, so it cannot learn where to get one. Each probe also runs loadToolsFromUrl.

Should fix before merge

1. Medium — src/mcp/server.ts:354: report-problem client gate is bypassable on the stateless path. isReportProblemServable uses clientContext != null as "client known", but the v2 SDK's required envelope keys are only protocol-version + client-capabilities — client-info is optional, so the context is always non-null and isReportProblemBlockedForClient sees an empty name. A blocklisted client that omits io.modelcontextprotocol/client-info gets report-problem listed and callable. The control fails open. Gate on clientContext?.clientInfo?.name.

Nice to have

2. Low — src/dev_server.ts:252: non-JSON Content-Type misroutes modern traffic. express.json() leaves req.body = {}, so isStatelessRequest classifies the request legacy and answers 400 / -32000 "Mcp-Session-Id header is required" instead of the modern entry's 415. The SDK's own isLegacyRequest docs require an isJsonContentType check before dispatching either leg. Spec conformance and debuggability only — correct clients never hit it.

4. Low — src/mcp/server.ts:564-570: the ajvValidate teardown in close() was dropped — intentional?

Pre-PR (1149d2c), close() walked the tool map and nulled each compiled validator before clearing:

for (const tool of this.tools.values()) {
    if (tool.ajvValidate && typeof tool.ajvValidate === 'function') {
        tool.ajvValidate = null;
    }
}
this.tools.clear();

Retracted issue 5.: public→private break on server / taskStore

---

Generated by Claude Code

[MQ37]

Bumped the v2 MCP SDK (@modelcontextprotocol/{core,node,server}) from 2.0.0-beta.5 to stable 2.0.0, now that it's released.

[jirispilka]

Thanks!

1. Keeping as-is: anonymous clients may see report-problem by policy. I was not sure about this but when ahead anyway. Client that does not identify itself correctly will get report-problem
2. No change: couldn’t reproduce; beta.5 and 2.0.0 both return 415.
3. Fixed locally: discovery is unauthenticated, skips tool loading, and 401s include WWW-Authenticate.
4. Intentional: clearing the maps releases validators; nulling throws on frozen defaults. close() now also clears retained source maps.