Show an actionable message when MCP OAuth dynamic registration is rejected (UsefulSoftwareCo#1121)

jackulau · RhysSullivan · web-flow · commit 5250f645188a · 2026-06-28T01:15:29.000-07:00
* fix(oauth): actionable message when DCR rejects a non-loopback redirect URI

Authorization servers that follow RFC 8252 strictly (e.g. Vercel MCP) only
approve loopback redirect URIs for anonymous Dynamic Client Registration.
Executor registers its browser origin, so a hosted, tailnet, or LAN origin
trips invalid_redirect_uri. Map that opaque code to guidance: name the
loopback-only requirement, the offending URI, and the two recovery paths.

Gated on the redirect URI being non-loopback so we never tell a localhost
user to use localhost. Adds an approveRedirectUri option to the OAuth test
server to mimic the loopback-only allowlist.

Goal: 001-fix-770-vercel-mcp-dcr-fallback (deliverable 1)

* fix(react): surface the DCR rejection reason in the BYO fallback

When transparent Dynamic Client Registration fails, runDcrConnect now returns
the server's failure message in the fallback outcome instead of swallowing it,
and the Add MCP Source / add-account modal shows that message (e.g. the
loopback redirect-URI rejection) over the generic 'register an app' copy. The
register dep widens to return { error } on failure; the OAuth start is skipped.

Also narrows the new SDK test's error reads to the typed OAuthRegisterDynamicError
and repositions the boundary lint directive.

Goal: 001-fix-770-vercel-mcp-dcr-fallback (deliverable 2)

---------

Co-authored-by: Jack &lt;72348727+Jack-GitHub12@users.noreply.github.com&gt;
Co-authored-by: Rhys Sullivan &lt;39114868+RhysSullivan@users.noreply.github.com&gt;
diff --git a/packages/core/sdk/src/oauth-helpers.ts b/packages/core/sdk/src/oauth-helpers.ts
@@ -61,7 +61,7 @@ export interface OAuthEndpointUrlPolicy {
   readonly allowHttp?: boolean;
 }
 
-const isLoopbackHttpUrl = (value: string): boolean => {
+export const isLoopbackHttpUrl = (value: string): boolean => {
   if (!URL.canParse(value)) return false;
   const url = new URL(value);
   if (url.protocol !== "http:") return false;
diff --git a/packages/core/sdk/src/oauth-register-dynamic.test.ts b/packages/core/sdk/src/oauth-register-dynamic.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "@effect/vitest";
-import { Effect } from "effect";
+import { Effect, Predicate } from "effect";
 
 import {
   AuthTemplateSlug,
@@ -8,6 +8,7 @@ import {
   OAuthClientSlug,
   ToolName,
 } from "./ids";
+import { OAuthRegisterDynamicError } from "./oauth-client";
 import { definePlugin } from "./plugin";
 import { makeTestWorkspaceHarness, memoryCredentialsPlugin } from "./test-config";
 import { serveOAuthTestServer } from "./testing/oauth-test-server";
@@ -143,4 +144,89 @@ describe("oauth.registerDynamicClient", () => {
       }),
     ),
   );
+
+  // Regression: issue #770. Vercel (and other RFC 8252-strict servers) only
+  // approve loopback redirect URIs for anonymous DCR, so a hosted/tailnet/LAN
+  // origin trips `invalid_redirect_uri`. The failure must explain the loopback
+  // requirement and name the offending URI, not dump the raw RFC code.
+  it.effect("DCR rejection of a non-loopback redirect URI yields an actionable loopback hint", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const server = yield* serveOAuthTestServer({
+          scopes: ["read"],
+          // Mirror Vercel: approve only loopback redirect URIs for anonymous DCR.
+          approveRedirectUri: (uri) =>
+            uri.startsWith("http://localhost") || uri.startsWith("http://127."),
+        });
+        const { executor } = yield* makeTestWorkspaceHarness({ plugins });
+        yield* executor.acme.seed();
+        const probe = yield* executor.oauth.probe({ url: server.mcpResourceUrl });
+
+        const nonLoopback = "https://app.example.com/api/oauth/callback";
+        const error = yield* Effect.flip(
+          executor.oauth.registerDynamicClient({
+            owner: "org",
+            slug: CLIENT,
+            registrationEndpoint: probe.registrationEndpoint!,
+            authorizationUrl: probe.authorizationUrl,
+            tokenUrl: probe.tokenUrl,
+            resource: probe.resource,
+            scopes: ["read"],
+            tokenEndpointAuthMethodsSupported: probe.tokenEndpointAuthMethodsSupported,
+            clientName: "Acme DCR",
+            redirectUri: nonLoopback,
+            originIntegration: INTEG,
+          }),
+        );
+        // Predicate guard narrows the union so `.message` reads off a typed failure.
+        expect(Predicate.isTagged("OAuthRegisterDynamicError")(error)).toBe(true);
+        const registerError = error as OAuthRegisterDynamicError;
+        const message = registerError.message;
+        // Names the loopback-only requirement, the localhost fix, and the URI.
+        expect(message).toContain("loopback");
+        expect(message).toContain("http://localhost");
+        expect(message).toContain(nonLoopback);
+      }),
+    ),
+  );
+
+  // The loopback hint is gated on the redirect URI actually being non-loopback.
+  // A server that rejects even a loopback URI keeps the generic message so we
+  // never tell the user "use localhost" when they already are.
+  it.effect(
+    "DCR rejection of a loopback redirect URI keeps the generic message (no false hint)",
+    () =>
+      Effect.scoped(
+        Effect.gen(function* () {
+          const server = yield* serveOAuthTestServer({
+            scopes: ["read"],
+            approveRedirectUri: () => false, // reject every redirect URI, even loopback
+          });
+          const { executor } = yield* makeTestWorkspaceHarness({ plugins });
+          yield* executor.acme.seed();
+          const probe = yield* executor.oauth.probe({ url: server.mcpResourceUrl });
+
+          const error = yield* Effect.flip(
+            executor.oauth.registerDynamicClient({
+              owner: "org",
+              slug: CLIENT,
+              registrationEndpoint: probe.registrationEndpoint!,
+              authorizationUrl: probe.authorizationUrl,
+              tokenUrl: probe.tokenUrl,
+              resource: probe.resource,
+              scopes: ["read"],
+              tokenEndpointAuthMethodsSupported: probe.tokenEndpointAuthMethodsSupported,
+              clientName: "Acme DCR",
+              redirectUri: "http://127.0.0.1:5394/api/oauth/callback",
+              originIntegration: INTEG,
+            }),
+          );
+          expect(Predicate.isTagged("OAuthRegisterDynamicError")(error)).toBe(true);
+          const registerError = error as OAuthRegisterDynamicError;
+          const message = registerError.message;
+          expect(message).toContain("Dynamic Client Registration failed: invalid_redirect_uri");
+          expect(message).not.toContain("Automatic OAuth setup failed");
+        }),
+      ),
+  );
 });
diff --git a/packages/core/sdk/src/oauth-service.ts b/packages/core/sdk/src/oauth-service.ts
@@ -64,6 +64,7 @@ import {
   createPkceCodeVerifier,
   exchangeAuthorizationCode,
   exchangeClientCredentials,
+  isLoopbackHttpUrl,
   rebindTokenEndpointHostToCallbackDomain,
   type OAuth2TokenResponse,
   type OAuthEndpointUrlPolicy,
@@ -573,13 +574,24 @@ export const makeOAuthService = (deps: OAuthServiceDeps): OAuthService => {
         },
         { httpClientLayer, endpointUrlPolicy: deps.endpointUrlPolicy },
       ).pipe(
-        Effect.mapError(
-          (cause) =>
-            new OAuthRegisterDynamicError({
-              // oxlint-disable-next-line executor/no-unknown-error-message -- boundary: OAuthDiscoveryError carries a typed `message` field
-              message: `Dynamic Client Registration failed: ${cause.message}`,
-            }),
-        ),
+        Effect.mapError((cause) => {
+          // Some authorization servers (Vercel, and others that follow RFC 8252
+          // strictly) reject anonymous Dynamic Client Registration unless the
+          // redirect URI is loopback (http://localhost or http://127.0.0.1).
+          // Executor registers its browser origin, so any hosted, tailnet, or
+          // LAN origin trips `invalid_redirect_uri`. Turn that opaque RFC code
+          // into guidance the user can act on instead of the raw error.
+          // oxlint-disable-next-line executor/no-unknown-error-message -- boundary: OAuthDiscoveryError carries a typed `message`
+          const rawMessage = cause.message;
+          const message =
+            cause.error === "invalid_redirect_uri" && !isLoopbackHttpUrl(flowRedirectUri)
+              ? `Automatic OAuth setup failed: this server only approves loopback redirect ` +
+                `URLs (http://localhost or http://127.0.0.1) for automatic registration, but ` +
+                `Executor is using ${flowRedirectUri}. Register an OAuth app manually with that ` +
+                `redirect URL approved by the server, or run Executor on http://localhost.`
+              : `Dynamic Client Registration failed: ${rawMessage}`;
+          return new OAuthRegisterDynamicError({ message });
+        }),
       );
 
       // Persist the minted client. DCR-minted public clients have no secret; we
diff --git a/packages/core/sdk/src/testing/oauth-test-server.ts b/packages/core/sdk/src/testing/oauth-test-server.ts
@@ -53,6 +53,11 @@ export interface OAuthTestServerOptions {
   readonly scopes?: readonly string[];
   readonly omitTokenResponseScopes?: readonly string[];
   readonly supportRefresh?: boolean;
+  /** Gate Dynamic Client Registration on the requested redirect URIs. When set,
+   *  `/register` returns `400 invalid_redirect_uri` unless every requested
+   *  `redirect_uris` entry is approved. Mirrors authorization servers (e.g.
+   *  Vercel) that only accept loopback redirect URIs for anonymous DCR. */
+  readonly approveRedirectUri?: (uri: string) => boolean;
 }
 
 export interface OAuthTestServerShape {
@@ -503,6 +508,16 @@ export const serveOAuthTestServer = (
               ? `secret_${randomUUID()}`
               : null;
           const redirectUris = new Set(arrayOfStrings(json.redirect_uris));
+          if (
+            options.approveRedirectUri &&
+            [...redirectUris].some((uri) => !options.approveRedirectUri!(uri))
+          ) {
+            return oauthError(
+              400,
+              "invalid_redirect_uri",
+              "The provided redirect URIs are not approved for use by this authorization server.",
+            );
+          }
           clients.set(clientId, {
             clientSecret,
             redirectUris,
diff --git a/packages/react/src/components/add-account-modal.test.ts b/packages/react/src/components/add-account-modal.test.ts
@@ -429,4 +429,47 @@ describe("runDcrConnect", () => {
     });
     expect(calls).toEqual(["register"]);
   });
+
+  it("threads the register failure message into the fallback (registration-failed)", async () => {
+    const message =
+      "Automatic OAuth setup failed: this server only approves loopback redirect URLs " +
+      "(http://localhost or http://127.0.0.1) for automatic registration, but Executor is " +
+      "using https://app.example.com/api/oauth/callback. Register an OAuth app manually with " +
+      "that redirect URL approved by the server, or run Executor on http://localhost.";
+    let started = false;
+    const outcome = await runDcrConnect(
+      {
+        probe: (): Promise<ProbeResult | null> =>
+          Promise.resolve({
+            authorizationUrl: "https://auth.example.com/authorize",
+            tokenUrl: "https://auth.example.com/token",
+            registrationEndpoint: "https://auth.example.com/register",
+          }),
+        register: (): Promise<{ readonly error: string }> => Promise.resolve({ error: message }),
+        start: (): void => {
+          started = true;
+        },
+      },
+      {
+        discoveryUrl: "https://mcp.example.com/mcp",
+        owner: "user",
+        integrationName: "App",
+        existingSlugs: [],
+        integration: TEST_INTEGRATION,
+      },
+    );
+    // The redirect-URI rejection reaches the caller verbatim so the BYO fallback
+    // can show why instead of the generic copy, and the OAuth start is skipped.
+    expect(outcome).toEqual({
+      kind: "fallback",
+      reason: "registration-failed",
+      probe: {
+        authorizationUrl: "https://auth.example.com/authorize",
+        tokenUrl: "https://auth.example.com/token",
+        registrationEndpoint: "https://auth.example.com/register",
+      },
+      message,
+    });
+    expect(started).toBe(false);
+  });
 });
diff --git a/packages/react/src/components/add-account-modal.tsx b/packages/react/src/components/add-account-modal.tsx
@@ -514,14 +514,22 @@ type DcrOutcome =
       readonly kind: "fallback";
       readonly reason: "no-registration-endpoint" | "registration-failed";
       readonly probe: DcrProbeResult;
+      /** A specific, user-facing reason to surface instead of the generic
+       *  "register an app" copy (e.g. a server that rejects the DCR redirect
+       *  URI). Absent when the fallback carries no actionable detail. */
+      readonly message?: string;
     };
 
 type RunDcrConnectDeps = {
   /** Probe the discovery URL → resolved endpoints + (maybe) a registration
    *  endpoint. Resolves to null when the probe fails. */
   readonly probe: (url: string) => Promise<DcrProbeResult | null>;
-  /** Register a DCR client → the minted client slug, or null on failure. */
-  readonly register: (args: DcrRegisterArgs) => Promise<OAuthClientSlug | null>;
+  /** Register a DCR client → the minted client slug, `{ error }` with a
+   *  user-facing message when the server rejects registration, or null on an
+   *  unexplained failure. */
+  readonly register: (
+    args: DcrRegisterArgs,
+  ) => Promise<OAuthClientSlug | { readonly error: string } | null>;
   /** Start the OAuth flow with the minted client (popup / inline). */
   readonly start: (args: DcrStartArgs) => void;
 };
@@ -557,7 +565,9 @@ export const dcrClientNameForIntegration = (integrationName: string): string =>
  *
  * - Probe failure → `{ kind: "fallback", reason: "probe-failed" }` (caller shows BYO).
  * - No registration endpoint → `{ kind: "fallback", reason: "no-registration-endpoint", probe }`.
- * - Registration failure → `{ kind: "fallback", reason: "registration-failed", probe }`.
+ * - Register rejected with a message → `{ kind: "fallback", reason: "registration-failed", probe, message }`
+ *   so the caller can show why (e.g. a redirect-URI rejection) over the generic copy.
+ * - Register failed without detail (null) → `{ kind: "fallback", reason: "registration-failed", probe }`.
  * - Success → registers, calls `start`, returns `{ kind: "started" }`.
  */
 export async function runDcrConnect(
@@ -585,6 +595,11 @@ export async function runDcrConnect(
     originIntegration: input.integration,
   });
   if (minted === null) return { kind: "fallback", reason: "registration-failed", probe };
+  // OAuthClientSlug is a branded string; an object return carries the failure
+  // message (e.g. the server rejected the redirect URI) for the BYO fallback.
+  if (typeof minted === "object") {
+    return { kind: "fallback", reason: "registration-failed", probe, message: minted.error };
+  }
   deps.start({ client: minted, owner: input.owner });
   return { kind: "started" };
 }
@@ -1179,7 +1194,9 @@ function AddAccountModalView(props: AddAccountModalProps) {
           if (Exit.isFailure(exit)) return null;
           return exit.value;
         },
-        register: async (args: DcrRegisterArgs): Promise<OAuthClientSlug | null> => {
+        register: async (
+          args: DcrRegisterArgs,
+        ): Promise<OAuthClientSlug | { readonly error: string } | null> => {
           const exit = await doRegisterDynamic({
             payload: {
               owner: args.owner,
@@ -1196,7 +1213,11 @@ function AddAccountModalView(props: AddAccountModalProps) {
             },
             reactivityKeys: oauthClientWriteKeys,
           });
-          if (Exit.isFailure(exit)) return null;
+          if (Exit.isFailure(exit)) {
+            return {
+              error: messageFromExit(exit, "Automatic setup unavailable. Register an app instead."),
+            };
+          }
           return exit.value.client;
         },
         start: (args: DcrStartArgs): void => {
@@ -1246,7 +1267,10 @@ function AddAccountModalView(props: AddAccountModalProps) {
     if (outcome.kind === "fallback") {
       setOAuthFallbackProbe("probe" in outcome ? outcome.probe : null);
       setDcrFailed(true);
-      toast.error("Automatic setup unavailable — register an app");
+      toast.error(
+        ("message" in outcome ? outcome.message : undefined) ??
+          "Automatic setup unavailable. Register an app instead.",
+      );
     }
   };
 

Original file line number	Diff line number	Diff line change
`@@ -61,7 +61,7 @@ export interface OAuthEndpointUrlPolicy {`
`61`	`61`	`readonly allowHttp?: boolean;`
`62`	`62`	`}`
`63`	`63`
`64`		`-const isLoopbackHttpUrl = (value: string): boolean => {`
	`64`	`+export const isLoopbackHttpUrl = (value: string): boolean => {`
`65`	`65`	`if (!URL.canParse(value)) return false;`
`66`	`66`	`const url = new URL(value);`
`67`	`67`	`if (url.protocol !== "http:") return false;`