docs: add dual-mode auth example to validate AuthProvider decomposition

Demonstrates two auth setups through the same authProvider slot:

MODE A (host-managed): Enclosing app owns the token. Minimal
AuthProvider with { token, onUnauthorized } — onUnauthorized signals
the host UI and throws instead of refreshing, since the host owns
the token lifecycle.

MODE B (user-configured): OAuth credentials supplied directly. Passes
a ClientCredentialsProvider; transport adapts it to AuthProvider via
adaptOAuthProvider (synthesizing token()/onUnauthorized()).

Same connectAndList() caller code for both — the transport abstracts
the difference. Validates the decomposition holds with zero branching
in user code.

Author: felixweinberger

examples/client/src/dualModeAuth.ts

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+/**
+ * Pressure-test example: two auth modes through the same `authProvider` slot.
+ *
+ * The decomposition is validated if both shapes plug in with zero branching
+ * in the transport/caller code.
+ *
+ * MODE A — Host-managed auth (token managed by an enclosing application)
+ *   - Host app owns the token; the MCP client just reads it
+ *   - On 401, the client cannot refresh — it signals the UI and bails
+ *   - Minimal AuthProvider: `{ token, onUnauthorized }` with no OAuth machinery
+ *
+ * MODE B — User-configured auth (OAuth credentials supplied directly)
+ *   - User supplies OAuth credentials; the SDK runs the full flow
+ *   - On 401, the provider refreshes via handleOAuthUnauthorized (token refresh,
+ *     or redirect for interactive flows)
+ *   - Full OAuthClientProvider, adapted to AuthProvider by the transport
+ */
+
+import type { AuthProvider } from '@modelcontextprotocol/client';
+import { Client, ClientCredentialsProvider, StreamableHTTPClientTransport, UnauthorizedError } from '@modelcontextprotocol/client';
+
+// --- Stubs for host-app integration points ---------------------------------
+
+/** Whatever the host app uses to store session state (e.g., cookies, keychain, in-memory). */
+interface HostSessionStore {
+    getMcpToken(): string | undefined;
+}
+
+/** Whatever the host app uses to surface UI prompts. */
+interface HostUi {
+    showReauthPrompt(message: string): void;
+}
+
+// --- MODE A: Host-managed auth ---------------------------------------------
+
+function createHostManagedTransport(serverUrl: URL, session: HostSessionStore, ui: HostUi): StreamableHTTPClientTransport {
+    const authProvider: AuthProvider = {
+        // Called before every request — just read whatever the host has.
+        token: async () => session.getMcpToken(),
+
+        // Called on 401 — don't refresh (the host owns the token), signal the UI and bail.
+        // The transport will retry once after this returns, so we throw to stop it:
+        // the user needs to act before a retry makes sense.
+        onUnauthorized: async () => {
+            ui.showReauthPrompt('MCP connection lost — click to reconnect');
+            throw new UnauthorizedError('Host token rejected — user action required');
+        }
+    };
+
+    return new StreamableHTTPClientTransport(serverUrl, { authProvider });
+}
+
+// --- MODE B: User-configured OAuth -----------------------------------------
+
+function createUserConfiguredTransport(serverUrl: URL, clientId: string, clientSecret: string): StreamableHTTPClientTransport {
+    // Built-in OAuth provider — the transport adapts it to AuthProvider internally.
+    // On 401, adaptOAuthProvider synthesizes onUnauthorized → handleOAuthUnauthorized,
+    // which runs token refresh (or redirect for interactive flows).
+    const authProvider = new ClientCredentialsProvider({ clientId, clientSecret });
+
+    return new StreamableHTTPClientTransport(serverUrl, { authProvider });
+}
+
+// --- Same caller code for both modes ---------------------------------------
+
+async function connectAndList(transport: StreamableHTTPClientTransport): Promise<void> {
+    const client = new Client({ name: 'dual-mode-example', version: '1.0.0' }, { capabilities: {} });
+    await client.connect(transport);
+
+    const tools = await client.listTools();
+    console.log('Tools:', tools.tools.map(t => t.name).join(', ') || '(none)');
+
+    await transport.close();
+}
+
+// --- Driver ----------------------------------------------------------------
+
+async function main() {
+    const serverUrl = new URL(process.env.MCP_SERVER_URL || 'http://localhost:3000/mcp');
+    const mode = process.argv[2] || 'host';
+
+    let transport: StreamableHTTPClientTransport;
+
+    if (mode === 'host') {
+        // Simulate a host app with a session-stored token and a UI hook.
+        const session: HostSessionStore = { getMcpToken: () => process.env.MCP_TOKEN };
+        const ui: HostUi = { showReauthPrompt: msg => console.error(`[UI] ${msg}`) };
+        transport = createHostManagedTransport(serverUrl, session, ui);
+    } else if (mode === 'oauth') {
+        const clientId = process.env.OAUTH_CLIENT_ID;
+        const clientSecret = process.env.OAUTH_CLIENT_SECRET;
+        if (!clientId || !clientSecret) {
+            console.error('OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET required for oauth mode');
+            process.exit(1);
+        }
+        transport = createUserConfiguredTransport(serverUrl, clientId, clientSecret);
+    } else {
+        console.error(`Unknown mode: ${mode}. Use 'host' or 'oauth'.`);
+        process.exit(1);
+    }
+
+    // Same connect/list code regardless of mode — the transport abstracts the difference.
+    await connectAndList(transport);
+}
+
+try {
+    await main();
+} catch (error) {
+    console.error('Error:', error);
+    // eslint-disable-next-line unicorn/no-process-exit
+    process.exit(1);
+}