Self-host MCP OAuth: connect-card path, approval screen, real-agent e2e + framework dwells (#1002)

* Self-host: serve the org-scoped MCP path the Connect card prints

The console Connect-an-agent card prints `<origin>/<organizationId>/mcp` —
a convention the multi-tenant cloud worker routes by stripping the org segment
at the edge. Self-host only served the bare `/mcp`, so a connecting MCP client
completed OAuth and then 404'd on reconnect. Self-host is single-tenant (the
session pins the one org), so the segment carries no routing meaning: both
front-ends (the prod Bun server in serve.ts and the vite dev middleware) now
strip a single leading segment from `/<seg>/mcp` and the matching OAuth
discovery path, mirroring cloud's edge rewrite but accepting any segment.

Coverage gap this slipped through: every MCP e2e built `${baseUrl}/mcp`
itself and connected to that, so none exercised the URL the card actually
hands the user. New scenario selfhost/mcp-connect-card-url scrapes the URL out
of the rendered card and asserts the server serves it (was 404, now 401) — it
fails on the pre-fix build. Also adds selfhost/mcp-oauth-consent, which records
the MCP OAuth browser flow and documents that it currently auto-consents (no
approval screen).

Shared pure helper (stripMcpOrgSegment) with unit tests; verified green on
both the selfhost (vite) and selfhost-docker (production image) targets.

* Self-host: require an MCP OAuth approval screen

Connecting MCP clients were auto-consented — a signed-in user's client got a
token with no prompt. Better Auth's MCP authorize only shows consent when the
request carries prompt=consent (clients don't send it) AND a consentPage is
configured. So: configure oidcConfig.consentPage -> the SPA route
/mcp-consent, and force the screen by injecting prompt=consent on every
/api/auth/mcp/authorize in the shared Better Auth handler (force-mcp-consent,
unit-tested). The handler also looks the registered client_name up from the
DCR row and appends it to the consent redirect so the screen reads
"Connect <name>?" rather than an opaque id (self-declared — a label, not a
trust signal). The /mcp-consent page (rebuilt from the earlier
test/selfhost-e2e-org-setup work) shows the client, scopes, an explicit note
that the grant is limited to the MCP server (not a web-app login, no other API
calls), and Allow/Deny posting to /api/auth/oauth2/consent.

Also fixes a dev-only routing bug the new route exposed: the vite middleware
matched MCP paths with rawUrl.startsWith("/mcp"), which swallowed
/mcp-consent (and its source module) and misrouted them to the API handler.
Now matches on the exact pathname.

The mcp-oauth-consent e2e asserts the approval screen appears with the client
name, Allow grants a code, and gates the connection. Green on selfhost (vite)
and selfhost-docker (prod image); unit + lint + typecheck clean.

* e2e: real OpenCode binary through self-host MCP OAuth consent, spliced

Drives the actual opencode binary through the full MCP OAuth handshake against
self-host (its own DCR/PKCE/scopes/token store), with the browser hop driven by
a real Playwright session that lands on the forced /mcp-consent approval screen
and clicks Allow — the consent redirect goes to OpenCode's own localhost
callback, so OpenCode receives the code and finishes the grant for real
(asserts a stored access token + "connected").

The agent PTY (terminal.cast) and the browser (session.mp4) run concurrently
via Effect.all and mark focus terminal→browser→terminal, so scripts/film.ts
cuts them into one film.mp4: the agent asks → we approve in the browser → the
agent is connected. Green on selfhost (vite) and selfhost-docker (prod image);
skips where the opencode binary isn't installed.

This is the real-client + spliced-recording coverage that previously lived only
on the unmerged test/selfhost-e2e-org-setup branch (record-flow-oauth.ts).

* e2e: framework-managed human dwells, gated by E2E_FILM

A scenario author shouldn't hand-code waitForTimeout to make a recording
readable — pacing is the recording's concern, not the scenario's. A dwell is a
property of a focus transition: tabbing between tools, a developer lingers a
beat to take in where they landed. So the framework owns it:

- timeline.ts gains beat()/enterFocus() + isFilming(). beat() is a no-op unless
  the run is being filmed (E2E_FILM=1, also implied by the desk's E2E_DESK).
- The browser step() enters focus (lingering on the outgoing window) and beats
  at the end so each named step's result holds on screen.
- The Cli surface holds the terminal's final frame at end of drive.

So fast/CI runs pay nothing, and a filmed run paces itself into a watchable
'moving between apps' splice. The OpenCode consent scenario drops all its
hand-rolled dwells and just names two browser steps + enterFocus at the
terminal transitions — verified: 2.9s film unfilmed, 7.2s paced under
E2E_FILM=1, green both ways.

* docs(e2e): add the OpenCode self-host MCP OAuth consent recording

The paced film (E2E_FILM=1) of selfhost/mcp-opencode-consent — the real
opencode binary asking to connect, the browser approval screen, and connected
— embedded in the PR so reviewers see the flow, not just read about it.

* Self-host: drive mcp-oauth end-to-end test through the consent screen

The forced MCP approval screen makes /authorize redirect to /mcp-consent with a
consent_code instead of straight to the client callback. Update the opaque-bearer
end-to-end test to approve on the consent screen (POST /api/auth/oauth2/consent)
and follow the returned redirectURI to the code, matching what a real client's
browser does.

Author: RhysSullivan

.changeset/selfhost-mcp-connect-url.md

@@ -0,0 +1,10 @@
+---
+"executor": patch
+---
+
+Fix the self-hosted "Connect an agent" MCP URL. The card printed an
+organization-scoped path (`<origin>/<organizationId>/mcp`) that the
+single-tenant self-host server didn't serve, so connecting an MCP client
+authorized successfully but then failed to reach the tools with an HTTP 404.
+The self-host server now accepts the organization-scoped path and routes it to
+its MCP endpoint.

.changeset/selfhost-mcp-consent.md

@@ -0,0 +1,10 @@
+---
+"executor": patch
+---
+
+Self-hosted MCP connections now require explicit approval. When an MCP client
+connects, the browser stops on an approval screen showing the connecting
+client's name, what it can access, and that the grant is limited to the MCP
+server (not a web-app login, and it can't make other API calls on your behalf);
+a token is granted only after you Approve. Previously a signed-in user's client
+was authorized automatically with no prompt.

apps/host-selfhost/src/auth/better-auth.ts

@@ -93,7 +93,18 @@ const makeAuthOptions = (url: string, getOrganizationId: () => string, gate?: Si
       admin(),
       apiKey({ enableSessionForAPIKeys: true, rateLimit: { enabled: false } }),
       bearer(),
-      mcp({ loginPage: "/login" }),
+      // `consentPage` makes the MCP authorize flow redirect to a human approval
+      // screen instead of auto-issuing a code — but ONLY when the request
+      // carries `prompt=consent`. MCP clients don't send that, so the self-host
+      // serving layer injects it on every authorize (see resolveAuthProviders'
+      // force-mcp-consent shim); together they force an approval step for every
+      // connecting client. The page itself is the SPA route `/mcp-consent`.
+      // `loginPage` in oidcConfig is required by the type but the mcp() plugin
+      // overrides it with the top-level one; `consentPage` is what we're after.
+      mcp({
+        loginPage: "/login",
+        oidcConfig: { loginPage: "/login", consentPage: "/mcp-consent" },
+      }),
     ],
     databaseHooks: {
       session: {

apps/host-selfhost/src/auth/force-mcp-consent.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "@effect/vitest";
+
+import {
+  consentRedirectClientId,
+  promptWithConsent,
+  withClientName,
+  withForcedMcpConsent,
+} from "./force-mcp-consent";
+
+describe("promptWithConsent", () => {
+  it("adds consent to an empty prompt", () => {
+    expect(promptWithConsent(null)).toBe("consent");
+    expect(promptWithConsent("")).toBe("consent");
+  });
+  it("preserves other prompt values without duplicating consent", () => {
+    expect(promptWithConsent("login")).toBe("login consent");
+    expect(promptWithConsent("consent")).toBe("consent");
+    expect(promptWithConsent("login consent")).toBe("login consent");
+  });
+});
+
+describe("withForcedMcpConsent", () => {
+  const authorize = (qs: string) => new Request(`https://host.example/api/auth/mcp/authorize${qs}`);
+
+  it("injects prompt=consent on MCP authorize", () => {
+    const out = withForcedMcpConsent(authorize("?client_id=abc&response_type=code"));
+    expect(new URL(out.url).searchParams.get("prompt")).toBe("consent");
+  });
+
+  it("merges with an existing prompt", () => {
+    const out = withForcedMcpConsent(authorize("?client_id=abc&prompt=login"));
+    expect(new URL(out.url).searchParams.get("prompt")).toBe("login consent");
+  });
+
+  it("leaves an already-consent request unchanged (same instance)", () => {
+    const req = authorize("?client_id=abc&prompt=consent");
+    expect(withForcedMcpConsent(req)).toBe(req);
+  });
+
+  it("never touches non-authorize or non-GET requests", () => {
+    const other = new Request("https://host.example/api/auth/mcp/token", { method: "POST" });
+    expect(withForcedMcpConsent(other)).toBe(other);
+    const consent = new Request("https://host.example/api/auth/oauth2/consent", { method: "POST" });
+    expect(withForcedMcpConsent(consent)).toBe(consent);
+  });
+});
+
+describe("consentRedirectClientId", () => {
+  it("returns the client id of a consent redirect lacking a name", () => {
+    expect(consentRedirectClientId("/mcp-consent?consent_code=c&client_id=abc&scope=openid")).toBe(
+      "abc",
+    );
+  });
+  it("returns null when the name is already present, or it isn't a consent redirect", () => {
+    expect(consentRedirectClientId("/mcp-consent?client_id=abc&client_name=Codex")).toBeNull();
+    expect(consentRedirectClientId("/login?client_id=abc")).toBeNull();
+    expect(consentRedirectClientId(null)).toBeNull();
+  });
+});
+
+describe("withClientName", () => {
+  it("appends client_name to a consent redirect (path+query only)", () => {
+    expect(withClientName("/mcp-consent?consent_code=c&client_id=abc", "Claude Code")).toBe(
+      "/mcp-consent?consent_code=c&client_id=abc&client_name=Claude+Code",
+    );
+  });
+});

apps/host-selfhost/src/auth/force-mcp-consent.ts

@@ -0,0 +1,59 @@
+// Force a human approval screen on every MCP OAuth connection.
+//
+// Better Auth's MCP authorize endpoint only shows the consent page when the
+// request carries `prompt=consent` (it otherwise auto-issues an authorization
+// code — see better-auth/plugins/mcp/authorize). MCP clients don't send that,
+// so a connecting client would be granted a token with no human approval. This
+// wraps Better Auth's web handler and adds `consent` to the `prompt` of every
+// `GET /api/auth/mcp/authorize`, so — paired with `oidcConfig.consentPage` —
+// every connect is gated on the `/oauth/consent` approval screen.
+//
+// Pure + Effect-free; the wrapper is a plain Request -> Request transform so it
+// composes with whatever serves the Better Auth handler (prod + vite dev both
+// mount the same handler).
+
+const AUTHORIZE_PATH = "/api/auth/mcp/authorize";
+const CONSENT_PAGE = "/mcp-consent";
+
+/** Merge `consent` into a possibly-empty space-separated `prompt` value. */
+export const promptWithConsent = (prompt: string | null): string => {
+  const set = new Set((prompt ?? "").split(/\s+/).filter((value) => value.length > 0));
+  set.add("consent");
+  return Array.from(set).join(" ");
+};
+
+/**
+ * Return the MCP-authorize request with `prompt=consent` ensured, or the
+ * original request unchanged when it isn't an MCP authorize call.
+ */
+export const withForcedMcpConsent = (request: Request): Request => {
+  if (request.method !== "GET") return request;
+  const url = new URL(request.url);
+  if (url.pathname !== AUTHORIZE_PATH) return request;
+  const prompt = url.searchParams.get("prompt");
+  if (prompt && prompt.split(/\s+/).includes("consent")) return request;
+  url.searchParams.set("prompt", promptWithConsent(prompt));
+  return new Request(url, request);
+};
+
+/**
+ * If `location` is Better Auth's redirect to the consent page carrying a
+ * `client_id` but no `client_name`, return that client id (so the caller can
+ * look up the registered name and enrich the redirect). Otherwise null.
+ * Better Auth's authorize only puts the opaque `client_id` on the consent
+ * redirect; the registered name makes the approval screen legible.
+ */
+export const consentRedirectClientId = (location: string | null): string | null => {
+  if (!location) return null;
+  const url = new URL(location, "http://host.internal");
+  if (url.pathname !== CONSENT_PAGE) return null;
+  if (url.searchParams.get("client_name")) return null;
+  return url.searchParams.get("client_id");
+};
+
+/** Append `client_name` to a consent-page redirect URL (path + query only). */
+export const withClientName = (location: string, clientName: string): string => {
+  const url = new URL(location, "http://host.internal");
+  url.searchParams.set("client_name", clientName);
+  return `${url.pathname}${url.search}`;
+};

apps/host-selfhost/src/auth/index.ts

@@ -5,6 +5,7 @@ import { IdentityProvider } from "@executor-js/api/server";
 import type { SelfHostDbHandle } from "../db/self-host-db";
 import { BetterAuth, buildBetterAuth, type BetterAuthHandle } from "./better-auth";
 import { betterAuthIdentityLayer } from "./identity";
+import { consentRedirectClientId, withClientName, withForcedMcpConsent } from "./force-mcp-consent";
 
 export { BetterAuth, buildBetterAuth, type BetterAuthHandle } from "./better-auth";
 export { betterAuthIdentityLayer } from "./identity";
@@ -37,9 +38,40 @@ export const resolveAuthProviders = async (
 ): Promise<ResolvedAuthProviders> => {
   const betterAuth = await buildBetterAuth(dbHandle.url, dbHandle.client);
   const betterAuthLayer = Layer.succeed(BetterAuth)(betterAuth);
+
+  // The consent redirect from Better Auth's authorize only carries the opaque
+  // client_id; look the registered client_name up (its adapter sees the
+  // just-written DCR row) so the approval screen reads "Connect Codex?" not a
+  // random id. Self-declared at open DCR — a label, not a trust signal.
+  const lookupClientName = async (clientId: string): Promise<string | null> => {
+    const ctx = await betterAuth.auth.$context;
+    const app = await ctx.adapter.findOne<{ name?: string | null }>({
+      model: "oauthApplication",
+      where: [{ field: "clientId", value: clientId }],
+    });
+    return app?.name ?? null;
+  };
+
+  // Force the MCP approval screen: inject `prompt=consent` on every MCP
+  // authorize so a connecting client is gated on /mcp-consent rather than
+  // silently granted a token (see ./force-mcp-consent), and enrich the
+  // resulting consent redirect with the registered client name.
+  const authHandler = async (request: Request): Promise<Response> => {
+    const response = await betterAuth.handler(withForcedMcpConsent(request));
+    if (response.status !== 302) return response;
+    const clientId = consentRedirectClientId(response.headers.get("location"));
+    if (!clientId) return response;
+    const name = await lookupClientName(clientId);
+    if (!name) return response;
+    // Preserve the rest of the response — notably the signed consent cookie.
+    const headers = new Headers(response.headers);
+    headers.set("location", withClientName(response.headers.get("location")!, name));
+    return new Response(null, { status: 302, headers });
+  };
+
   return {
     identityLayer: betterAuthIdentityLayer.pipe(Layer.provide(betterAuthLayer)),
-    authHandler: betterAuth.handler,
+    authHandler,
     betterAuth,
   };
 };

apps/host-selfhost/src/mcp/mcp-oauth.test.ts

@@ -96,7 +96,11 @@ test("MCP OAuth opaque-bearer flow authenticates /mcp end-to-end", async () => {
   expect([200, 201]).toContain(reg.status);
   const clientId = String((await json(reg)).client_id);
 
-  // 2. PKCE authorize with the signed-in session cookie -> 302 to redirect_uri?code=…
+  // 2. PKCE authorize with the signed-in session cookie. Self-host forces an
+  // approval screen (prompt=consent injected by the serving layer), so authorize
+  // does NOT redirect straight to the client callback — it redirects to the
+  // relative /mcp-consent page carrying a consent_code. A real client's browser
+  // lands there and the user clicks Allow; we drive that POST directly.
   const verifier = b64url(crypto.getRandomValues(new Uint8Array(32)));
   const challengeBytes = new Uint8Array(
     await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier)),
@@ -114,9 +118,25 @@ test("MCP OAuth opaque-bearer flow authenticates /mcp end-to-end", async () => {
   const authorize = await handler(
     new Request(authorizeUrl, { headers: { cookie }, redirect: "manual" }),
   );
-  expect([302, 200]).toContain(authorize.status);
-  const location = authorize.headers.get("location") ?? "";
-  const code = new URL(location).searchParams.get("code") ?? "";
+  expect(authorize.status).toBe(302);
+  // Resolve against BASE — the consent redirect is a relative app path.
+  const consentRedirect = new URL(authorize.headers.get("location") ?? "", BASE);
+  expect(consentRedirect.pathname).toBe("/mcp-consent");
+  const consentCode = consentRedirect.searchParams.get("consent_code") ?? "";
+  expect(consentCode).not.toBe("");
+
+  // 2b. Approve on the consent screen — the same POST the /mcp-consent page makes.
+  // It returns { redirectURI } back to the client's callback carrying the code.
+  const consent = await handler(
+    new Request(`${BASE}/api/auth/oauth2/consent`, {
+      method: "POST",
+      headers: { "content-type": "application/json", cookie },
+      body: JSON.stringify({ accept: true, consent_code: consentCode }),
+    }),
+  );
+  expect(consent.status).toBe(200);
+  const redirectURI = String((await json(consent)).redirectURI ?? "");
+  const code = new URL(redirectURI).searchParams.get("code") ?? "";
   expect(code).not.toBe("");
 
   // 3. Token exchange.

apps/host-selfhost/src/mcp/org-path.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "@effect/vitest";
+
+import { stripMcpOrgSegment } from "./org-path";
+
+describe("stripMcpOrgSegment", () => {
+  it("strips a single org segment before /mcp", () => {
+    expect(stripMcpOrgSegment("/iI9idP7BZcWpg9wW8cit3xE4r4dFSnHj/mcp")).toBe("/mcp");
+    expect(stripMcpOrgSegment("/org_123/mcp")).toBe("/mcp");
+  });
+
+  it("strips the org segment from the protected-resource discovery path", () => {
+    expect(stripMcpOrgSegment("/.well-known/oauth-protected-resource/abc123/mcp")).toBe(
+      "/.well-known/oauth-protected-resource/mcp",
+    );
+  });
+
+  it("leaves the bare paths untouched", () => {
+    expect(stripMcpOrgSegment("/mcp")).toBeNull();
+    expect(stripMcpOrgSegment("/.well-known/oauth-protected-resource/mcp")).toBeNull();
+    expect(stripMcpOrgSegment("/.well-known/oauth-authorization-server")).toBeNull();
+  });
+
+  it("never claims OAuth endpoints or unrelated paths", () => {
+    expect(stripMcpOrgSegment("/api/auth/mcp/authorize")).toBeNull();
+    expect(stripMcpOrgSegment("/api/auth/mcp/register")).toBeNull();
+    expect(stripMcpOrgSegment("/integrations")).toBeNull();
+    expect(stripMcpOrgSegment("/")).toBeNull();
+    expect(stripMcpOrgSegment("/a/b/mcp")).toBeNull(); // deeper than one segment
+  });
+});

apps/host-selfhost/src/mcp/org-path.ts

@@ -0,0 +1,36 @@
+// Self-host serves MCP at the bare `/mcp` path (and bare OAuth discovery docs).
+// The console "Connect an agent" card, however, prints
+// `<origin>/<organizationId>/mcp` — a convention the multi-tenant cloud worker
+// routes (it strips the org segment at the edge, carrying the org in a header).
+// Self-host is single-tenant: the session already pins the one org, so the org
+// segment in the URL carries no routing meaning. Rather than special-case the
+// card per host, both self-host front-ends (the prod Bun server and the vite
+// dev middleware) strip a single leading segment so the card's URL reaches the
+// real route — mirroring cloud's edge rewrite, but accepting ANY segment (a
+// Better Auth org id is not the `org_…` shape cloud keys on) and setting no
+// header.
+//
+// Pure + Effect-free on purpose: the vite config imports it too.
+
+const PRM_PREFIX = "/.well-known/oauth-protected-resource";
+
+/**
+ * Given a request pathname, return the bare MCP pathname it should route to
+ * when it carries a single leading org segment, or `null` when no rewrite
+ * applies (already bare, not an MCP path, or an OAuth endpoint like
+ * `/api/auth/mcp/authorize`).
+ *
+ *   /<seg>/mcp                                          -> /mcp
+ *   /.well-known/oauth-protected-resource/<seg>/mcp     -> /.well-known/oauth-protected-resource/mcp
+ */
+export const stripMcpOrgSegment = (pathname: string): string | null => {
+  if (pathname.startsWith(`${PRM_PREFIX}/`)) {
+    const rest = pathname
+      .slice(PRM_PREFIX.length + 1)
+      .split("/")
+      .filter((segment) => segment.length > 0);
+    return rest.length === 2 && rest[1] === "mcp" ? `${PRM_PREFIX}/mcp` : null;
+  }
+  const segments = pathname.split("/").filter((segment) => segment.length > 0);
+  return segments.length === 2 && segments[1] === "mcp" ? "/mcp" : null;
+};

apps/host-selfhost/src/serve.ts

@@ -15,15 +15,39 @@
 
 import { fileURLToPath } from "node:url";
 
-import { HttpRouter, HttpStaticServer } from "effect/unstable/http";
+import {
+  HttpMiddleware,
+  HttpRouter,
+  HttpServerRequest,
+  HttpStaticServer,
+} from "effect/unstable/http";
 import { BunFileSystem, BunHttpServer, BunPath, BunRuntime } from "@effect/platform-bun";
-import { Layer } from "effect";
+import { Effect, Layer } from "effect";
 
 import { makeSelfHostApp } from "./app";
 import { loadConfig } from "./config";
+import { stripMcpOrgSegment } from "./mcp/org-path";
 
 const distDir = fileURLToPath(new URL("../dist/", import.meta.url));
 
+// Rewrite `/<org>/mcp` (and its OAuth discovery path) to the bare path before
+// routing, so the "Connect an agent" card's org-pinned URL reaches the real
+// `/mcp` route — see ./mcp/org-path. A no-op for every other request.
+const mcpOrgPathRewrite = HttpMiddleware.make((httpApp) =>
+  Effect.gen(function* () {
+    const request = yield* HttpServerRequest.HttpServerRequest;
+    const url = new URL(request.url, "http://host.internal");
+    const rewritten = stripMcpOrgSegment(url.pathname);
+    if (rewritten === null) return yield* httpApp;
+    return yield* httpApp.pipe(
+      Effect.provideService(
+        HttpServerRequest.HttpServerRequest,
+        request.modify({ url: `${rewritten}${url.search}` }),
+      ),
+    );
+  }),
+);
+
 export const startServer = async (): Promise<void> => {
   const config = loadConfig();
   const { AppLayer } = await makeSelfHostApp();
@@ -35,7 +59,9 @@ export const startServer = async (): Promise<void> => {
     Layer.provide(BunPath.layer),
   );
 
-  const ServerLive = HttpRouter.serve(Layer.mergeAll(AppLayer, StaticLive)).pipe(
+  const ServerLive = HttpRouter.serve(Layer.mergeAll(AppLayer, StaticLive), {
+    middleware: mcpOrgPathRewrite,
+  }).pipe(
     Layer.provide(
       BunHttpServer.layer({ hostname: config.host, port: config.port, idleTimeout: 0 }),
     ),