feat(mcp): add oauth callbackHost config

chrisolszewski · chrisolszewski · commit bb069b3ead69 · 2026-02-26T10:47:18.000-05:00
Add optional callbackHost field to MCP OAuth config that controls
the bind address for the OAuth callback server. Useful for WSL2,
Docker, and devcontainer environments where the default loopback
bind is not reachable from the host browser.

- Add callbackHost to McpOAuth schema with .min(1) validation
- Update ensureRunning(opts?) with backward-compatible signature
- Track currentHost and restart server on host change
- Normalize 0.0.0.0 to 127.0.0.1 for port-in-use checks
- Fix HTML injection in error page (escapeHtml)
- Add config validation tests
- Document in mcp-servers.mdx Debugging section
diff --git a/packages/opencode/src/config/config.ts b/packages/opencode/src/config/config.ts
@@ -542,6 +542,11 @@ export namespace Config {
         .describe("OAuth client ID. If not provided, dynamic client registration (RFC 7591) will be attempted."),
       clientSecret: z.string().optional().describe("OAuth client secret (if required by the authorization server)"),
       scope: z.string().optional().describe("OAuth scopes to request during authorization"),
+      callbackHost: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Host address to bind the OAuth callback server to (e.g. '0.0.0.0' for WSL2/Docker)"),
     })
     .strict()
     .meta({
diff --git a/packages/opencode/src/mcp/index.ts b/packages/opencode/src/mcp/index.ts
@@ -726,19 +726,18 @@ export namespace MCP {
       throw new Error(`MCP server ${mcpName} has OAuth explicitly disabled`)
     }
 
+    // OAuth config is optional - if not provided, we'll use auto-discovery
+    const oauthConfig = typeof mcpConfig.oauth === "object" ? mcpConfig.oauth : undefined
+
     // Start the callback server
-    await McpOAuthCallback.ensureRunning()
+    await McpOAuthCallback.ensureRunning({ callbackHost: oauthConfig?.callbackHost })
 
     // Generate and store a cryptographically secure state parameter BEFORE creating the provider
     // The SDK will call provider.state() to read this value
     const oauthState = Array.from(crypto.getRandomValues(new Uint8Array(32)))
       .map((b) => b.toString(16).padStart(2, "0"))
       .join("")
     await McpAuth.updateOAuthState(mcpName, oauthState)
-
-    // Create a new auth provider for this flow
-    // OAuth config is optional - if not provided, we'll use auto-discovery
-    const oauthConfig = typeof mcpConfig.oauth === "object" ? mcpConfig.oauth : undefined
     let capturedUrl: URL | undefined
     const authProvider = new McpOAuthProvider(
       mcpName,
diff --git a/packages/opencode/src/mcp/oauth-callback.ts b/packages/opencode/src/mcp/oauth-callback.ts
@@ -23,6 +23,10 @@ const HTML_SUCCESS = `<!DOCTYPE html>
 </body>
 </html>`
 
+function escapeHtml(str: string): string {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;")
+}
+
 const HTML_ERROR = (error: string) => `<!DOCTYPE html>
 <html>
 <head>
@@ -39,7 +43,7 @@ const HTML_ERROR = (error: string) => `<!DOCTYPE html>
   <div class="container">
     <h1>Authorization Failed</h1>
     <p>An error occurred during authorization.</p>
-    <div class="error">${error}</div>
+    <div class="error">${escapeHtml(error)}</div>
   </div>
 </body>
 </html>`
@@ -52,21 +56,34 @@ interface PendingAuth {
 
 export namespace McpOAuthCallback {
   let server: ReturnType<typeof Bun.serve> | undefined
+  let currentHost: string | undefined
   const pendingAuths = new Map<string, PendingAuth>()
 
   const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000 // 5 minutes
 
-  export async function ensureRunning(): Promise<void> {
-    if (server) return
+  export async function ensureRunning(opts?: { callbackHost?: string }): Promise<void> {
+    const callbackHost = opts?.callbackHost
+
+    if (server && callbackHost === currentHost) return
+    if (server && callbackHost !== currentHost) {
+      log.info("restarting oauth callback server with new host", { oldHost: currentHost, newHost: callbackHost })
+      server.stop()
+      server = undefined
+    }
 
-    const running = await isPortInUse()
+    const checkHost = !callbackHost || callbackHost === "0.0.0.0" ? "127.0.0.1" : callbackHost
+    const running = await isPortInUse(checkHost)
     if (running) {
-      log.info("oauth callback server already running on another instance", { port: OAUTH_CALLBACK_PORT })
+      log.info("oauth callback server already running on another instance", {
+        port: OAUTH_CALLBACK_PORT,
+        host: checkHost,
+      })
       return
     }
 
     server = Bun.serve({
       port: OAUTH_CALLBACK_PORT,
+      ...(callbackHost ? { hostname: callbackHost } : {}),
       fetch(req) {
         const url = new URL(req.url)
 
@@ -133,7 +150,8 @@ export namespace McpOAuthCallback {
       },
     })
 
-    log.info("oauth callback server started", { port: OAUTH_CALLBACK_PORT })
+    currentHost = callbackHost
+    log.info("oauth callback server started", { port: OAUTH_CALLBACK_PORT, host: callbackHost ?? "default" })
   }
 
   export function waitForCallback(oauthState: string): Promise<string> {
@@ -158,10 +176,10 @@ export namespace McpOAuthCallback {
     }
   }
 
-  export async function isPortInUse(): Promise<boolean> {
+  export async function isPortInUse(host: string = "127.0.0.1"): Promise<boolean> {
     return new Promise((resolve) => {
       Bun.connect({
-        hostname: "127.0.0.1",
+        hostname: host,
         port: OAUTH_CALLBACK_PORT,
         socket: {
           open(socket) {
diff --git a/packages/opencode/test/config/config.test.ts b/packages/opencode/test/config/config.test.ts
@@ -1884,3 +1884,39 @@ describe("OPENCODE_CONFIG_CONTENT token substitution", () => {
     }
   })
 })
+
+describe("MCP OAuth callbackHost validation", () => {
+  test("accepts valid callbackHost", () => {
+    const result = Config.McpOAuth.safeParse({ callbackHost: "0.0.0.0" })
+    expect(result.success).toBe(true)
+    if (result.success) expect(result.data.callbackHost).toBe("0.0.0.0")
+  })
+
+  test("accepts 127.0.0.1", () => {
+    const result = Config.McpOAuth.safeParse({ callbackHost: "127.0.0.1" })
+    expect(result.success).toBe(true)
+  })
+
+  test("rejects empty string", () => {
+    const result = Config.McpOAuth.safeParse({ callbackHost: "" })
+    expect(result.success).toBe(false)
+  })
+
+  test("allows omitting callbackHost", () => {
+    const result = Config.McpOAuth.safeParse({})
+    expect(result.success).toBe(true)
+    if (result.success) expect(result.data.callbackHost).toBeUndefined()
+  })
+
+  test("works with other oauth fields", () => {
+    const result = Config.McpOAuth.safeParse({
+      clientId: "my-client",
+      callbackHost: "0.0.0.0",
+    })
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.clientId).toBe("my-client")
+      expect(result.data.callbackHost).toBe("0.0.0.0")
+    }
+  })
+})
diff --git a/packages/opencode/test/mcp/oauth-callback.test.ts b/packages/opencode/test/mcp/oauth-callback.test.ts
@@ -0,0 +1,68 @@
+import { describe, test, expect, mock, beforeEach, afterEach } from "bun:test"
+
+describe("McpOAuthCallback ensureRunning behavior", () => {
+  let originalServe: typeof Bun.serve
+  let originalConnect: typeof Bun.connect
+  let serveCallArgs: Array<{ hostname?: string; port?: number }>
+  let mockServer: { stop: ReturnType<typeof mock> }
+
+  beforeEach(() => {
+    serveCallArgs = []
+    mockServer = { stop: mock(() => {}) }
+    originalServe = Bun.serve
+    originalConnect = Bun.connect
+
+    Bun.serve = mock((opts: any) => {
+      serveCallArgs.push({ hostname: opts.hostname, port: opts.port })
+      return mockServer as any
+    }) as any
+
+    Bun.connect = mock(() => Promise.reject(new Error("Connection refused"))) as any
+  })
+
+  afterEach(async () => {
+    Bun.serve = originalServe
+    Bun.connect = originalConnect
+    const mod = await import("../../src/mcp/oauth-callback")
+    mod.McpOAuthCallback.stop()
+  })
+
+  test("passes hostname to Bun.serve when callbackHost is set", async () => {
+    const { McpOAuthCallback } = await import("../../src/mcp/oauth-callback")
+    await McpOAuthCallback.ensureRunning({ callbackHost: "127.0.0.1" })
+
+    expect(serveCallArgs.length).toBe(1)
+    expect(serveCallArgs[0].hostname).toBe("127.0.0.1")
+  })
+
+  test("does not pass hostname when callbackHost is unset", async () => {
+    const { McpOAuthCallback } = await import("../../src/mcp/oauth-callback")
+    await McpOAuthCallback.ensureRunning()
+
+    expect(serveCallArgs.length).toBe(1)
+    expect(serveCallArgs[0].hostname).toBeUndefined()
+  })
+
+  test("restarts server when callbackHost changes", async () => {
+    const { McpOAuthCallback } = await import("../../src/mcp/oauth-callback")
+
+    await McpOAuthCallback.ensureRunning({ callbackHost: "127.0.0.1" })
+    expect(serveCallArgs.length).toBe(1)
+    expect(mockServer.stop).not.toHaveBeenCalled()
+
+    await McpOAuthCallback.ensureRunning({ callbackHost: "0.0.0.0" })
+    expect(serveCallArgs.length).toBe(2)
+    expect(mockServer.stop).toHaveBeenCalled()
+    expect(serveCallArgs[1].hostname).toBe("0.0.0.0")
+  })
+
+  test("does not restart when callbackHost unchanged", async () => {
+    const { McpOAuthCallback } = await import("../../src/mcp/oauth-callback")
+
+    await McpOAuthCallback.ensureRunning({ callbackHost: "127.0.0.1" })
+    await McpOAuthCallback.ensureRunning({ callbackHost: "127.0.0.1" })
+
+    expect(serveCallArgs.length).toBe(1)
+    expect(mockServer.stop).not.toHaveBeenCalled()
+  })
+})
diff --git a/packages/web/src/content/docs/mcp-servers.mdx b/packages/web/src/content/docs/mcp-servers.mdx
@@ -272,6 +272,7 @@ If you want to disable automatic OAuth for a server (e.g., for servers that use
 | `clientId`     | String          | OAuth client ID. If not provided, dynamic client registration will be attempted. |
 | `clientSecret` | String          | OAuth client secret, if required by the authorization server.                    |
 | `scope`        | String          | OAuth scopes to request during authorization.                                    |
+| `callbackHost` | String          | Bind address for the callback server. See [Debugging](#debugging).               |
 
 #### Debugging
 
@@ -287,6 +288,26 @@ opencode mcp debug my-oauth-server
 
 The `mcp debug` command shows the current auth status, tests HTTP connectivity, and attempts the OAuth discovery flow.
 
+If you're running OpenCode in WSL2, Docker, or a devcontainer and OAuth callbacks fail, the callback server may not be reachable from your host browser. Set `callbackHost` to an address your host can reach (commonly `0.0.0.0`).
+
+:::caution
+Binding to `0.0.0.0` exposes the callback listener on your network, not just localhost. Use only when needed.
+:::
+
+`callbackHost` only affects the bind address; it does not change `redirectUri`.
+
+```json title="opencode.json" {4}
+{
+  "mcp": {
+    "my-server": {
+      "oauth": { "callbackHost": "0.0.0.0" }
+    }
+  }
+}
+```
+
+In containers, you may also need to publish/forward port `19876` (or your configured redirect port) to the host.
+
 ---
 
 ## Manage
