@cursor/july 0.1.95 → 0.1.97

package/src/internal/mcp-host.ts

@@ -26,6 +26,47 @@ import type {
 import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
 import { createHostMcpOAuthProvider } from "./mcp-oauth.js";
 
+export class McpNeedsAuthError extends Error {
+  readonly connection: string;
+
+  constructor(connection: string, cause?: unknown) {
+    super(
+      `MCP connection "${connection}" needs authorization. Run \`${CLI} mcp oauth ${connection}\`.`
+    );
+    this.name = "McpNeedsAuthError";
+    this.connection = connection;
+    if (cause !== undefined) {
+      this.cause = cause;
+    }
+  }
+}
+
+export function isMcpNeedsAuthError(
+  error: unknown
+): error is McpNeedsAuthError {
+  return error instanceof McpNeedsAuthError;
+}
+
+export function hostMcpCallNeedsAuth(result: HostMcpCallResult): boolean {
+  if (result.isError !== true) {
+    return false;
+  }
+  const text = result.content
+    .map((part) => (part.type === "text" ? part.text : ""))
+    .join("\n");
+  return text.includes("needsAuth") || text.includes("needs authorization");
+}
+
+function throwIfCallNeedsAuth(
+  connection: string,
+  result: HostMcpCallResult
+): HostMcpCallResult {
+  if (hostMcpCallNeedsAuth(result)) {
+    throw new McpNeedsAuthError(connection);
+  }
+  return result;
+}
+
 interface OpenedConnection {
   client: Client;
   close: () => Promise<void>;
@@ -46,6 +87,7 @@ export interface HostMcpOneOff {
 export class McpHost implements HostMcpRegistry {
   private readonly byName = new Map<string, DiscoveredConnection>();
   private readonly clients = new Map<string, Promise<OpenedConnection>>();
+  private oauthRedirectUrl: string | undefined;
 
   constructor(connections: DiscoveredConnection[]) {
     for (const connection of connections) {
@@ -53,6 +95,11 @@ export class McpHost implements HostMcpRegistry {
     }
   }
 
+  /** Public serve callback for host OAuth (not the CLI loopback port on pods). */
+  setOAuthRedirectUrl(url: string): void {
+    this.oauthRedirectUrl = url;
+  }
+
   /**
    * Register a connection after construction (serve-time resolved peers).
    * Clients open lazily on first use, so adding before first call is safe.
@@ -82,10 +129,11 @@ export class McpHost implements HostMcpRegistry {
    * mapping as registry calls.
    */
   oneOff(connection: DiscoveredConnection): HostMcpOneOff {
+    const redirectUrl = this.oauthRedirectUrl;
     const withFreshClient = async <T>(
       run: (client: Client) => Promise<T>
     ): Promise<T> => {
-      const opened = await openConnection(connection);
+      const opened = await openConnection(connection, redirectUrl);
       try {
         return await run(opened.client);
       } finally {
@@ -104,7 +152,10 @@ export class McpHost implements HostMcpRegistry {
             name: toolName,
             arguments: args,
           });
-          return normalizeCallResult(result);
+          return throwIfCallNeedsAuth(
+            connection.name,
+            normalizeCallResult(result)
+          );
         }),
     };
   }
@@ -119,10 +170,23 @@ export class McpHost implements HostMcpRegistry {
         name: toolName,
         arguments: args,
       });
-      return normalizeCallResult(result);
+      return throwIfCallNeedsAuth(connectionName, normalizeCallResult(result));
     });
   }
 
+  async dropClient(name: string): Promise<void> {
+    const pending = this.clients.get(name);
+    this.clients.delete(name);
+    if (pending === undefined) {
+      return;
+    }
+    try {
+      await (await pending).close();
+    } catch {
+      // Best-effort teardown.
+    }
+  }
+
   async close(): Promise<void> {
     const opened = await Promise.allSettled([...this.clients.values()]);
     this.clients.clear();
@@ -198,7 +262,7 @@ export class McpHost implements HostMcpRegistry {
         `Unknown MCP connection "${name}". Authored MCP connections: ${known}.`
       );
     }
-    return openConnection(connection);
+    return openConnection(connection, this.oauthRedirectUrl);
   }
 }
 
@@ -283,13 +347,14 @@ function toToolInfo(tool: {
 }
 
 async function openConnection(
-  connection: DiscoveredConnection
+  connection: DiscoveredConnection,
+  oauthRedirectUrl?: string
 ): Promise<OpenedConnection> {
   const client = new Client({
     name: "agent-serve",
     version: "0.1.0",
   });
-  const transport = await createTransport(connection);
+  const transport = await createTransport(connection, oauthRedirectUrl);
   try {
     await client.connect(transport);
   } catch (error) {
@@ -297,10 +362,7 @@ async function openConnection(
       error instanceof UnauthorizedError &&
       isOauthHttpTransport(connection.transport)
     ) {
-      throw new Error(
-        `MCP connection "${connection.name}" needs authorization. Run \`${CLI} mcp oauth ${connection.name}\`.`,
-        { cause: error }
-      );
+      throw new McpNeedsAuthError(connection.name, error);
     }
     throw error;
   }
@@ -322,7 +384,10 @@ async function openConnection(
   };
 }
 
-async function createTransport(connection: DiscoveredConnection) {
+async function createTransport(
+  connection: DiscoveredConnection,
+  oauthRedirectUrl?: string
+) {
   const transport = connection.transport;
   if ("agent" in transport) {
     // Peers are resolved to concrete URLs by the serve host before any call
@@ -365,6 +430,7 @@ async function createTransport(connection: DiscoveredConnection) {
       ? await createHostMcpOAuthProvider({
           identifier: connection.name,
           resourceUrl: transport.url,
+          redirectUrl: oauthRedirectUrl,
         })
       : undefined;
 

package/src/internal/mcp-oauth-on-demand.ts

@@ -0,0 +1,352 @@
+/**
+ * Mid-run host MCP OAuth: mint an authUrl, finish on the public serve
+ * callback (file tokens). Deployment secrets persist from the
+ * authenticated park, not from that callback.
+ *
+ * CLI `mcp oauth` still uses the loopback callback. This path is recovery
+ * and first-use without a separate `--store` step.
+ */
+
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { describeError } from "./describe-error.js";
+import { LOG_PREFIX } from "./distribution.js";
+import {
+  createHostMcpOAuthProvider,
+  FileMcpOAuthStore,
+  MCP_OAUTH_CALLBACK_URL,
+} from "./mcp-oauth.js";
+import {
+  type McpOauthSecretsTarget,
+  type ResolveHostedMcpOauthSecretsArgs,
+  resolveHostedMcpOauthSecretsTarget,
+  upsertHostMcpOauthSecrets,
+} from "./mcp-oauth-persist.js";
+
+export function mcpOauthServeCallbackPath(basePath = ""): string {
+  return `${basePath}/v1/mcp-oauth/callback`;
+}
+
+export function mcpOauthServeCallbackUrl(
+  origin: string,
+  basePath = ""
+): string {
+  return `${origin.replace(/\/$/, "")}${mcpOauthServeCallbackPath(basePath)}`;
+}
+
+export type BeginHostMcpOauthResult =
+  | { status: "authorized" }
+  | {
+      status: "needs_auth";
+      authUrl: string;
+      state: string;
+      finish: (code: string) => Promise<void>;
+      abort: () => Promise<void>;
+    };
+
+export async function beginHostMcpOauth(args: {
+  connection: string;
+  url: string;
+  type?: "http" | "sse";
+  headers?: Record<string, string>;
+  redirectUrl: string;
+  store?: FileMcpOAuthStore;
+}): Promise<BeginHostMcpOauthResult> {
+  let authorizationUrl: URL | undefined;
+  const provider = await createHostMcpOAuthProvider({
+    identifier: args.connection,
+    resourceUrl: args.url,
+    store: args.store,
+    redirectUrl: args.redirectUrl,
+    onRedirect: (url) => {
+      authorizationUrl = url;
+    },
+  });
+
+  const client = new Client({ name: "agent-sdk-mcp-oauth", version: "0.1.0" });
+  const url = new URL(args.url);
+  const requestInit =
+    args.headers === undefined ? undefined : { headers: args.headers };
+
+  const makeTransport = ():
+    | StreamableHTTPClientTransport
+    | SSEClientTransport => {
+    if (args.type === "sse") {
+      return new SSEClientTransport(url, {
+        authProvider: provider,
+        requestInit,
+      });
+    }
+    return new StreamableHTTPClientTransport(url, {
+      authProvider: provider,
+      requestInit,
+    });
+  };
+
+  const transport = makeTransport();
+  try {
+    await client.connect(transport);
+    await client.close().catch(() => undefined);
+    return { status: "authorized" };
+  } catch (error) {
+    if (!(error instanceof UnauthorizedError)) {
+      throw error;
+    }
+  }
+
+  const redirect = authorizationUrl ?? provider.lastRedirectUrl;
+  if (redirect === undefined) {
+    throw new Error(
+      `Auth required for "${args.connection}" but no authorization URL was provided.`
+    );
+  }
+  const state = redirect.searchParams.get("state") ?? "";
+  if (state === "") {
+    throw new Error(
+      `Auth required for "${args.connection}" but the authorization URL had no state.`
+    );
+  }
+
+  return {
+    status: "needs_auth",
+    authUrl: redirect.toString(),
+    state,
+    finish: async (code: string) => {
+      await transport.finishAuth(code);
+      await transport.close?.().catch(() => undefined);
+    },
+    abort: async () => {
+      await transport.close?.().catch(() => undefined);
+    },
+  };
+}
+
+type BoundAttempt = {
+  connection: string;
+  resourceUrl: string;
+  finish: (code: string) => Promise<void>;
+  abort: () => Promise<void>;
+  sessionId?: string;
+  callId?: string;
+};
+
+export type McpOauthCompleteResult = {
+  connection: string;
+  sessionId?: string;
+  callId?: string;
+};
+
+export class McpOauthOnDemandHub {
+  private readonly attempts = new Map<string, BoundAttempt>();
+  private readonly completed = new Map<string, BoundAttempt>();
+  private readonly finishing = new Map<
+    string,
+    Promise<McpOauthCompleteResult>
+  >();
+  private readonly aborted = new Set<string>();
+  callbackUrl: string | undefined;
+  secrets?: McpOauthSecretsTarget;
+  // Identity only — resolve the key at persist, after freeze bind.
+  secretsBind?: ResolveHostedMcpOauthSecretsArgs;
+  logger?: (line: string) => void;
+  private store?: FileMcpOAuthStore;
+
+  async mint(args: {
+    connection: string;
+    url: string;
+    type?: "http" | "sse";
+    headers?: Record<string, string>;
+    sessionId?: string;
+  }): Promise<{ authUrl: string; state: string } | { authorized: true }> {
+    const redirectUrl = this.callbackUrl ?? MCP_OAUTH_CALLBACK_URL;
+    const store = this.fileStore();
+    const started = await beginHostMcpOauth({
+      connection: args.connection,
+      url: args.url,
+      type: args.type,
+      headers: args.headers,
+      redirectUrl,
+      store,
+    });
+    if (started.status === "authorized") {
+      return { authorized: true };
+    }
+    this.attempts.set(started.state, {
+      connection: args.connection,
+      resourceUrl: args.url,
+      finish: started.finish,
+      abort: started.abort,
+      sessionId: args.sessionId,
+    });
+    return { authUrl: started.authUrl, state: started.state };
+  }
+
+  async abortCall(sessionId: string, callId: string): Promise<void> {
+    await this.dropWhere(
+      (attempt) => attempt.sessionId === sessionId && attempt.callId === callId,
+      true
+    );
+  }
+
+  async abortSession(sessionId: string): Promise<void> {
+    await this.dropWhere((attempt) => attempt.sessionId === sessionId, false);
+  }
+
+  async close(): Promise<void> {
+    await this.dropWhere(() => true, true);
+  }
+
+  private async dropWhere(
+    match: (attempt: BoundAttempt) => boolean,
+    includeCompleted: boolean
+  ): Promise<void> {
+    const jobs: Array<Promise<void>> = [];
+    for (const [state, attempt] of this.attempts) {
+      if (!match(attempt)) {
+        continue;
+      }
+      this.aborted.add(state);
+      this.attempts.delete(state);
+      jobs.push(attempt.abort().catch(() => undefined));
+    }
+    if (includeCompleted) {
+      for (const [state, attempt] of this.completed) {
+        if (!match(attempt)) {
+          continue;
+        }
+        this.aborted.add(state);
+        this.completed.delete(state);
+      }
+    }
+    await Promise.all(jobs);
+  }
+
+  bind(
+    state: string,
+    sessionId: string,
+    callId: string
+  ): "pending" | "already_done" | "unknown" {
+    const live = this.attempts.get(state);
+    if (live !== undefined) {
+      live.sessionId = sessionId;
+      live.callId = callId;
+      return "pending";
+    }
+    const done = this.completed.get(state);
+    if (done !== undefined) {
+      done.sessionId = sessionId;
+      done.callId = callId;
+      return "already_done";
+    }
+    return "unknown";
+  }
+
+  async complete(state: string, code: string): Promise<McpOauthCompleteResult> {
+    if (this.aborted.has(state)) {
+      throw new Error("Unknown OAuth state.");
+    }
+    const pending = this.finishing.get(state);
+    if (pending !== undefined) {
+      return await pending;
+    }
+    const attempt = this.attempts.get(state);
+    if (attempt === undefined) {
+      throw new Error("Unknown OAuth state.");
+    }
+    const run = this.finishAttempt(state, attempt, code);
+    this.finishing.set(state, run);
+    return await run;
+  }
+
+  private async finishAttempt(
+    state: string,
+    attempt: BoundAttempt,
+    code: string
+  ): Promise<McpOauthCompleteResult> {
+    try {
+      await attempt.finish(code);
+      this.attempts.delete(state);
+      if (!this.aborted.has(state)) {
+        this.completed.set(state, attempt);
+      }
+      return {
+        connection: attempt.connection,
+        sessionId: attempt.sessionId,
+        callId: attempt.callId,
+      };
+    } finally {
+      this.finishing.delete(state);
+    }
+  }
+
+  private fileStore(): FileMcpOAuthStore {
+    this.store ??= new FileMcpOAuthStore();
+    return this.store;
+  }
+
+  async persistFor(connection: string, resourceUrl: string): Promise<void> {
+    const target =
+      this.secrets ??
+      resolveHostedMcpOauthSecretsTarget(this.secretsBind ?? {});
+    if (target === undefined) {
+      return;
+    }
+    const store = this.fileStore();
+    const tokens = await store.loadTokens(connection, resourceUrl);
+    if (tokens === undefined || tokens.access_token.trim() === "") {
+      return;
+    }
+    const client = await store.loadClientInformation(connection, resourceUrl);
+    try {
+      const names = await upsertHostMcpOauthSecrets({
+        connection,
+        tokens,
+        clientId: client?.client_id,
+        target,
+      });
+      this.logger?.(
+        `${LOG_PREFIX} MCP OAuth tokens stored on the deployment (${names.join(", ")}).`
+      );
+    } catch (error) {
+      this.logger?.(
+        `${LOG_PREFIX} MCP OAuth persist failed for "${connection}": ${describeError(error)}`
+      );
+    }
+  }
+
+  async handleCallback(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state") ?? "";
+    if (this.aborted.has(state)) {
+      return oauthHtml(404, "<h1>Not found</h1>");
+    }
+    if (this.completed.has(state)) {
+      return oauthHtml(200, "<h1>Authorized</h1><p>Return to the agent.</p>");
+    }
+    if (!this.attempts.has(state)) {
+      return oauthHtml(404, "<h1>Not found</h1>");
+    }
+    if (code !== null && code !== "") {
+      try {
+        await this.complete(state, code);
+      } catch {
+        return oauthHtml(400, "<h1>Authorization failed</h1>");
+      }
+      if (this.aborted.has(state)) {
+        return oauthHtml(404, "<h1>Not found</h1>");
+      }
+      return oauthHtml(200, "<h1>Authorized</h1><p>Return to the agent.</p>");
+    }
+    return oauthHtml(400, "<h1>Authorization failed</h1>");
+  }
+}
+
+function oauthHtml(status: number, body: string): Response {
+  return new Response(`<!doctype html><html><body>${body}</body></html>`, {
+    status,
+    headers: { "content-type": "text/html; charset=utf-8" },
+  });
+}

package/src/internal/mcp-oauth-persist.ts

@@ -0,0 +1,127 @@
+/**
+ * Deployment-secret upsert for host MCP OAuth (`mcp oauth --store` and
+ * hosted Connect). File writes stay on FileMcpOAuthStore / the OAuth
+ * provider. Resolve the `--store` client at persist time so v2 freeze
+ * bind can drop the key after listen.
+ */
+
+import type { OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import { AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR } from "../storage-backends/cursor-hosted.js";
+import {
+  cursorExternalApiUrl,
+  resolveApiKeySync,
+} from "./cursor/credentials.js";
+import {
+  AgentServeDeployClient,
+  parseAgentServeMcpGatewayUrl,
+} from "./deploy-client.js";
+import { mcpOauthSecretNames } from "./mcp-oauth.js";
+
+export type McpOauthSecretsClient = {
+  setSecrets(args: {
+    teamId: number;
+    slug: string;
+    secrets: Array<{ name: string; value: string }>;
+  }): Promise<string[]>;
+};
+
+export type McpOauthSecretsTarget = {
+  client: McpOauthSecretsClient;
+  teamId: number;
+  slug: string;
+};
+
+function mcpOauthSecretsPayload(args: {
+  connection: string;
+  tokens: OAuthTokens;
+  clientId?: string;
+}): Array<{ name: string; value: string }> {
+  const names = mcpOauthSecretNames(args.connection);
+  const secrets: Array<{ name: string; value: string }> = [
+    { name: names.accessToken, value: args.tokens.access_token },
+  ];
+  const refresh = args.tokens.refresh_token?.trim();
+  if (refresh !== undefined && refresh !== "") {
+    secrets.push({ name: names.refreshToken, value: refresh });
+  }
+  const clientId = args.clientId?.trim();
+  if (clientId !== undefined && clientId !== "") {
+    secrets.push({ name: names.clientId, value: clientId });
+  }
+  return secrets;
+}
+
+export async function upsertHostMcpOauthSecrets(args: {
+  connection: string;
+  tokens: OAuthTokens;
+  clientId?: string;
+  target: McpOauthSecretsTarget;
+}): Promise<string[]> {
+  const payload = mcpOauthSecretsPayload(args);
+  if (payload.length === 0) {
+    return [];
+  }
+  return await args.target.client.setSecrets({
+    teamId: args.target.teamId,
+    slug: args.target.slug,
+    secrets: payload,
+  });
+}
+
+export type ResolveHostedMcpOauthSecretsArgs = {
+  slug?: string;
+  team?: string;
+  apiKey?: string;
+  cloudToolsUrl?: string;
+  env?: NodeJS.ProcessEnv;
+};
+
+/**
+ * Bind the CLI `--store` client when this process is a hosted engine
+ * (`AGENT_SERVE_DEPLOYMENT_ID`) and a live API key is present.
+ * Self-hosted / no deployment / unsigned: undefined.
+ */
+export function resolveHostedMcpOauthSecretsTarget(
+  args: ResolveHostedMcpOauthSecretsArgs = {}
+): McpOauthSecretsTarget | undefined {
+  const env = args.env ?? process.env;
+  const deploymentId = env[AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR]?.trim();
+  if (deploymentId === undefined || deploymentId === "") {
+    return undefined;
+  }
+  const resolved = resolveApiKeySync(
+    args.apiKey === undefined ? undefined : { apiKey: args.apiKey }
+  );
+  if (resolved === undefined) {
+    return undefined;
+  }
+  const fromUrl =
+    args.cloudToolsUrl === undefined
+      ? undefined
+      : parseAgentServeMcpGatewayUrl(args.cloudToolsUrl);
+  const slug =
+    args.slug !== undefined && args.slug !== "" ? args.slug : fromUrl?.slug;
+  const teamId = parseTeamId(args.team) ?? fromUrl?.teamId;
+  if (slug === undefined || teamId === undefined) {
+    return undefined;
+  }
+  return {
+    client: new AgentServeDeployClient({
+      backendUrl: cursorExternalApiUrl(),
+      apiKey: resolved.apiKey,
+    }),
+    teamId,
+    slug,
+  };
+}
+
+function parseTeamId(team: string | undefined): number | undefined {
+  if (team === undefined || team === "") {
+    return undefined;
+  }
+  const teamId = Number.parseInt(team, 10);
+  if (!Number.isInteger(teamId) || teamId <= 0) {
+    return undefined;
+  }
+  return teamId;
+}

package/src/internal/mcp-oauth.ts

@@ -411,13 +411,25 @@ export class HostMcpOAuthProvider implements OAuthClientProvider {
   }
 }
 
+function clientForRedirect(
+  info: OAuthClientInformationFull | undefined,
+  redirectUrl: string
+): OAuthClientInformationFull | undefined {
+  if (info === undefined || !info.redirect_uris.includes(redirectUrl)) {
+    return undefined;
+  }
+  return info;
+}
+
 export async function createHostMcpOAuthProvider(args: {
   identifier: string;
   resourceUrl: string;
   store?: FileMcpOAuthStore;
   onRedirect?: (url: URL) => void;
+  redirectUrl?: string;
 }): Promise<HostMcpOAuthProvider> {
   const store = args.store ?? new FileMcpOAuthStore();
+  const redirectUrl = args.redirectUrl ?? MCP_OAUTH_CALLBACK_URL;
   const [fileTokens, fileClient, omitResourceIndicator] = await Promise.all([
     store.loadTokens(args.identifier, args.resourceUrl),
     store.loadClientInformation(args.identifier, args.resourceUrl),
@@ -427,8 +439,12 @@ export async function createHostMcpOAuthProvider(args: {
     identifier: args.identifier,
     resourceUrl: args.resourceUrl,
     store,
+    redirectUrl,
     tokens: fileTokens ?? tokensFromEnv(args.identifier),
-    clientInformation: fileClient ?? clientIdFromEnv(args.identifier),
+    clientInformation: clientForRedirect(
+      fileClient ?? clientIdFromEnv(args.identifier),
+      redirectUrl
+    ),
     onRedirect: args.onRedirect,
     omitResourceIndicator,
   });