@goke/mcp 0.0.13 → 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
 
@@ -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,7 @@ 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` | `(sessionId?) => Transport \| null` | — | Custom transport. Use for stdio or anything `getMcpUrl` cannot express |
+| `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`) |
@@ -554,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,7 +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: [
@@ -12,7 +15,6 @@ const staleCache = (over = {}) => ({
         },
     ],
     timestamp: Date.now() - 2 * 60 * 60 * 1000,
-    sessionId: 'stale-session',
     ...over,
 });
 function captureErrors() {
@@ -124,4 +126,64 @@ describe('addMcpCommands first-run help', () => {
         });
         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

package/dist/index.d.ts

@@ -9,7 +9,6 @@
  *
  * - **Auto-discovery**: Fetches all tools from the MCP server and creates CLI commands
  * - **Caching**: Tools are cached for 1 hour to avoid reconnecting on every invocation
- * - **Session reuse**: MCP session IDs are cached to skip initialization handshake
  * - **Type-aware parsing**: Handles string, number, boolean, object, and array arguments
  * - **JSON schema support**: Generates CLI options from tool input schemas
  * - **OAuth support**: Automatic OAuth authentication on 401 errors (lazy auth)
@@ -41,11 +40,12 @@
  */
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { Goke } from "goke";
+export { startOAuthFlow } from "./auth.js";
 import type { McpOAuthConfig } from "./types.js";
 export { addCliToolsToMcp, createMcpAction } from "./cli-to-mcp.js";
 export type { AddCliToolsToMcpOptions, CreateMcpActionOptions } from "./cli-to-mcp.js";
 export type { Transport };
-export type { McpOAuthConfig, McpOAuthState } from "./types.js";
+export type { McpOAuthConfig, McpOAuthState, StartOAuthFlowOptions, OAuthFlowResult } from "./types.js";
 export interface CachedMcpTools {
     tools: Array<{
         name: string;
@@ -53,7 +53,6 @@ export interface CachedMcpTools {
         inputSchema?: unknown;
     }>;
     timestamp: number;
-    sessionId?: string;
 }
 export interface AddMcpCommandsOptions {
     cli: Goke;
@@ -76,9 +75,8 @@ export interface AddMcpCommandsOptions {
     /**
      * Returns a transport to connect to the MCP server, or null if not configured.
      * Use this for stdio servers or any setup `getMcpUrl` cannot express.
-     * @param sessionId - Optional session ID from a still-valid cache
      */
-    getMcpTransport?: (sessionId?: string) => Transport | null | Promise<Transport | null>;
+    getMcpTransport?: () => Transport | null | Promise<Transport | null>;
     /**
      * Argv used to decide whether to skip live discovery.
      * Defaults to `process.argv.slice(2)`.
@@ -118,7 +116,6 @@ export interface AddMcpCommandsOptions {
  * Adds MCP tool commands to a goke CLI instance.
  *
  * Tools are cached for 1 hour to avoid connecting on every CLI invocation.
- * Session ID is also cached to skip MCP initialization handshake.
  *
  * OAuth is lazy - authentication only happens when a 401 error occurs.
  * After successful auth, the operation is automatically retried.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAC/E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAKjC,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAGvF,YAAY,EAAE,SAAS,EAAE,CAAC;AAC1B,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,CAAC,CAAC;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,IAAI,CAAC;IACV;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAErC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEvF;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAEtD;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,cAAc,GAAG,SAAS,CAAC;IAE5C;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,KAAK,IAAI,CAAC;CACxD;AA2JD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4NlF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAC/E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAKjC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAGvF,YAAY,EAAE,SAAS,EAAE,CAAC;AAC1B,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAExG,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,CAAC,CAAC;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,IAAI,CAAC;IACV;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAErC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAErE;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAEtD;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,cAAc,GAAG,SAAS,CAAC;IAE5C;;OAEG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,KAAK,IAAI,CAAC;CACxD;AAwJD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkNlF"}

package/dist/index.js

@@ -9,7 +9,6 @@
  *
  * - **Auto-discovery**: Fetches all tools from the MCP server and creates CLI commands
  * - **Caching**: Tools are cached for 1 hour to avoid reconnecting on every invocation
- * - **Session reuse**: MCP session IDs are cached to skip initialization handshake
  * - **Type-aware parsing**: Handles string, number, boolean, object, and array arguments
  * - **JSON schema support**: Generates CLI options from tool input schemas
  * - **OAuth support**: Automatic OAuth authentication on 401 errors (lazy auth)
@@ -45,6 +44,7 @@ import { wrapJsonSchema } from "goke";
 import yaml from "js-yaml";
 import { FileOAuthProvider } from "./oauth-provider.js";
 import { startOAuthFlow, isAuthRequiredError } from "./auth.js";
+export { startOAuthFlow } from "./auth.js";
 export { addCliToolsToMcp, createMcpAction } from "./cli-to-mcp.js";
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 /**
@@ -140,7 +140,7 @@ function matchesRegisteredCommand({ argv, cli }) {
         return nameParts.every((part, i) => parts[i] === part);
     });
 }
-function createTransportWithAuth({ url, sessionId, oauthState, oauth, headers, }) {
+function createTransportWithAuth({ url, oauthState, oauth, headers, }) {
     let authProvider;
     if (oauth && oauthState?.tokens) {
         authProvider = new FileOAuthProvider({
@@ -157,7 +157,6 @@ function createTransportWithAuth({ url, sessionId, oauthState, oauth, headers, }
     }
     const hasHeaders = headers && Object.keys(headers).length > 0;
     return new StreamableHTTPClientTransport(url, {
-        sessionId,
         authProvider,
         requestInit: hasHeaders ? { headers } : undefined,
     });
@@ -166,16 +165,13 @@ function createTransportWithAuth({ url, sessionId, oauthState, oauth, headers, }
  * Adds MCP tool commands to a goke CLI instance.
  *
  * Tools are cached for 1 hour to avoid connecting on every CLI invocation.
- * Session ID is also cached to skip MCP initialization handshake.
  *
  * OAuth is lazy - authentication only happens when a 401 error occurs.
  * After successful auth, the operation is automatically retried.
  */
 export async function addMcpCommands(options) {
     const { cli, commandPrefix = "", clientName = "mcp-cli-client", getMcpUrl, getMcpTransport, getHeaders, oauth, loadCache, saveCache, argv = process.argv.slice(2), } = options;
-    // Helper to get transport - supports both old and new API
-    const getTransport = async (sessionId) => {
-        // New API: getMcpUrl + oauth
+    const getTransport = async () => {
         if (getMcpUrl) {
             const mcpUrl = getMcpUrl();
             if (!mcpUrl) {
@@ -185,15 +181,13 @@ export async function addMcpCommands(options) {
             const oauthState = oauth?.load();
             return createTransportWithAuth({
                 url,
-                sessionId,
                 oauthState,
                 oauth,
                 headers: getHeaders?.(),
             });
         }
-        // Custom / stdio transport
         if (getMcpTransport) {
-            return getMcpTransport(sessionId);
+            return getMcpTransport();
         }
         return null;
     };
@@ -226,10 +220,8 @@ export async function addMcpCommands(options) {
     const isCacheValid = cachedTools && (Date.now() - cachedTools.timestamp) < CACHE_TTL_MS;
     const skipLiveDiscovery = isHelpOrMetaArgv(argv) || matchesRegisteredCommand({ argv, cli });
     let tools;
-    let cachedSessionId;
     if (isCacheValid && cachedTools) {
         tools = cachedTools.tools;
-        cachedSessionId = cachedTools.sessionId;
     }
     else if (skipLiveDiscovery) {
         if (cachedTools) {
@@ -244,7 +236,6 @@ export async function addMcpCommands(options) {
                 await client.connect(transport);
                 const result = await client.listTools();
                 tools = result.tools;
-                const sessionId = transport.sessionId;
                 saveCache({
                     tools: tools.map((t) => ({
                         name: t.name,
@@ -252,9 +243,7 @@ export async function addMcpCommands(options) {
                         inputSchema: t.inputSchema,
                     })),
                     timestamp: Date.now(),
-                    sessionId,
                 });
-                cachedSessionId = sessionId;
             }
             catch (err) {
                 const shouldAuth = isAuthRequiredError(err) && oauth && getMcpUrl && !skipLiveDiscovery;
@@ -321,7 +310,7 @@ export async function addMcpCommands(options) {
             // Goke already coerced all values via schemas — just extract the relevant keys
             const parsedArgs = extractToolArguments(cliOptions, inputSchema);
             const executeWithRetry = async (isRetry = false) => {
-                const transport = await getTransport(isRetry ? undefined : cachedSessionId);
+                const transport = await getTransport();
                 if (!transport) {
                     console.error("MCP transport not available. Run login command first.");
                     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goke/mcp",
-  "version": "0.0.13",
+  "version": "0.1.0",
   "type": "module",
   "description": "Dynamically generate CLI commands from MCP server tools",
   "repository": {
@@ -40,7 +40,7 @@
   "author": "Tommaso De Rossi, morse <beats.by.morse@gmail.com>",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "js-yaml": "^4.1.1"
   },
   "peerDependencies": {
@@ -51,7 +51,7 @@
     "@types/node": "^22.19.7",
     "vitest": "^3.1.0",
     "zod": "^4.3.6",
-    "goke": "^6.12.1"
+    "goke": "^6.15.1"
   },
   "scripts": {
     "clean": "rm -rf dist",

package/src/__test__/add-mcp-commands-help.test.ts

@@ -1,7 +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, type CachedMcpTools } from '../index.js'
 
 const staleCache = (over: Partial<CachedMcpTools> = {}): CachedMcpTools => ({
@@ -13,7 +16,6 @@ const staleCache = (over: Partial<CachedMcpTools> = {}): CachedMcpTools => ({
     },
   ],
   timestamp: Date.now() - 2 * 60 * 60 * 1000,
-  sessionId: 'stale-session',
   ...over,
 })
 
@@ -136,4 +138,69 @@ describe('addMcpCommands first-run help', () => {
 
     expect(transportCalls).toBe(0)
   })
+
+  it('does not pass a session id into getMcpTransport', async () => {
+    const sessionIds: Array<string | undefined> = []
+    const cli = goke('testcli')
+
+    await addMcpCommands({
+      cli,
+      argv: ['find_bookmarks'],
+      getMcpTransport: (sessionId?: string) => {
+        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: CachedMcpTools[] = []
+    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/src/__test__/http-multi-tenant.test.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,15 +18,14 @@
  *     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 { Buffer } from "node:buffer";
 import path from "node:path";
 
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -34,7 +33,6 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { Server as McpLowLevelServer } from "@modelcontextprotocol/sdk/server/index.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import type { FetchLike } from "@modelcontextprotocol/sdk/shared/transport.js";
-import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { goke, type Goke, type GokeFs } from "goke";
 import { describe, expect, it } from "vitest";
 import { z } from "zod";
@@ -94,7 +92,7 @@ class InMemoryFs implements GokeFs {
  * 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(): Goke {
   const cli = goke("notes-app");
@@ -122,9 +120,8 @@ function buildBaseCli(): Goke {
 // ─── In-process multi-tenant fetch ────────────────────────────────
 
 /**
- * Per-tenant state resolved from the `x-tenant-id` header on a
- * session-initialization request. Each tenant gets its own cwd,
- * env, and in-memory fs.
+ * Per-tenant state resolved from the `x-tenant-id` header on each
+ * request. Each tenant gets its own cwd, env, and in-memory fs.
  */
 interface TenantState {
   cwd: string;
@@ -133,28 +130,27 @@ interface TenantState {
 }
 
 /**
- * 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: {
   baseCli: Goke;
   resolveTenant: (tenantId: string) => TenantState;
 }): {
   fetch: FetchLike;
-  transports: Map<string, WebStandardStreamableHTTPServerTransport>;
+  sessionHeaders: string[];
 } {
   const { baseCli, resolveTenant } = options;
-  const transports = new Map<string, WebStandardStreamableHTTPServerTransport>();
+  const sessionHeaders: string[] = [];
 
   const customFetch: FetchLike = 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
@@ -177,35 +173,11 @@ function createMultiTenantFetch(options: {
       }
     }
 
-    // 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 });
@@ -225,29 +197,18 @@ function createMultiTenantFetch(options: {
     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 ────────────────────────────────────────────────────────
@@ -267,7 +228,7 @@ describe("remote MCP over streamable HTTP with multi-tenant in-memory fs", () =>
       fs: new InMemoryFs(),
     });
 
-    const { fetch: tenantFetch } = createMultiTenantFetch({
+    const { fetch: tenantFetch, sessionHeaders } = createMultiTenantFetch({
       baseCli,
       resolveTenant: (id) => {
         const tenant = tenants.get(id);
@@ -297,7 +258,7 @@ describe("remote MCP over streamable HTTP with multi-tenant in-memory fs", () =>
       return client;
     }
 
-    return { tenants, connectTenant };
+    return { tenants, connectTenant, sessionHeaders };
   }
 
   function firstTextBlock(result: Awaited<ReturnType<Client["callTool"]>>): string {
@@ -305,8 +266,8 @@ describe("remote MCP over streamable HTTP with multi-tenant in-memory fs", () =>
     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");
@@ -320,8 +281,8 @@ describe("remote MCP over streamable HTTP with multi-tenant in-memory fs", () =>
       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" },
@@ -359,6 +320,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();
       await bobClient.close();

package/src/auth.ts

@@ -29,8 +29,10 @@ async function openBrowser(url: string): Promise<void> {
 
 /**
  * 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/src/index.ts

@@ -9,7 +9,6 @@
  *
  * - **Auto-discovery**: Fetches all tools from the MCP server and creates CLI commands
  * - **Caching**: Tools are cached for 1 hour to avoid reconnecting on every invocation
- * - **Session reuse**: MCP session IDs are cached to skip initialization handshake
  * - **Type-aware parsing**: Handles string, number, boolean, object, and array arguments
  * - **JSON schema support**: Generates CLI options from tool input schemas
  * - **OAuth support**: Automatic OAuth authentication on 401 errors (lazy auth)
@@ -48,13 +47,14 @@ import { wrapJsonSchema } from "goke";
 import yaml from "js-yaml";
 import { FileOAuthProvider } from "./oauth-provider.js";
 import { startOAuthFlow, isAuthRequiredError } from "./auth.js";
+export { startOAuthFlow } from "./auth.js";
 import type { McpOAuthConfig, McpOAuthState } from "./types.js";
 export { addCliToolsToMcp, createMcpAction } from "./cli-to-mcp.js";
 export type { AddCliToolsToMcpOptions, CreateMcpActionOptions } from "./cli-to-mcp.js";
 
-// Public exports - only types that consumers need
+// Public exports
 export type { Transport };
-export type { McpOAuthConfig, McpOAuthState } from "./types.js";
+export type { McpOAuthConfig, McpOAuthState, StartOAuthFlowOptions, OAuthFlowResult } from "./types.js";
 
 export interface CachedMcpTools {
   tools: Array<{
@@ -63,7 +63,6 @@ export interface CachedMcpTools {
     inputSchema?: unknown;
   }>;
   timestamp: number;
-  sessionId?: string;
 }
 
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
@@ -91,9 +90,8 @@ export interface AddMcpCommandsOptions {
   /**
    * Returns a transport to connect to the MCP server, or null if not configured.
    * Use this for stdio servers or any setup `getMcpUrl` cannot express.
-   * @param sessionId - Optional session ID from a still-valid cache
    */
-  getMcpTransport?: (sessionId?: string) => Transport | null | Promise<Transport | null>;
+  getMcpTransport?: () => Transport | null | Promise<Transport | null>;
 
   /**
    * Argv used to decide whether to skip live discovery.
@@ -251,13 +249,11 @@ function matchesRegisteredCommand({ argv, cli }: { argv: string[]; cli: Goke })
 
 function createTransportWithAuth({
   url,
-  sessionId,
   oauthState,
   oauth,
   headers,
 }: {
   url: URL
-  sessionId?: string
   oauthState?: McpOAuthState
   oauth?: McpOAuthConfig
   headers?: Record<string, string>
@@ -280,7 +276,6 @@ function createTransportWithAuth({
 
   const hasHeaders = headers && Object.keys(headers).length > 0;
   return new StreamableHTTPClientTransport(url, {
-    sessionId,
     authProvider,
     requestInit: hasHeaders ? { headers } : undefined,
   });
@@ -292,7 +287,6 @@ function createTransportWithAuth({
  * Adds MCP tool commands to a goke CLI instance.
  *
  * Tools are cached for 1 hour to avoid connecting on every CLI invocation.
- * Session ID is also cached to skip MCP initialization handshake.
  *
  * OAuth is lazy - authentication only happens when a 401 error occurs.
  * After successful auth, the operation is automatically retried.
@@ -311,9 +305,7 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
     argv = process.argv.slice(2),
   } = options;
 
-  // Helper to get transport - supports both old and new API
-  const getTransport = async (sessionId?: string): Promise<Transport | null> => {
-    // New API: getMcpUrl + oauth
+  const getTransport = async (): Promise<Transport | null> => {
     if (getMcpUrl) {
       const mcpUrl = getMcpUrl();
       if (!mcpUrl) {
@@ -325,16 +317,14 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
 
       return createTransportWithAuth({
         url,
-        sessionId,
         oauthState,
         oauth,
         headers: getHeaders?.(),
       });
     }
 
-    // Custom / stdio transport
     if (getMcpTransport) {
-      return getMcpTransport(sessionId);
+      return getMcpTransport();
     }
 
     return null;
@@ -376,11 +366,9 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
     isHelpOrMetaArgv(argv) || matchesRegisteredCommand({ argv, cli });
 
   let tools: CachedMcpTools["tools"] | undefined;
-  let cachedSessionId: string | undefined;
 
   if (isCacheValid && cachedTools) {
     tools = cachedTools.tools;
-    cachedSessionId = cachedTools.sessionId;
   } else if (skipLiveDiscovery) {
     if (cachedTools) {
       tools = cachedTools.tools;
@@ -394,8 +382,6 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
         const result = await client.listTools();
         tools = result.tools;
 
-        const sessionId = (transport as { sessionId?: string }).sessionId;
-
         saveCache({
           tools: tools.map((t) => ({
             name: t.name,
@@ -403,9 +389,7 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
             inputSchema: t.inputSchema,
           })),
           timestamp: Date.now(),
-          sessionId,
         });
-        cachedSessionId = sessionId;
       } catch (err) {
         const shouldAuth = isAuthRequiredError(err) && oauth && getMcpUrl && !skipLiveDiscovery;
         if (shouldAuth) {
@@ -480,7 +464,7 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
       const parsedArgs = extractToolArguments(cliOptions, inputSchema);
 
       const executeWithRetry = async (isRetry = false): Promise<void> => {
-        const transport = await getTransport(isRetry ? undefined : cachedSessionId);
+        const transport = await getTransport();
         if (!transport) {
           console.error("MCP transport not available. Run login command first.");
           process.exit(1);