feat(client)!: support stateful streamable-HTTP servers

mcpInitialize now sends notifications/initialized and returns an McpSession
whose Mcp-Session-Id and MCP-Protocol-Version later requests carry. Discovery,
mcpTools and the sidecar bundle pass it on, and reopen it after a failed
call. A protocolVersion that is not printable ASCII is refused before it is
echoed into a header, and a timed-out notification is an McpError. Non-JSON
data frames are skipped, and only a message with result or error and no
method counts as the response. e2e covers the official SDK's stateless and
stateful server transports; the SDK is a devDependency only.

BREAKING CHANGE: mcpInitialize returns McpSession instead of McpServerInfo.

Author: TheGreatAxios

.github/workflows/ci.yml

@@ -17,6 +17,7 @@ jobs:
       - uses: oven-sh/setup-bun@v2
       - run: bun install --frozen-lockfile
       - run: bun run check
+      - run: bun run test:e2e
       - name: node consumer smoke
         run: |
           set -euo pipefail

AGENTS.md

@@ -40,21 +40,22 @@ never hold a server's bearer.
 
 The client in `src/client.ts` is hand-rolled on purpose. It only sends
 `initialize`, `tools/list` and `tools/call`, each as one request awaiting one
-reply; in the sidecar bundle that request goes through a fetch the mediated
+reply, plus the `notifications/initialized` notification; in the sidecar bundle that request goes through a fetch the mediated
 credential handle pins to the server's origin. That needs only JSON-RPC
 framing and reading the matching `data:` frame from an event-stream reply.
 
 The SDK's streamable-HTTP client transport is built for long-lived sessions
 (resumable streams, server-initiated requests) and installs `zod`, `ajv`,
 `express` and more, none of which this package uses.
 
-The cost: the client never sends `Mcp-Session-Id`, so a server that issues
-one on `initialize` and requires it afterwards rejects `tools/list` and
-`tools/call`. Notifications and server-to-client requests are not
-supported either.
+The session a stateful server issues on `initialize` is carried in
+`McpSession` and sent as `Mcp-Session-Id` with `MCP-Protocol-Version` on
+every later request. Resumable streams and server-to-client requests are not
+supported. `e2e/` runs discovery and tool calls against the SDK's stateless
+and stateful server transports; the SDK is a devDependency only.
 
 ## Local development
 
 ```sh
-bun install && bun run check
+bun install && bun run check && bun run test:e2e
 ```

CONTRIBUTING.md

@@ -5,9 +5,10 @@
 ```sh
 bun install
 bun run check
+bun run test:e2e
 ```
 
-`bun run check` runs typecheck, lint, format check and unit tests. `bun run format` rewrites the tree.
+`bun run check` runs typecheck, lint, format check and unit tests. `bun run test:e2e` runs the client against the official SDK's server transports. `bun run format` rewrites the tree.
 
 Contributors sign the [CLA](CLA.md) on their first PR; the CLA bot explains how.
 

README.md

@@ -8,7 +8,7 @@ A Corbits tool pack for the Interchange sidecar that turns each tool on a remote
 2. **The agent never holds the server's token.** Calls go through a mediated credential: a fetch pinned to the server's origin that adds the bearer per request.
 3. **Destructive tools stay behind approval.** Every generated tool starts `ask`-marked, and a tool the server flags `destructiveHint: true` cannot be lowered to `allow`.
 
-It supports `initialize`, `tools/list` and `tools/call` only. It does not send `Mcp-Session-Id`, so servers that require a session are not supported.
+It supports `initialize`, `tools/list` and `tools/call` only, against stateless and stateful (`Mcp-Session-Id`) servers.
 
 ## Install
 
@@ -32,13 +32,13 @@ Lists the tools on a public MCP server:
 import { mcpInitialize, mcpListTools } from "@corbits/mcp";
 
 const url = "https://mcp.deepwiki.com/mcp";
-await mcpInitialize(url);
-for (const tool of await mcpListTools(url)) {
+const session = await mcpInitialize(url);
+for (const tool of await mcpListTools(url, { session })) {
   console.log(`${tool.name}: ${tool.description ?? ""}`);
 }
 ```
 
-Every client call takes `{ fetch, timeoutMs, signal }` as its last argument, for example a fetch that adds an `Authorization` header. `timeoutMs` covers the request and reading its body, and `signal` cancels both. `mcpTools` and `mcpServers` take a `timeoutMs` option, 60 seconds by default, and pass each tool call's abort signal through, so a stalling server fails that call instead of hanging it. A response body or event-stream frame over 4 MiB is refused and the stream cancelled.
+Every client call takes `{ fetch, timeoutMs, signal, session }` as its last argument, for example a fetch that adds an `Authorization` header. `timeoutMs` covers the request and reading its body, and `signal` cancels both. `mcpTools` and `mcpServers` take a `timeoutMs` option, 60 seconds by default, and pass each tool call's abort signal through, so a stalling server fails that call instead of hanging it. A response body or event-stream frame over 4 MiB is refused and the stream cancelled.
 
 ## Where it fits
 
@@ -52,7 +52,7 @@ Every client call takes `{ fetch, timeoutMs, signal }` as its last argument, for
 
 | Export                                            | Entry                         | Purpose                                                                                                           |
 | ------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `mcpInitialize(url, opts?)`                       | `@corbits/mcp`                | Send `initialize`; returns `serverInfo` and `protocolVersion`.                                                    |
+| `mcpInitialize(url, opts?)`                       | `@corbits/mcp`                | Send `initialize` and `notifications/initialized`; returns the `McpSession` to pass to later calls.               |
 | `mcpListTools(url, opts?)`                        | `@corbits/mcp`                | Send `tools/list`; returns `McpTool[]`.                                                                           |
 | `mcpCallTool(url, name, args, opts?)`             | `@corbits/mcp`                | Send `tools/call`; returns `McpToolResult`.                                                                       |
 | `mcpTools(options, env?)`                         | `@corbits/mcp`                | Discover each server live, then build tools. For hosts that can await; servers use `name` and `credentialHandle`. |
@@ -174,6 +174,7 @@ Grant the agent's principal `tool:deepwiki.*` for the whole server, or `tool:dee
 - `@intx/db`, `@intx/hub-api`, `drizzle-orm`, `hono` and `@corbits/credential-http` are optional peers. Install them if you use `@corbits/mcp/hub`. `@corbits/credential-http` replaces `@corbits/credential-mcp`.
 - Discovery with a credential pins to the credential's provider `apiBaseUrl` origin, not to the requested URL's origin. A credential with a secret whose provider has no `apiBaseUrl` is refused, and a URL on another origin needs `extraOrigins`. No origin is allowed by default.
 - `readCredentialSecret` is now `readCredential`, which returns `{ secret, origin? }`. `discoverMcpServer` takes `credential: { secret, origin? }` instead of `secret`.
+- `mcpInitialize` returns an `McpSession` (`protocolVersion`, `sessionId?`, `serverInfo?`) and sends `notifications/initialized`. Pass it as `{ session }` to `mcpListTools` and `mcpCallTool`; a stateful server needs it.
 - `@intx/agent` and `@intx/harness` peers are `^0.4.0`.
 - Discovery rejects authorization-server metadata whose `issuer` differs from the one the protected resource names.