@goke/mcp 0.0.12 → 0.1.0

package/README.md

@@ -25,7 +25,7 @@ MCP server                        Your CLI
 
 1. **Discover** — calls `tools/list` on the MCP server to get every tool + its JSON Schema
 2. **Register** — creates a CLI command per tool with `--options` derived from the schema
-3. **Cache** — tools and session ID are cached for 1 hour (no network on subsequent runs). Expired cache is still used when a live fetch is impossible (no token, 401 on `--help`)
+3. **Cache** — tool schemas are cached for 1 hour (no network on subsequent runs). Expired cache is still used when a live fetch is impossible (no token, 401 on `--help`)
 4. **Execute** — on invocation, connects to the server and calls the tool with coerced arguments
 5. **OAuth** — if the server returns 401, automatically opens the browser for OAuth, then retries. `--help`, `--version`, `completions`, and no-args never start OAuth
 
@@ -55,9 +55,9 @@ cli.completions()
 cli.parse()
 ```
 
-Always pass `getMcpUrl`. Do not return `undefined` just because the user has no token. `--help` and no-args must still run so the CLI can show `config` / login instructions.
+If the MCP server is HTTP, pass `getMcpUrl` even when the user has no token. `--help` and no-args must still run so the CLI can show `config` / login instructions. Use `getMcpTransport` when you need stdio or a custom transport.
 
-For a Bearer token, pass `getHeaders` instead of a custom transport:
+For an HTTP Bearer token, pass `getHeaders`:
 
 ```ts
 await addMcpCommands({
@@ -199,8 +199,8 @@ When you expose a cli as a **remote** MCP (over `StreamableHTTPServerTransport`,
 The recipe is:
 
 1. Define the cli **once**.
-2. On every new MCP session, **clone** the cli with per-tenant `{ cwd, env, fs, stdin }` and mount it on a fresh session-scoped `Server` via `addCliToolsToMcp({ cli: tenantClone, server })`.
-3. Inside command actions, always use the **injected** `ctx` — `ctx.fs`, `ctx.process.cwd`, `ctx.process.env`, `ctx.console.log` — instead of the Node globals. `@goke/mcp` wires each tool call into the tenant's cloned context, but only code that goes through `ctx` participates in that isolation.
+2. On every HTTP POST, **clone** the cli with per-tenant `{ cwd, env, fs, stdin }` from the request auth (header, cookie, JWT). Mount it on a fresh `Server` via `addCliToolsToMcp({ cli: tenantClone, server })`.
+3. Inside command actions, always use the **injected** `ctx` (`ctx.fs`, `ctx.process.cwd`, `ctx.process.env`, `ctx.console.log`) instead of the Node globals. `@goke/mcp` wires each tool call into the tenant's cloned context, but only code that goes through `ctx` participates in that isolation.
 
 ### Write commands against `ctx`
 
@@ -231,64 +231,36 @@ cli
 
 `ctx.fs` satisfies the `GokeFs` interface — a Node-compatible async filesystem API. You can point it at a real directory, a virtual in-memory store, an S3 bucket adapter, a `memfs`, or anything else you can wrap behind that interface.
 
-### Clone the cli per session
+### Clone the cli per request
 
 The MCP SDK ships `WebStandardStreamableHTTPServerTransport`, which accepts a Web-Standard `Request` and returns a `Response`. That one shape plugs directly into **any** web framework that speaks web-standard: [Spiceflow](https://github.com/remorses/spiceflow), Cloudflare Workers, Deno, Bun, Next.js route handlers, SvelteKit endpoints, or a raw `fetch`-based handler. No Express, no `node:http` wiring, no framework lock-in.
 
+Do **not** keep a `Map` of transports keyed by `Mcp-Session-Id`. Tenant state lives in durable storage. Each POST clones the cli from the request auth.
+
 You build one `handleMcpRequest(request: Request): Promise<Response>` function and mount it wherever you route HTTP:
 
 ```ts
-import { randomUUID } from "node:crypto"
 import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js"
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js"
-import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js"
 import { addCliToolsToMcp } from "@goke/mcp"
 import type { GokeFs } from "goke"
 
-// Wherever you store per-user state — DB, Redis, config files, etc.
 declare function resolveTenant(tenantId: string): {
   cwd: string
   env: Record<string, string>
-  fs: GokeFs   // your filesystem adapter
+  fs: GokeFs
 }
 
-const transports = new Map<string, WebStandardStreamableHTTPServerTransport>()
-
 export async function handleMcpRequest(request: Request): Promise<Response> {
-  // Pre-parse the body so we can use it for both routing decisions
-  // (is this an `initialize` request?) and as the pre-parsed body
-  // forwarded to the transport via `HandleRequestOptions.parsedBody`.
   let parsedBody: unknown
   if (request.method === "POST") {
     parsedBody = await request.clone().json().catch(() => undefined)
   }
 
-  const sessionId = request.headers.get("mcp-session-id")
-
-  // Existing session — route to its transport.
-  if (sessionId && transports.has(sessionId)) {
-    return transports.get(sessionId)!.handleRequest(request, { parsedBody })
-  }
-
-  // No session yet — must be an `initialize` request.
-  if (!isInitializeRequest(parsedBody)) {
-    return Response.json(
-      {
-        jsonrpc: "2.0",
-        error: { code: -32000, message: "Bad Request: No valid session ID provided" },
-        id: null,
-      },
-      { status: 400 },
-    )
-  }
-
-  // Derive the tenant from whatever header/cookie/JWT you use.
   const tenantId = request.headers.get("x-tenant-id")
   if (!tenantId) return new Response("missing x-tenant-id", { status: 401 })
   const tenant = resolveTenant(tenantId)
 
-  // Clone the base cli with tenant-specific cwd/env/fs. Every tool
-  // call on this session now sees the tenant's state via `ctx`.
   const tenantCli = baseCli.clone({
     cwd: tenant.cwd,
     env: { ...tenant.env, TENANT_ID: tenantId },
@@ -302,22 +274,17 @@ export async function handleMcpRequest(request: Request): Promise<Response> {
   addCliToolsToMcp({ cli: tenantCli, server: mcpServer })
 
   const transport = new WebStandardStreamableHTTPServerTransport({
-    sessionIdGenerator: () => randomUUID(),
-    enableJsonResponse: true, // pure request/response; no SSE to manage
-    onsessioninitialized: (sid) => {
-      transports.set(sid, transport)
-    },
-    onsessionclosed: (sid) => {
-      transports.delete(sid)
-    },
+    sessionIdGenerator: undefined,
+    enableJsonResponse: true,
   })
-  transport.onclose = () => {
-    const sid = transport.sessionId
-    if (sid) transports.delete(sid)
-  }
 
   await mcpServer.connect(transport)
-  return transport.handleRequest(request, { parsedBody })
+  try {
+    return await transport.handleRequest(request, { parsedBody })
+  } finally {
+    await transport.close()
+    await mcpServer.close()
+  }
 }
 ```
 
@@ -353,7 +320,7 @@ export async function POST(request: Request) {
 
 **Key guarantees**
 
-- Every tool call inside a session runs against `tenantCli`'s `cwd` / `env` / `fs` — not the base cli's and not another tenant's.
+- Every tool call on a request runs against `tenantCli`'s `cwd` / `env` / `fs`, not the base cli's and not another tenant's.
 - `ctx.console.log` / `ctx.console.error` / `ctx.process.stdout.write` / `ctx.process.stderr.write` are captured into the `CallToolResult.content`. They never reach the host process stdio, so they can't corrupt the JSON-RPC channel or leak between users.
 - `ctx.process.exit(code)` throws `GokeProcessExit` instead of killing the server. The tool call resolves as `{ isError: code !== 0, content: [captured output] }` and the next request keeps running.
 - Actions that `throw` are caught and returned as `{ isError: true, content: [message, stderr] }`.
@@ -486,7 +453,9 @@ Registers MCP tool commands on a goke CLI instance.
 |--------|------|---------|-------------|
 | `cli` | `Goke` | **required** | The goke CLI instance to add commands to |
 | `getMcpUrl` | `() => string \| undefined` | — | Returns the MCP server URL. Return the URL even when the user is not logged in so `--help` still works |
+| `getMcpTransport` | `() => Transport \| null` | — | Custom transport. Use for stdio or anything `getMcpUrl` cannot express |
 | `getHeaders` | `() => Record<string, string> \| undefined` | — | Extra HTTP headers (for example `Authorization`). Used with `getMcpUrl` |
+| `argv` | `string[]` | `process.argv.slice(2)` | Args used to skip live discovery on help and already registered commands |
 | `commandPrefix` | `string` | `''` | Prefix for commands (e.g. `'mcp'` makes `mcp notion-search`) |
 | `clientName` | `string` | `'mcp-cli-client'` | Name sent to the MCP server during connection |
 | `oauth` | `McpOAuthConfig` | — | OAuth config for servers that require authentication |
@@ -552,7 +521,7 @@ Tokens are persisted via the `oauth.save()` callback you provide, so subsequent
 
 ## Caching
 
-Tools and the MCP session ID are cached for **1 hour** to avoid connecting on every invocation. The cache is managed through the `loadCache`/`saveCache` callbacks — you control where it's stored (file, database, env, etc.).
+Tool schemas are cached for **1 hour** so `--help` and command registration do not hit the network on every invocation. The cache is managed through the `loadCache`/`saveCache` callbacks. You control where it is stored (file, database, env, etc.). Each tool call still opens a new MCP connection. There is no `Mcp-Session-Id` reuse.
 
 When the cache expires or a tool call fails, the cache is cleared and tools are re-fetched on the next run.
 

package/dist/__test__/add-mcp-commands-help.test.js

@@ -1,6 +1,10 @@
 // First-run help and stale-cache behavior for addMcpCommands.
+import http from 'node:http';
 import { describe, expect, it } from 'vitest';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { goke } from 'goke';
+import { addCliToolsToMcp } from '../cli-to-mcp.js';
 import { addMcpCommands } from '../index.js';
 const staleCache = (over = {}) => ({
     tools: [
@@ -13,63 +17,79 @@ const staleCache = (over = {}) => ({
     timestamp: Date.now() - 2 * 60 * 60 * 1000,
     ...over,
 });
-async function withArgv(argv, fn) {
-    const previous = process.argv;
-    process.argv = ['node', 'testcli', ...argv];
-    try {
-        return await fn();
-    }
-    finally {
-        process.argv = previous;
-    }
+function captureErrors() {
+    const errors = [];
+    const error = console.error;
+    console.error = (...args) => {
+        errors.push(args.map(String).join(' '));
+    };
+    return {
+        errors,
+        restore() {
+            console.error = error;
+        },
+    };
+}
+function listen401() {
+    const server = http.createServer((_req, res) => {
+        res.writeHead(401, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: 'unauthorized' }));
+    });
+    return new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            if (!addr || typeof addr === 'string')
+                throw new Error('no port');
+            resolve({
+                url: `http://127.0.0.1:${addr.port}/mcp`,
+                close: () => new Promise((done) => server.close(() => done())),
+            });
+        });
+    });
 }
 describe('addMcpCommands first-run help', () => {
     it('lets --help run when there is no token and no cache', async () => {
-        const errors = [];
-        const error = console.error;
-        console.error = (...args) => {
-            errors.push(args.map(String).join(' '));
-        };
+        const io = captureErrors();
         const cli = goke('testcli');
         cli.command('config', 'Save token').action(() => { });
-        await withArgv(['--help'], async () => {
+        try {
             await addMcpCommands({
                 cli,
+                argv: ['--help'],
                 getMcpTransport: () => null,
                 loadCache: () => undefined,
                 saveCache: () => { },
             });
-        });
-        console.error = error;
+        }
+        finally {
+            io.restore();
+        }
         const help = cli.helpText();
-        expect(errors.join('\n')).not.toMatch(/Failed to connect/);
+        expect(io.errors.join('\n')).not.toMatch(/Failed to connect/);
         expect(help).toMatch(/config/);
         expect(help).not.toMatch(/find_bookmarks/);
     });
     it('registers stale cached tools when live fetch is impossible', async () => {
         const cli = goke('testcli');
-        await withArgv(['--help'], async () => {
-            await addMcpCommands({
-                cli,
-                getMcpTransport: () => null,
-                loadCache: () => staleCache(),
-                saveCache: () => { },
-            });
+        await addMcpCommands({
+            cli,
+            argv: ['--help'],
+            getMcpTransport: () => null,
+            loadCache: () => staleCache(),
+            saveCache: () => { },
         });
         expect(cli.helpText()).toMatch(/find_bookmarks/);
     });
     it('does not start OAuth when --help gets a 401', async () => {
+        const server = await listen401();
         const authUrls = [];
-        const errors = [];
-        const error = console.error;
-        console.error = (...args) => {
-            errors.push(args.map(String).join(' '));
-        };
+        const io = captureErrors();
         const cli = goke('testcli');
-        await withArgv(['--help'], async () => {
+        try {
             await addMcpCommands({
                 cli,
-                getMcpUrl: () => 'http://127.0.0.1:1/mcp',
+                argv: ['--help'],
+                getMcpUrl: () => server.url,
                 oauth: {
                     clientName: 'test',
                     load: () => undefined,
@@ -81,10 +101,89 @@ describe('addMcpCommands first-run help', () => {
                 loadCache: () => undefined,
                 saveCache: () => { },
             });
-        });
-        console.error = error;
+        }
+        finally {
+            io.restore();
+            await server.close();
+        }
         expect(authUrls).toEqual([]);
-        expect(errors.join('\n')).not.toMatch(/Authentication required/);
+        expect(io.errors.join('\n')).not.toMatch(/Authentication required/);
         expect(cli.helpText()).toMatch(/Usage/);
     });
+    it('does not connect for an already registered command', async () => {
+        let transportCalls = 0;
+        const cli = goke('testcli');
+        cli.command('config', 'Save token').action(() => { });
+        await addMcpCommands({
+            cli,
+            argv: ['config', '--token', 'x'],
+            getMcpTransport: () => {
+                transportCalls += 1;
+                return null;
+            },
+            loadCache: () => undefined,
+            saveCache: () => { },
+        });
+        expect(transportCalls).toBe(0);
+    });
+    it('does not pass a session id into getMcpTransport', async () => {
+        const sessionIds = [];
+        const cli = goke('testcli');
+        await addMcpCommands({
+            cli,
+            argv: ['find_bookmarks'],
+            getMcpTransport: (sessionId) => {
+                sessionIds.push(sessionId);
+                return null;
+            },
+            loadCache: () => ({
+                tools: [
+                    {
+                        name: 'find_bookmarks',
+                        description: 'Find bookmarks',
+                        inputSchema: { type: 'object', properties: {} },
+                    },
+                ],
+                timestamp: Date.now(),
+                sessionId: 'should-not-be-reused',
+            }),
+            saveCache: () => { },
+        });
+        const command = cli.commands.find((entry) => entry.name === 'find_bookmarks');
+        try {
+            await command?.commandAction?.({});
+        }
+        catch {
+            // transport is null, so the action exits
+        }
+        expect(sessionIds).toEqual([undefined]);
+    });
+    it('caches tools without a session id', async () => {
+        const saved = [];
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        const serverCli = goke('server-cli');
+        serverCli.command('ping', 'Ping').action(() => 'pong');
+        const server = new Server({ name: 'test-server', version: '1.0.0' }, { capabilities: {} });
+        addCliToolsToMcp({ cli: serverCli, server });
+        await server.connect(serverTransport);
+        const cli = goke('testcli');
+        try {
+            await addMcpCommands({
+                cli,
+                argv: ['ping'],
+                getMcpTransport: () => clientTransport,
+                loadCache: () => undefined,
+                saveCache: (cache) => {
+                    if (cache)
+                        saved.push(cache);
+                },
+            });
+        }
+        finally {
+            await server.close();
+        }
+        expect(saved).toHaveLength(1);
+        expect(saved[0]?.tools.map((tool) => tool.name)).toEqual(['ping']);
+        expect(saved[0]).not.toHaveProperty('sessionId');
+    });
 });

package/dist/__test__/http-multi-tenant.test.d.ts

@@ -3,8 +3,8 @@
  *
  * Proves that one goke cli exposed over the MCP streamable-HTTP
  * transport can serve multiple concurrent users with fully isolated
- * state (in-memory fs + cwd + env) — no shared host process stdio,
- * no cross-tenant leaks.
+ * state (in-memory fs + cwd + env). Isolation comes from the
+ * `x-tenant-id` header on each POST, not from `Mcp-Session-Id`.
  *
  * Wiring choices worth calling out:
  *
@@ -18,7 +18,8 @@
  *     into pure request/response JSON. GET SSE opens are answered
  *     with `405`, which the client treats as "server does not offer
  *     SSE" and moves on (see `_startOrAuthSse` in the SDK client).
- *   - Each session gets its own cli **clone** via
+ *   - Each HTTP POST gets a fresh transport with
+ *     `sessionIdGenerator: undefined` and a cli **clone** via
  *     `baseCli.clone({ cwd, env, fs })`. The clone inherits the
  *     command tree but owns its own `{ cwd, env, fs }`, which is
  *     what `runCliTool` forwards into every action through

package/dist/__test__/http-multi-tenant.test.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-multi-tenant.test.d.ts","sourceRoot":"","sources":["../../src/__test__/http-multi-tenant.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}
+{"version":3,"file":"http-multi-tenant.test.d.ts","sourceRoot":"","sources":["../../src/__test__/http-multi-tenant.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}

package/dist/__test__/http-multi-tenant.test.js

@@ -3,8 +3,8 @@
  *
  * Proves that one goke cli exposed over the MCP streamable-HTTP
  * transport can serve multiple concurrent users with fully isolated
- * state (in-memory fs + cwd + env) — no shared host process stdio,
- * no cross-tenant leaks.
+ * state (in-memory fs + cwd + env). Isolation comes from the
+ * `x-tenant-id` header on each POST, not from `Mcp-Session-Id`.
  *
  * Wiring choices worth calling out:
  *
@@ -18,19 +18,18 @@
  *     into pure request/response JSON. GET SSE opens are answered
  *     with `405`, which the client treats as "server does not offer
  *     SSE" and moves on (see `_startOrAuthSse` in the SDK client).
- *   - Each session gets its own cli **clone** via
+ *   - Each HTTP POST gets a fresh transport with
+ *     `sessionIdGenerator: undefined` and a cli **clone** via
  *     `baseCli.clone({ cwd, env, fs })`. The clone inherits the
  *     command tree but owns its own `{ cwd, env, fs }`, which is
  *     what `runCliTool` forwards into every action through
  *     `ctx.process.*` / `ctx.fs`.
  */
-import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { Server as McpLowLevelServer } from "@modelcontextprotocol/sdk/server/index.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
-import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { goke } from "goke";
 import { describe, expect, it } from "vitest";
 import { z } from "zod";
@@ -80,7 +79,7 @@ class InMemoryFs {
  * One cli definition, reused across tenants. Commands read / write
  * through `ctx.fs` and resolve paths against `ctx.process.cwd`, so
  * the *same* code runs per tenant but talks to a tenant-specific
- * filesystem when invoked via the session-scoped clone below.
+ * filesystem when invoked via the per-request clone below.
  */
 function buildBaseCli() {
     const cli = goke("notes-app");
@@ -102,21 +101,20 @@ function buildBaseCli() {
     return cli;
 }
 /**
- * Build a `FetchLike` that routes MCP streamable-HTTP traffic into
- * in-process session-scoped `WebStandardStreamableHTTPServerTransport`
- * instances. One transport + one cli clone per session. Each session
- * is keyed by `mcp-session-id`; initialization requests pick a tenant
- * via the `x-tenant-id` header.
- *
- * Returns both the custom fetch and the transports map so tests can
- * inspect session state if needed.
+ * Build a `FetchLike` that serves MCP streamable-HTTP traffic with a
+ * fresh transport + cli clone on every POST. Tenant identity comes
+ * from `x-tenant-id`. There is no `mcp-session-id` map.
  */
 function createMultiTenantFetch(options) {
     const { baseCli, resolveTenant } = options;
-    const transports = new Map();
+    const sessionHeaders = [];
     const customFetch = async (url, init) => {
         const method = (init?.method ?? "GET").toUpperCase();
         const headers = new Headers(init?.headers);
+        const sessionHeader = headers.get("mcp-session-id");
+        if (sessionHeader) {
+            sessionHeaders.push(sessionHeader);
+        }
         // Pure request/response mode: tell the client there's no SSE
         // available on GET. `_startOrAuthSse` in the SDK client treats
         // 405 as "server does not offer SSE" and moves on gracefully.
@@ -136,28 +134,10 @@ function createMultiTenantFetch(options) {
                 parsedBody = JSON.parse(bodyText);
             }
         }
-        // Rebuild a plain Request with the same method + headers. The
-        // transport reads accept/content-type from here and uses
-        // `parsedBody` for the actual JSON-RPC payload.
         const request = new Request(url.toString(), {
             method,
             headers,
         });
-        const sessionId = headers.get("mcp-session-id");
-        // Existing session: route to its transport.
-        if (sessionId && transports.has(sessionId)) {
-            return transports.get(sessionId).handleRequest(request, { parsedBody });
-        }
-        // New session: must be an initialize POST.
-        if (method !== "POST" || !isInitializeRequest(parsedBody)) {
-            return new Response(JSON.stringify({
-                jsonrpc: "2.0",
-                error: { code: -32000, message: "Bad Request: No valid session ID provided" },
-                id: null,
-            }), { status: 400, headers: { "content-type": "application/json" } });
-        }
-        // Resolve the tenant from the custom header, build a cli clone
-        // with its cwd/env/fs, and spin up a session-scoped MCP server.
         const tenantId = headers.get("x-tenant-id");
         if (!tenantId) {
             return new Response("missing x-tenant-id header", { status: 401 });
@@ -171,26 +151,16 @@ function createMultiTenantFetch(options) {
         const mcpServer = new McpLowLevelServer({ name: "notes-app-mcp", version: "1.0.0" }, { capabilities: {} });
         addCliToolsToMcp({ cli: tenantCli, server: mcpServer });
         const transport = new WebStandardStreamableHTTPServerTransport({
-            sessionIdGenerator: () => randomUUID(),
-            // Pure request/response — no SSE streaming to clean up.
+            sessionIdGenerator: undefined,
             enableJsonResponse: true,
-            onsessioninitialized: (sid) => {
-                transports.set(sid, transport);
-            },
-            onsessionclosed: (sid) => {
-                transports.delete(sid);
-            },
         });
-        transport.onclose = () => {
-            const sid = transport.sessionId;
-            if (sid) {
-                transports.delete(sid);
-            }
-        };
         await mcpServer.connect(transport);
-        return transport.handleRequest(request, { parsedBody });
+        const response = await transport.handleRequest(request, { parsedBody });
+        await transport.close();
+        await mcpServer.close();
+        return response;
     };
-    return { fetch: customFetch, transports };
+    return { fetch: customFetch, sessionHeaders };
 }
 // ─── Tests ────────────────────────────────────────────────────────
 describe("remote MCP over streamable HTTP with multi-tenant in-memory fs", () => {
@@ -207,7 +177,7 @@ describe("remote MCP over streamable HTTP with multi-tenant in-memory fs", () =>
             env: { ROLE: "reader" },
             fs: new InMemoryFs(),
         });
-        const { fetch: tenantFetch } = createMultiTenantFetch({
+        const { fetch: tenantFetch, sessionHeaders } = createMultiTenantFetch({
             baseCli,
             resolveTenant: (id) => {
                 const tenant = tenants.get(id);
@@ -232,14 +202,14 @@ describe("remote MCP over streamable HTTP with multi-tenant in-memory fs", () =>
             await client.connect(transport);
             return client;
         }
-        return { tenants, connectTenant };
+        return { tenants, connectTenant, sessionHeaders };
     }
     function firstTextBlock(result) {
         const content = result.content ?? [];
         return content.find((block) => block.type === "text")?.text ?? "";
     }
-    it("routes each session to its own cli clone with tenant-specific cwd/env/fs", async () => {
-        const { tenants, connectTenant } = setupScenario();
+    it("routes each request to its own cli clone with tenant-specific cwd/env/fs", async () => {
+        const { tenants, connectTenant, sessionHeaders } = setupScenario();
         const aliceClient = await connectTenant("tenant-a");
         const bobClient = await connectTenant("tenant-b");
         try {
@@ -250,8 +220,8 @@ describe("remote MCP over streamable HTTP with multi-tenant in-memory fs", () =>
             expect(aliceTools).toEqual(["load", "save"]);
             expect(bobTools).toEqual(["load", "save"]);
             // Both tenants write a file called `notes.txt` with different
-            // content. Since each session uses its own cli clone (with
-            // its own cwd + fs), the writes land in separate Maps.
+            // content. Since each request clones the cli with that tenant's
+            // cwd + fs, the writes land in separate Maps.
             const aliceSave = await aliceClient.callTool({
                 name: "save",
                 arguments: { filename: "notes.txt", content: "alice-secret" },
@@ -285,6 +255,7 @@ describe("remote MCP over streamable HTTP with multi-tenant in-memory fs", () =>
             expect([...tenantBFs.files.keys()]).toEqual(["/workspace-b/notes.txt"]);
             expect(tenantAFs.files.get("/workspace-a/notes.txt")).toBe("alice-secret");
             expect(tenantBFs.files.get("/workspace-b/notes.txt")).toBe("bob-secret");
+            expect(sessionHeaders).toEqual([]);
         }
         finally {
             await aliceClient.close();

package/dist/auth.d.ts

@@ -1,8 +1,10 @@
 import type { OAuthFlowResult, StartOAuthFlowOptions } from "./types.js";
 /**
  * Start the OAuth flow for an MCP server.
- * This is an internal function - consumers should not call this directly.
- * It is automatically triggered by addMcpCommands when a 401 error occurs.
+ *
+ * Used internally by addMcpCommands on 401 errors, but also available
+ * for CLIs that need explicit control over the auth flow (e.g. a login
+ * command that runs the flow in a background daemon).
  *
  * This function:
  * 1. Starts a local callback server on a random port

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAiB,eAAe,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA0BxF;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,CA4E7F;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAazD"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAiB,eAAe,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA0BxF;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,CA4E7F;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAazD"}

package/dist/auth.js

@@ -24,8 +24,10 @@ async function openBrowser(url) {
 }
 /**
  * Start the OAuth flow for an MCP server.
- * This is an internal function - consumers should not call this directly.
- * It is automatically triggered by addMcpCommands when a 401 error occurs.
+ *
+ * Used internally by addMcpCommands on 401 errors, but also available
+ * for CLIs that need explicit control over the auth flow (e.g. a login
+ * command that runs the flow in a background daemon).
  *
  * This function:
  * 1. Starts a local callback server on a random port