@goke/mcp 0.0.11 → 0.0.12

package/README.md

@@ -25,9 +25,9 @@ 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)
+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`)
 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
+5. **OAuth** — if the server returns 401, automatically opens the browser for OAuth, then retries. `--help`, `--version`, `completions`, and no-args never start OAuth
 
 ## Quick start
 
@@ -55,6 +55,24 @@ 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.
+
+For a Bearer token, pass `getHeaders` instead of a custom transport:
+
+```ts
+await addMcpCommands({
+  cli,
+  getMcpUrl: () => 'https://api.example.com/mcp',
+  getHeaders: () => {
+    const token = process.env.EXAMPLE_TOKEN || loadConfig().token
+    if (!token) return
+    return { Authorization: `Bearer ${token}` }
+  },
+  loadCache: () => loadConfig().cache,
+  saveCache: (cache) => saveConfig({ cache }),
+})
+```
+
 That's it. Every tool the MCP server exposes becomes a CLI command:
 
 ```bash
@@ -467,7 +485,8 @@ Registers MCP tool commands on a goke CLI instance.
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `cli` | `Goke` | **required** | The goke CLI instance to add commands to |
-| `getMcpUrl` | `() => string \| undefined` | — | Returns the MCP server URL |
+| `getMcpUrl` | `() => string \| undefined` | — | Returns the MCP server URL. Return the URL even when the user is not logged in so `--help` still works |
+| `getHeaders` | `() => Record<string, string> \| undefined` | — | Extra HTTP headers (for example `Authorization`). Used with `getMcpUrl` |
 | `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 |
@@ -537,6 +556,8 @@ Tools and the MCP session ID are cached for **1 hour** to avoid connecting on ev
 
 When the cache expires or a tool call fails, the cache is cleared and tools are re-fetched on the next run.
 
+If a live `tools/list` cannot run (no transport, 401 during `--help`), `addMcpCommands` still registers tools from an expired cache so help stays useful.
+
 ## License
 
 MIT

package/dist/__test__/add-mcp-commands-help.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=add-mcp-commands-help.test.d.ts.map

package/dist/__test__/add-mcp-commands-help.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-mcp-commands-help.test.d.ts","sourceRoot":"","sources":["../../src/__test__/add-mcp-commands-help.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,90 @@
+// First-run help and stale-cache behavior for addMcpCommands.
+import { describe, expect, it } from 'vitest';
+import { goke } from 'goke';
+import { addMcpCommands } from '../index.js';
+const staleCache = (over = {}) => ({
+    tools: [
+        {
+            name: 'find_bookmarks',
+            description: 'Find bookmarks',
+            inputSchema: { type: 'object', properties: {} },
+        },
+    ],
+    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;
+    }
+}
+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 cli = goke('testcli');
+        cli.command('config', 'Save token').action(() => { });
+        await withArgv(['--help'], async () => {
+            await addMcpCommands({
+                cli,
+                getMcpTransport: () => null,
+                loadCache: () => undefined,
+                saveCache: () => { },
+            });
+        });
+        console.error = error;
+        const help = cli.helpText();
+        expect(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: () => { },
+            });
+        });
+        expect(cli.helpText()).toMatch(/find_bookmarks/);
+    });
+    it('does not start OAuth when --help gets a 401', async () => {
+        const authUrls = [];
+        const errors = [];
+        const error = console.error;
+        console.error = (...args) => {
+            errors.push(args.map(String).join(' '));
+        };
+        const cli = goke('testcli');
+        await withArgv(['--help'], async () => {
+            await addMcpCommands({
+                cli,
+                getMcpUrl: () => 'http://127.0.0.1:1/mcp',
+                oauth: {
+                    clientName: 'test',
+                    load: () => undefined,
+                    save: () => { },
+                    onAuthUrl: (url) => {
+                        authUrls.push(url);
+                    },
+                },
+                loadCache: () => undefined,
+                saveCache: () => { },
+            });
+        });
+        console.error = error;
+        expect(authUrls).toEqual([]);
+        expect(errors.join('\n')).not.toMatch(/Authentication required/);
+        expect(cli.helpText()).toMatch(/Usage/);
+    });
+});

package/dist/auth.d.ts

@@ -1,10 +1,8 @@
 import type { OAuthFlowResult, StartOAuthFlowOptions } from "./types.js";
 /**
  * Start the OAuth flow for an MCP server.
- *
- * 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 is an internal function - consumers should not call this directly.
+ * It is automatically triggered by addMcpCommands when a 401 error occurs.
  *
  * 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;;;;;;;;;;;;;;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"}
+{"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"}

package/dist/auth.js

@@ -24,10 +24,8 @@ async function openBrowser(url) {
 }
 /**
  * Start the OAuth flow for an MCP server.
- *
- * 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 is an internal function - consumers should not call this directly.
+ * It is automatically triggered by addMcpCommands when a 401 error occurs.
  *
  * This function:
  * 1. Starts a local callback server on a random port

package/dist/index.d.ts

@@ -41,12 +41,11 @@
  */
 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, StartOAuthFlowOptions, OAuthFlowResult } from "./types.js";
+export type { McpOAuthConfig, McpOAuthState } from "./types.js";
 export interface CachedMcpTools {
     tools: Array<{
         name: string;
@@ -82,6 +81,11 @@ export interface AddMcpCommandsOptions {
      * @deprecated Use getMcpUrl + oauth instead for simpler setup
      */
     getMcpTransport?: (sessionId?: string) => Transport | null | Promise<Transport | null>;
+    /**
+     * Extra headers for MCP HTTP requests (for example `Authorization`).
+     * Used with `getMcpUrl`. Ignored when `getMcpTransport` is set.
+     */
+    getHeaders?: () => Record<string, string> | undefined;
     /**
      * OAuth configuration. When provided, enables automatic OAuth authentication.
      *

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,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;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;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEvF;;;;;;;;;;;;;;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;AAmID;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyMlF"}
+{"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;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEvF;;;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;AA4ID;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiNlF"}

package/dist/index.js

@@ -45,7 +45,6 @@ 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
 /**
@@ -125,7 +124,14 @@ function outputResult(result) {
 /**
  * Create a transport with optional OAuth authentication
  */
-function createTransportWithAuth(url, sessionId, oauthState, oauth) {
+function isHelpOrMetaArgv(argv) {
+    if (argv.length === 0)
+        return true;
+    if (argv[0] === "completions" || argv.includes("--get-goke-completions"))
+        return true;
+    return argv.some((arg) => arg === "--help" || arg === "-h" || arg === "--version" || arg === "-v");
+}
+function createTransportWithAuth(url, sessionId, oauthState, oauth, headers) {
     let authProvider;
     if (oauth && oauthState?.tokens) {
         authProvider = new FileOAuthProvider({
@@ -140,9 +146,11 @@ function createTransportWithAuth(url, sessionId, oauthState, oauth) {
             },
         });
     }
+    const hasHeaders = headers && Object.keys(headers).length > 0;
     return new StreamableHTTPClientTransport(url, {
         sessionId,
         authProvider,
+        requestInit: hasHeaders ? { headers } : undefined,
     });
 }
 /**
@@ -155,7 +163,7 @@ function createTransportWithAuth(url, sessionId, oauthState, oauth) {
  * After successful auth, the operation is automatically retried.
  */
 export async function addMcpCommands(options) {
-    const { cli, commandPrefix = "", clientName = "mcp-cli-client", getMcpUrl, getMcpTransport, oauth, loadCache, saveCache, } = options;
+    const { cli, commandPrefix = "", clientName = "mcp-cli-client", getMcpUrl, getMcpTransport, getHeaders, oauth, loadCache, saveCache, } = options;
     // Helper to get transport - supports both old and new API
     const getTransport = async (sessionId) => {
         // New API: getMcpUrl + oauth
@@ -166,7 +174,7 @@ export async function addMcpCommands(options) {
             }
             const url = new URL(mcpUrl);
             const oauthState = oauth?.load();
-            return createTransportWithAuth(url, sessionId, oauthState, oauth);
+            return createTransportWithAuth(url, sessionId, oauthState, oauth, getHeaders?.());
         }
         // Legacy API: getMcpTransport
         if (getMcpTransport) {
@@ -201,54 +209,60 @@ export async function addMcpCommands(options) {
     // Try to use cached tools first (fast path - no network)
     const cachedTools = loadCache();
     const isCacheValid = cachedTools && (Date.now() - cachedTools.timestamp) < CACHE_TTL_MS;
+    const helpOrMeta = isHelpOrMetaArgv(process.argv.slice(2));
     let tools;
     let cachedSessionId;
-    if (isCacheValid) {
+    if (isCacheValid && cachedTools) {
         tools = cachedTools.tools;
         cachedSessionId = cachedTools.sessionId;
     }
     else {
-        // Cache invalid/missing - connect to fetch tools
         const transport = await getTransport();
-        if (!transport) {
-            return;
-        }
-        const client = new Client({ name: clientName, version: "1.0.0" }, { capabilities: {} });
-        try {
-            await client.connect(transport);
-            const result = await client.listTools();
-            tools = result.tools;
-            const sessionId = transport.sessionId;
-            saveCache({
-                tools: tools.map((t) => ({
-                    name: t.name,
-                    description: t.description,
-                    inputSchema: t.inputSchema,
-                })),
-                timestamp: Date.now(),
-                sessionId,
-            });
-            cachedSessionId = sessionId;
-        }
-        catch (err) {
-            // Check if auth is required during tool discovery
-            if (isAuthRequiredError(err) && oauth && getMcpUrl) {
-                const mcpUrl = getMcpUrl();
-                if (mcpUrl) {
-                    const authSuccess = await handleAuthRequired((mcpUrl).toString());
-                    if (authSuccess) {
-                        // Retry after auth
-                        return addMcpCommands(options);
+        if (transport) {
+            const client = new Client({ name: clientName, version: "1.0.0" }, { capabilities: {} });
+            try {
+                await client.connect(transport);
+                const result = await client.listTools();
+                tools = result.tools;
+                const sessionId = transport.sessionId;
+                saveCache({
+                    tools: tools.map((t) => ({
+                        name: t.name,
+                        description: t.description,
+                        inputSchema: t.inputSchema,
+                    })),
+                    timestamp: Date.now(),
+                    sessionId,
+                });
+                cachedSessionId = sessionId;
+            }
+            catch (err) {
+                const shouldAuth = isAuthRequiredError(err) && oauth && getMcpUrl && !helpOrMeta;
+                if (shouldAuth) {
+                    const mcpUrl = getMcpUrl();
+                    if (mcpUrl) {
+                        const authSuccess = await handleAuthRequired(mcpUrl);
+                        if (authSuccess) {
+                            return addMcpCommands(options);
+                        }
                     }
                 }
+                if (!helpOrMeta) {
+                    console.error(`Failed to connect to MCP server: ${err instanceof Error ? err.message : err}`);
+                }
+            }
+            finally {
+                await client.close();
             }
-            console.error(`Failed to connect to MCP server: ${err instanceof Error ? err.message : err}`);
-            return;
         }
-        finally {
-            await client.close();
+        if (!tools && cachedTools) {
+            tools = cachedTools.tools;
+            cachedSessionId = cachedTools.sessionId;
         }
     }
+    if (!tools) {
+        return;
+    }
     // Register CLI commands for each tool
     for (const tool of tools) {
         const inputSchema = tool.inputSchema;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goke/mcp",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "type": "module",
   "description": "Dynamically generate CLI commands from MCP server tools",
   "repository": {
@@ -51,7 +51,7 @@
     "@types/node": "^22.19.7",
     "vitest": "^3.1.0",
     "zod": "^4.3.6",
-    "goke": "^6.13.0"
+    "goke": "^6.12.1"
   },
   "scripts": {
     "clean": "rm -rf dist",

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

@@ -0,0 +1,102 @@
+// First-run help and stale-cache behavior for addMcpCommands.
+import { describe, expect, it } from 'vitest'
+import { goke } from 'goke'
+import { addMcpCommands, type CachedMcpTools } from '../index.js'
+
+const staleCache = (over: Partial<CachedMcpTools> = {}): CachedMcpTools => ({
+  tools: [
+    {
+      name: 'find_bookmarks',
+      description: 'Find bookmarks',
+      inputSchema: { type: 'object', properties: {} },
+    },
+  ],
+  timestamp: Date.now() - 2 * 60 * 60 * 1000,
+  ...over,
+})
+
+async function withArgv<T>(argv: string[], fn: () => Promise<T>) {
+  const previous = process.argv
+  process.argv = ['node', 'testcli', ...argv]
+  try {
+    return await fn()
+  } finally {
+    process.argv = previous
+  }
+}
+
+describe('addMcpCommands first-run help', () => {
+  it('lets --help run when there is no token and no cache', async () => {
+    const errors: string[] = []
+    const error = console.error
+    console.error = (...args: unknown[]) => {
+      errors.push(args.map(String).join(' '))
+    }
+
+    const cli = goke('testcli')
+    cli.command('config', 'Save token').action(() => {})
+
+    await withArgv(['--help'], async () => {
+      await addMcpCommands({
+        cli,
+        getMcpTransport: () => null,
+        loadCache: () => undefined,
+        saveCache: () => {},
+      })
+    })
+    console.error = error
+
+    const help = cli.helpText()
+    expect(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: () => {},
+      })
+    })
+
+    expect(cli.helpText()).toMatch(/find_bookmarks/)
+  })
+
+  it('does not start OAuth when --help gets a 401', async () => {
+    const authUrls: string[] = []
+    const errors: string[] = []
+    const error = console.error
+    console.error = (...args: unknown[]) => {
+      errors.push(args.map(String).join(' '))
+    }
+
+    const cli = goke('testcli')
+
+    await withArgv(['--help'], async () => {
+      await addMcpCommands({
+        cli,
+        getMcpUrl: () => 'http://127.0.0.1:1/mcp',
+        oauth: {
+          clientName: 'test',
+          load: () => undefined,
+          save: () => {},
+          onAuthUrl: (url) => {
+            authUrls.push(url)
+          },
+        },
+        loadCache: () => undefined,
+        saveCache: () => {},
+      })
+    })
+    console.error = error
+
+    expect(authUrls).toEqual([])
+    expect(errors.join('\n')).not.toMatch(/Authentication required/)
+    expect(cli.helpText()).toMatch(/Usage/)
+  })
+})

package/src/auth.ts

@@ -29,10 +29,8 @@ async function openBrowser(url: string): Promise<void> {
 
 /**
  * Start the OAuth flow for an MCP server.
- *
- * 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 is an internal function - consumers should not call this directly.
+ * It is automatically triggered by addMcpCommands when a 401 error occurs.
  *
  * This function:
  * 1. Starts a local callback server on a random port

package/src/index.ts

@@ -48,14 +48,13 @@ 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
+// Public exports - only types that consumers need
 export type { Transport };
-export type { McpOAuthConfig, McpOAuthState, StartOAuthFlowOptions, OAuthFlowResult } from "./types.js";
+export type { McpOAuthConfig, McpOAuthState } from "./types.js";
 
 export interface CachedMcpTools {
   tools: Array<{
@@ -98,6 +97,12 @@ export interface AddMcpCommandsOptions {
    */
   getMcpTransport?: (sessionId?: string) => Transport | null | Promise<Transport | null>;
 
+  /**
+   * Extra headers for MCP HTTP requests (for example `Authorization`).
+   * Used with `getMcpUrl`. Ignored when `getMcpTransport` is set.
+   */
+  getHeaders?: () => Record<string, string> | undefined;
+
   /**
    * OAuth configuration. When provided, enables automatic OAuth authentication.
    *
@@ -225,11 +230,18 @@ function outputResult(result: {
 /**
  * Create a transport with optional OAuth authentication
  */
+function isHelpOrMetaArgv(argv: string[]) {
+  if (argv.length === 0) return true;
+  if (argv[0] === "completions" || argv.includes("--get-goke-completions")) return true;
+  return argv.some((arg) => arg === "--help" || arg === "-h" || arg === "--version" || arg === "-v");
+}
+
 function createTransportWithAuth(
   url: URL,
   sessionId: string | undefined,
   oauthState: McpOAuthState | undefined,
   oauth: McpOAuthConfig | undefined,
+  headers?: Record<string, string>,
 ): StreamableHTTPClientTransport {
   let authProvider: FileOAuthProvider | undefined;
 
@@ -247,9 +259,11 @@ function createTransportWithAuth(
     });
   }
 
+  const hasHeaders = headers && Object.keys(headers).length > 0;
   return new StreamableHTTPClientTransport(url, {
     sessionId,
     authProvider,
+    requestInit: hasHeaders ? { headers } : undefined,
   });
 }
 
@@ -271,6 +285,7 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
     clientName = "mcp-cli-client",
     getMcpUrl,
     getMcpTransport,
+    getHeaders,
     oauth,
     loadCache,
     saveCache,
@@ -288,7 +303,7 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
       const url = new URL(mcpUrl);
       const oauthState = oauth?.load();
 
-      return createTransportWithAuth(url, sessionId, oauthState, oauth);
+      return createTransportWithAuth(url, sessionId, oauthState, oauth, getHeaders?.());
     }
 
     // Legacy API: getMcpTransport
@@ -331,55 +346,62 @@ export async function addMcpCommands(options: AddMcpCommandsOptions): Promise<vo
   // Try to use cached tools first (fast path - no network)
   const cachedTools = loadCache();
   const isCacheValid = cachedTools && (Date.now() - cachedTools.timestamp) < CACHE_TTL_MS;
+  const helpOrMeta = isHelpOrMetaArgv(process.argv.slice(2));
 
-  let tools: CachedMcpTools["tools"];
+  let tools: CachedMcpTools["tools"] | undefined;
   let cachedSessionId: string | undefined;
 
-  if (isCacheValid) {
+  if (isCacheValid && cachedTools) {
     tools = cachedTools.tools;
     cachedSessionId = cachedTools.sessionId;
   } else {
-    // Cache invalid/missing - connect to fetch tools
     const transport = await getTransport();
-    if (!transport) {
-      return;
-    }
-
-    const client = new Client({ name: clientName, version: "1.0.0" }, { capabilities: {} });
-    try {
-      await client.connect(transport);
-      const result = await client.listTools();
-      tools = result.tools;
-
-      const sessionId = (transport as { sessionId?: string }).sessionId;
-
-      saveCache({
-        tools: tools.map((t) => ({
-          name: t.name,
-          description: t.description,
-          inputSchema: t.inputSchema,
-        })),
-        timestamp: Date.now(),
-        sessionId,
-      });
-      cachedSessionId = sessionId;
-    } catch (err) {
-      // Check if auth is required during tool discovery
-      if (isAuthRequiredError(err) && oauth && getMcpUrl) {
-        const mcpUrl = getMcpUrl();
-        if (mcpUrl) {
-          const authSuccess = await handleAuthRequired((mcpUrl).toString());
-          if (authSuccess) {
-            // Retry after auth
-            return addMcpCommands(options);
+    if (transport) {
+      const client = new Client({ name: clientName, version: "1.0.0" }, { capabilities: {} });
+      try {
+        await client.connect(transport);
+        const result = await client.listTools();
+        tools = result.tools;
+
+        const sessionId = (transport as { sessionId?: string }).sessionId;
+
+        saveCache({
+          tools: tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+          })),
+          timestamp: Date.now(),
+          sessionId,
+        });
+        cachedSessionId = sessionId;
+      } catch (err) {
+        const shouldAuth = isAuthRequiredError(err) && oauth && getMcpUrl && !helpOrMeta;
+        if (shouldAuth) {
+          const mcpUrl = getMcpUrl();
+          if (mcpUrl) {
+            const authSuccess = await handleAuthRequired(mcpUrl);
+            if (authSuccess) {
+              return addMcpCommands(options);
+            }
           }
         }
+        if (!helpOrMeta) {
+          console.error(`Failed to connect to MCP server: ${err instanceof Error ? err.message : err}`);
+        }
+      } finally {
+        await client.close();
       }
-      console.error(`Failed to connect to MCP server: ${err instanceof Error ? err.message : err}`);
-      return;
-    } finally {
-      await client.close();
     }
+
+    if (!tools && cachedTools) {
+      tools = cachedTools.tools;
+      cachedSessionId = cachedTools.sessionId;
+    }
+  }
+
+  if (!tools) {
+    return;
   }
 
   // Register CLI commands for each tool