feat(eve): add stateful MCP session reattach

[allenzhou101]

Summary

Adds opt-in stateful MCP session reattach for Streamable HTTP MCP connections:

• defineMcpClientConnection({ session: { mode: "stateful" } })
• persists framework-owned MCP session metadata in session.state
• rehydrates @ai-sdk/mcp through native initialSessionId, initialProtocolVersion, initialInitializeResult, onSessionIdChange, and onSessionExpired hooks
• retries once with a fresh MCP session when a saved session expires with 404

Credit

This PR builds on the API direction and connection-provider scaffolding from #331 by @ckblockit. The implementation commit carries Chung Eun Kim as a co-author and includes their DCO signoff from the original PR.

Notes

This keeps the useful public shape from #331, but avoids the custom fetch/header wrapper now that @ai-sdk/mcp@2.0.1 exposes the protocol-native hooks.

session: { mode: "stateful" } is intentionally opt-in. The default remains stateless, and docs point authors to defineState() for semantic app state that should survive upstream MCP session expiry.

Railway remote MCP smoke: https://mcp.railway.com is a protected Streamable HTTP MCP endpoint. Its protected-resource metadata advertises https://backboard.railway.com as the OAuth server, and unauthenticated initialize returns 401 with WWW-Authenticate: Bearer ... resource_metadata=.... A built eve McpConnectionClient pointed at Railway classifies that response as ConnectionAuthorizationRequiredError without creating/persisting an MCP session slot. Full listTools/tool-call validation requires completing Railway OAuth with a user identity; Railway remote MCP does not accept project tokens.

Verification

• pnpm install
• pnpm --filter eve run build:compiled
• pnpm --filter eve exec vitest run --config vitest.unit.config.ts src/runtime/connections/mcp-client.test.ts src/runtime/connections/mcp-session-store.test.ts src/context/providers/connection.test.ts src/runtime/connections/registry.test.ts src/runtime/resolve-connection.test.ts src/public/definitions/connections/mcp.test.ts src/internal/authored-definition/connection.test.ts
• pnpm --filter eve run typecheck
• pnpm changeset status --since=origin/main
• pnpm run guard:invariants
• pnpm run docs:check
• git diff --check
• pnpm --filter eve run build
• curl -i -X POST https://mcp.railway.com ... initialize -> 401 Authentication required
• PATH=/opt/homebrew/bin:$PATH npm run typecheck from railway-mcp-test-agent/
• built-package smoke with McpConnectionClient({ url: "https://mcp.railway.com", session: { mode: "stateful" } }) -> ConnectionAuthorizationRequiredError

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
eve-docs	Ready	Preview, Comment, Open in v0	Jun 26, 2026 8:44pm

[github-actions]

Bundle + Package Summary: apps/fixtures/weather-agent

Key takeaways

• No notable deltas vs main (ad467e8).

Delta vs main (ad467e8)

Area	Metric	Baseline	Current	Delta
Package	Packed tarball	3.47 MB	3.47 MB	+4.6 kB ⚠️
Package	Unpacked publish size	12.60 MB	12.61 MB	+10.6 kB ⚠️
Package	Installed footprint	52.58 MB	52.59 MB	+10.6 kB ⚠️
Package	Published files	2359	2361	+2
Package	Installed files	5567	5569	+2
Runtime	Unique function payloads	2	2	0
Runtime	Total function bytes	9.70 MB	9.71 MB	+6.8 kB ⚠️
Runtime	Public routes	9	9	0

Changed function payloads vs main (ad467e8) (2)

Function	Status	Baseline	Current	Delta	Route changes
functions/.well-known/workflow/v1/flow.func	changed	5.71 MB	5.72 MB	+3.5 kB ⚠️	none
functions/__server.func	changed	3.99 MB	3.99 MB	+3.4 kB ⚠️	none

Build Metadata

• Preset: vercel
• Nitro: nitro@3.0.260610-beta
• Output directory: apps/fixtures/weather-agent/.vercel/output
• Build metadata timestamp: 2026-06-26T20:44:21.801Z
• Route aliases: 9 public, 1 internal (10 total aliases)
• Vercel routes in config: 10
• Severity legend: 🔴 dominant/large, 🟠 notable, 🟡 watch, ⚪ small

Package Drill-Down

Package Details

• Package: eve@0.15.5
• Package directory: packages/eve
• Tarball: 3.47 MB (eve-0.15.5.tgz)
• Unpacked payload: 12.61 MB across 2361 published files
• Installed footprint: 52.59 MB across 5569 installed files
• Installed root package: 11.33 MB
• Installed dependencies: 41.26 MB
• Runtime dependencies: 1
• Peer dependencies: 12 (11 optional)

Installed footprint is measured from an isolated temporary npm install of the packed tarball.

Heavy installed dependencies

• @rolldown/binding-linux-x64-gnu: 20.26 MB (38.5%)
• eve: 11.33 MB (21.5%)
• ai: 6.26 MB (11.9%)
• zod: 5.04 MB (9.6%)
• nitro: 2.41 MB (4.6%)

Publish payload breakdown

Published file size
🟠 dist/src/compiled/experimental-ai-sdk-code-mo... [####....................] 1.51 MB 11.9%
🟡 dist/src/compiled/@workflow/core/runtime.js      [##......................] 788.4 kB 6.3%
🟡 dist/src/compiled/@vercel/sandbox/index.js       [##......................] 632.0 kB 5.0%
🟡 dist/src/compiled/@chat-adapter/slack/index.js   [#.......................] 438.4 kB 3.5%
🟡 dist/src/compiled/_chunks/workflow/attribute-... [#.......................] 371.6 kB 2.9%
🔴 Other published files                            [########################] 8.87 MB 70.4%

Installed footprint breakdown

Installed package size
🔴 @rolldown/binding-linux-x64-gnu [########################] 20.26 MB 38.5%
🔴 eve                             [#############...........] 11.33 MB 21.5%
🔴 ai                              [#######.................] 6.26 MB 11.9%
🔴 zod                             [######..................] 5.04 MB 9.6%
🟠 nitro                           [###.....................] 2.41 MB 4.6%
🟡 rolldown                        [#.......................] 771.7 kB 1.5%
🔴 Other installed packages        [########................] 6.52 MB 12.4%

Runtime dependencies (1)

Package	Range	Notes
nitro	3.0.260610-beta

Peer dependencies (12)

Package	Range	Notes
@opentelemetry/api	^1.0.0	optional peer
@sveltejs/kit	^2.0.0	optional peer
ai	catalog:
braintrust	^3.0.0	optional peer
just-bash	^3.0.0	optional peer
microsandbox	^0.5.0	optional peer
next	^16.0.0	optional peer
nuxt	^4.0.0	optional peer
react	^19.0.0	optional peer
svelte	^5.0.0	optional peer
vite	^8.0.0	optional peer
vue	^3.5.0	optional peer

Function Drill-Down

Payload Size Graph

Unique function payload size and share of total
🔴 functions/.well-known/workflow/v1/flow.func     [########################] 5.72 MB 58.9%
🔴 functions/__server.func                         [#################.......] 3.99 MB 41.1%

Top Function Payloads

🟠 functions/.well-known/workflow/v1/flow.func • 1 public route • 5.72 MB

Metric	Value
Public routes	/.well-known/workflow/v1/flow
Runtime	nodejs24.x
Handler	index.mjs
Payload	5.72 MB
Function files	5.72 MB across 26 files
Traced dependencies	0 B
Signal	🟠 Bundled file __eve_nitro_handler__.mjs is 1.95 MB (34.1%)

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 __eve_nitro_handler__.mjs              [########################] 1.95 MB 34.1%
🟠 _chunks/runtime.mjs                    [############............] 975.4 kB 17.1%
🟡 _chunks/sandbox.mjs                    [#########...............] 766.0 kB 13.4%
🟡 _chunks/attribute-changes-DUxG-Gic.mjs [######..................] 473.2 kB 8.3%
🟡 _libs/@ai-sdk/gateway+[...].mjs        [#####...................] 413.5 kB 7.2%
🟠 Other bundled files                    [##############..........] 1.14 MB 19.9%

🧾 Vercel Config

{
  "handler": "index.mjs",
  "launcherType": "Nodejs",
  "shouldAddHelpers": false,
  "supportsResponseStreaming": true,
  "runtime": "nodejs24.x",
  "environment": {
    "NODE_OPTIONS": "--experimental-require-module"
  },
  "maxDuration": "max",
  "experimentalTriggers": [
    {
      "type": "queue/v2beta",
      "topic": "__eve776561746865722d6167656e74_wkf_workflow_*",
      "consumer": "default",
      "retryAfterSeconds": 5,
      "initialDelaySeconds": 0
    }
  ]
}

---

🟠 functions/__server.func • 8 public routes, 1 internal alias • 3.99 MB

Metric	Value
Public routes	/ /eve/v1/callback/[token] /eve/v1/connections/[name]/callback/[token] /eve/v1/health /eve/v1/info /eve/v1/session /eve/v1/session/[sessionId] /eve/v1/session/[sessionId]/stream
Internal aliases	/__server
Runtime	nodejs24.x
Handler	index.mjs
Payload	3.99 MB
Function files	3.99 MB across 21 files
Traced dependencies	0 B
Signal	🟠 Bundled file index.mjs is 1.52 MB (38.1%)

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 index.mjs                              [########################] 1.52 MB 38.1%
🟠 _chunks/runtime.mjs                    [##############..........] 883.8 kB 22.1%
🟠 _chunks/sandbox.mjs                    [############............] 766.0 kB 19.2%
🟡 _chunks/attribute-changes-DUxG-Gic.mjs [#######.................] 448.9 kB 11.2%
⚪ _libs/zod.mjs                          [##......................] 114.2 kB 2.9%
🟡 Other bundled files                    [####....................] 258.8 kB 6.5%

🧾 Vercel Config

{
  "handler": "index.mjs",
  "launcherType": "Nodejs",
  "shouldAddHelpers": false,
  "supportsResponseStreaming": true,
  "runtime": "nodejs24.x"
}