feat(cursor): add an optional Cursor team id

A Cursor account can belong to several teams. T3 Code sent no team, so runs always billed the
account's default team, with no way to choose another (#16840).

@cursor/sdk 1.2.0 accepts a team id. Bump it and add an optional `CURSOR_TEAM_ID` provider setting
that applies to browser sign-in and to `CURSOR_API_KEY`. Agent runs, text generation, and the model
catalog use the team, and the provider status publishes its id so usage limits group by team.
Without the setting, nothing changes.

Validation: `vp run check:changed` passes, with tests for `CURSOR_TEAM_ID` parsing and scoping, the
catalog team header and per-team cache, and the status.

Model: Claude Opus 5.5. Harness: Cursor.
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: alex-pex

apps/server/package.json

@@ -34,7 +34,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.276",
-    "@cursor/sdk": "1.0.38",
+    "@cursor/sdk": "1.2.0",
     "@effect/platform-node": "catalog:",
     "@effect/platform-node-shared": "catalog:",
     "@ff-labs/fff-node": "0.11.0",

docs/user/cursor.md

@@ -21,6 +21,9 @@ Choose **Sign in**, then open the sign-in page and complete it in your browser.
 updates automatically when sign-in finishes. This works when connected to a remote environment too.
 On mobile, use **Settings > Providers** for an already configured Cursor instance.
 
+If your Cursor account belongs to several teams, runs use the account's default team. To use another
+team, enter its id in **Team ID**. It applies to browser sign-in and to `CURSOR_API_KEY`.
+
 Each provider instance keeps its own login on the environment that runs it. Your Cursor editor and
 CLI login are separate. A configured `CURSOR_API_KEY` overrides browser sign-in; remove that override
 to use the browser flow.

packages/provider-cursor/package.json

@@ -49,7 +49,7 @@
     "test": "vp test run --config ../../vite.config.ts --dir ."
   },
   "dependencies": {
-    "@cursor/sdk": "1.0.38",
+    "@cursor/sdk": "1.2.0",
     "@napi-rs/keyring": "^1.3.0",
     "@t3tools/contracts": "workspace:*",
     "@t3tools/provider-core": "workspace:*",

packages/provider-cursor/src/client.ts

@@ -17,6 +17,12 @@ export const cursorClient = defineProviderClient({
       placeholder: "Paste API key",
       sensitive: true,
     },
+    {
+      name: "CURSOR_TEAM_ID",
+      label: "Team ID",
+      description: "Optional. Leave empty for the account's default team.",
+      sensitive: false,
+    },
   ],
   icon: {
     viewBox: "0 0 466.73 532.09",

packages/provider-cursor/src/server/CursorSdkCatalog.test.ts

@@ -82,6 +82,7 @@ describe("CursorSdkCatalog", () => {
         ];
         const client = HttpClient.make((request) => {
           expect(request.headers.authorization).toBe("Bearer test-key");
+          expect(request.headers["x-cursor-team-id"]).toBe("42");
           expect(request.method).toBe("GET");
           requests.push(request.url);
           const matches = request.url === `https://api.cursor.com/v1/${route}`;
@@ -104,7 +105,7 @@ describe("CursorSdkCatalog", () => {
           ),
         );
         expect(sdkLoad).not.toHaveBeenCalled();
-        const result = yield* catalog.read("test-key").pipe(Effect.exit);
+        const result = yield* catalog.read("test-key", 42).pipe(Effect.exit);
         expect(requests).toContain(`https://api.cursor.com/v1/${route}`);
         if (expected === "ready" || expected === "no-user") {
           expect(Exit.isSuccess(result)).toBe(true);
@@ -159,7 +160,7 @@ describe("CursorSdkCatalog", () => {
     }),
   );
 
-  it.effect("does not cache failed or empty model discovery", () =>
+  it.effect("does not cache failed or empty model discovery, nor across teams", () =>
     Effect.gen(function* () {
       let modelCalls = 0;
       const catalog = yield* CursorSdkCatalog.makeCursorSdkCatalog({
@@ -178,6 +179,8 @@ describe("CursorSdkCatalog", () => {
       expect((yield* catalog.read("test-key")).models).toEqual([model]);
       expect((yield* catalog.read("test-key")).models).toEqual([model]);
       expect(modelCalls).toBe(3);
+      yield* catalog.read("test-key", 42);
+      expect(modelCalls).toBe(4);
     }),
   );
 });

packages/provider-cursor/src/server/CursorSdkCatalog.ts

@@ -6,6 +6,7 @@ import * as HttpClient from "effect/http/HttpClient";
 import * as HttpClientRequest from "effect/http/HttpClientRequest";
 import * as HttpClientResponse from "effect/http/HttpClientResponse";
 import * as Context from "effect/Context";
+import * as Data from "effect/Data";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
@@ -46,14 +47,19 @@ export class CursorSdkCatalog extends Context.Service<
   {
     readonly read: (
       apiKey: string,
+      teamId?: number,
     ) => Effect.Effect<CursorSdkCatalogSnapshot, CursorSdkCatalogError>;
   }
 >()("@t3tools/provider-cursor/server/CursorSdkCatalog") {}
 
 export interface CursorSdkCatalogProbes {
-  readonly readUser: (apiKey: string) => Effect.Effect<SDKUser, CursorSdkCatalogError>;
+  readonly readUser: (
+    apiKey: string,
+    teamId?: number,
+  ) => Effect.Effect<SDKUser, CursorSdkCatalogError>;
   readonly readModels: (
     apiKey: string,
+    teamId?: number,
   ) => Effect.Effect<ReadonlyArray<SDKModel>, CursorSdkCatalogError>;
 }
 
@@ -111,10 +117,17 @@ const makeLiveProbes = Effect.gen(function* () {
     Config.withDefault("https://api.cursor.com"),
     Effect.orDie,
   )).replace(/\/$/, "");
-  const request = Effect.fn("CursorSdkCatalog.request")(function* (apiKey: string, path: string) {
+  const request = Effect.fn("CursorSdkCatalog.request")(function* (
+    apiKey: string,
+    path: string,
+    teamId: number | undefined,
+  ) {
     const response = yield* client
       .execute(
-        HttpClientRequest.get(`${baseUrl}${path}`).pipe(HttpClientRequest.bearerToken(apiKey)),
+        HttpClientRequest.get(`${baseUrl}${path}`).pipe(
+          HttpClientRequest.bearerToken(apiKey),
+          HttpClientRequest.setHeaders(teamId ? { "x-cursor-team-id": String(teamId) } : {}),
+        ),
       )
       .pipe(
         Effect.mapError(
@@ -136,17 +149,17 @@ const makeLiveProbes = Effect.gen(function* () {
     return response;
   });
   return {
-    readUser: (apiKey) =>
-      request(apiKey, "/v1/me").pipe(
+    readUser: (apiKey, teamId) =>
+      request(apiKey, "/v1/me", teamId).pipe(
         Effect.flatMap(HttpClientResponse.schemaBodyJson(CatalogUser)),
         Effect.mapError((cause) =>
           isCatalogError(cause)
             ? cause
             : new CursorSdkCatalogError({ authenticationFailure: false, cause }),
         ),
       ),
-    readModels: (apiKey) =>
-      request(apiKey, "/v1/models").pipe(
+    readModels: (apiKey, teamId) =>
+      request(apiKey, "/v1/models", teamId).pipe(
         Effect.flatMap(HttpClientResponse.schemaBodyJson(CatalogModels)),
         Effect.map((body) => body.items),
         Effect.mapError((cause) =>
@@ -158,26 +171,34 @@ const makeLiveProbes = Effect.gen(function* () {
   } satisfies CursorSdkCatalogProbes;
 });
 
+class ModelCacheKey extends Data.Class<{
+  readonly apiKey: string;
+  readonly teamId: number | undefined;
+}> {}
+
 export const makeCursorSdkCatalog = Effect.fn("CursorSdkCatalog.make")(function* (
   probes: CursorSdkCatalogProbes,
 ) {
-  const modelCache = yield* Cache.makeWith(probes.readModels, {
-    capacity: 32,
-    timeToLive: (exit) =>
-      Exit.isSuccess(exit) && exit.value.length > 0 ? Duration.minutes(30) : Duration.zero,
-  });
+  const modelCache = yield* Cache.makeWith(
+    (key: ModelCacheKey) => probes.readModels(key.apiKey, key.teamId),
+    {
+      capacity: 32,
+      timeToLive: (exit) =>
+        Exit.isSuccess(exit) && exit.value.length > 0 ? Duration.minutes(30) : Duration.zero,
+    },
+  );
   return CursorSdkCatalog.of({
-    read: Effect.fn("CursorSdkCatalog.read")(function (apiKey) {
+    read: Effect.fn("CursorSdkCatalog.read")(function (apiKey, teamId) {
       return Effect.all(
         {
           // Enterprise teams can block account labels while model discovery still works.
           user: Effect.catchIf(
-            probes.readUser(apiKey),
+            probes.readUser(apiKey, teamId),
             (error: CursorSdkCatalogError): boolean => error.accountBlocked,
             () => Effect.undefined,
             (error: CursorSdkCatalogError) => Effect.fail(error),
           ),
-          models: Cache.get(modelCache, apiKey),
+          models: Cache.get(modelCache, new ModelCacheKey({ apiKey, teamId })),
         },
         { concurrency: "unbounded" },
       );

packages/provider-cursor/src/server/auth.test.ts

@@ -11,6 +11,7 @@ import * as Option from "effect/Option";
 import * as Stream from "effect/Stream";
 
 import { makeCursorAuth, type CursorAuthOptions } from "./auth.ts";
+import type { CursorTeam } from "./auth.ts";
 import { loadCursorSdk } from "./sdk.ts";
 
 const { InMemoryCredentialStore } = loadCursorSdk();
@@ -72,6 +73,8 @@ const makeHarness = Effect.fn("makeCursorAuthHarness")(function* (
 });
 
 type Auth = Effect.Success<ReturnType<typeof makeCursorAuth>>;
+const readApiKey = (auth: Auth) => Effect.map(auth.readAccess, (access) => access?.apiKey);
+const requireApiKey = (auth: Auth) => Effect.map(auth.requireAccess, (access) => access.apiKey);
 const phase = (auth: Auth, phase: ProviderAuthState["phase"], session = owner) =>
   auth.controller.subscribe(session).pipe(
     Stream.filter((state) => state.phase === phase),
@@ -112,15 +115,15 @@ it.layer(NodeServices.layer)("CursorAuth", (it) => {
       expect(closedSession).toBe(true);
       expect(closedRequest).toBe(true);
       expect(Exit.isFailure(yield* Fiber.await(request))).toBe(true);
-      expect(yield* harness.auth.readApiKey).toBeUndefined();
+      expect(yield* readApiKey(harness.auth)).toBeUndefined();
     }).pipe(Effect.scoped),
   );
 
   it.effect("completes a remote browser login, saves its key and refreshes provider status", () =>
     Effect.gen(function* () {
       const harness = yield* makeHarness();
       let stopped = false;
-      expect(yield* harness.auth.readApiKey).toBeUndefined();
+      expect(yield* readApiKey(harness.auth)).toBeUndefined();
       const starting = yield* harness.auth.controller.start(
         owner,
         Effect.sync(() => {
@@ -133,11 +136,11 @@ it.layer(NodeServices.layer)("CursorAuth", (it) => {
       expect(waiting.flowId).toBe(starting.flowId);
       expect(harness.loginOptions()?.openBrowser).toBe(false);
       expect((yield* harness.auth.controller.start(owner)).flowId).toBe(starting.flowId);
-      expect(Exit.isFailure(yield* Effect.exit(harness.auth.requireApiKey))).toBe(true);
+      expect(Exit.isFailure(yield* Effect.exit(requireApiKey(harness.auth)))).toBe(true);
       yield* Effect.sync(() => harness.complete.resolve());
       const succeeded = yield* phase(harness.auth, "succeeded");
       expect(succeeded.authorizationUrl).toBeNull();
-      expect(yield* harness.auth.requireApiKey).toBe("browser-key");
+      expect(yield* requireApiKey(harness.auth)).toBe("browser-key");
       expect(harness.changes).toEqual([true]);
       expect(Object.values(succeeded)).not.toContain("browser-key");
       expect(yield* Effect.promise(() => harness.store.load())).toEqual(harness.credentials);
@@ -180,7 +183,7 @@ it.layer(NodeServices.layer)("CursorAuth", (it) => {
       expect(harness.loginOptions()?.signal?.aborted).toBe(true);
       yield* Effect.sync(() => harness.complete.resolve());
       yield* Effect.promise(() => harness.returned.promise);
-      expect(yield* harness.auth.readApiKey).toBeUndefined();
+      expect(yield* readApiKey(harness.auth)).toBeUndefined();
       expect(harness.changes).toEqual([]);
     }).pipe(Effect.scoped),
   );
@@ -208,12 +211,12 @@ it.layer(NodeServices.layer)("CursorAuth", (it) => {
       const failed = yield* phase(harness.auth, "failed");
       expect(failed.message).toBe(rejectionMessage);
       expect(yield* Effect.promise(() => harness.store.load())).toBeUndefined();
-      expect(yield* harness.auth.readApiKey).toBeUndefined();
-      expect(Exit.isFailure(yield* Effect.exit(harness.auth.requireApiKey))).toBe(true);
+      expect(yield* readApiKey(harness.auth)).toBeUndefined();
+      expect(Exit.isFailure(yield* Effect.exit(requireApiKey(harness.auth)))).toBe(true);
       rejected = false;
       yield* harness.auth.controller.start(owner);
       yield* phase(harness.auth, "succeeded");
-      expect(yield* harness.auth.requireApiKey).toBe("browser-key");
+      expect(yield* requireApiKey(harness.auth)).toBe("browser-key");
     }).pipe(Effect.scoped),
   );
 
@@ -225,13 +228,13 @@ it.layer(NodeServices.layer)("CursorAuth", (it) => {
       yield* Effect.promise(() => other.store.save({ ...other.credentials, apiKey: "other-key" }));
       const state = yield* harness.auth.controller.logout(
         Effect.gen(function* () {
-          expect(yield* harness.auth.readApiKey).toBe("browser-key");
-          expect(Exit.isFailure(yield* Effect.exit(harness.auth.requireApiKey))).toBe(true);
+          expect(yield* readApiKey(harness.auth)).toBe("browser-key");
+          expect(Exit.isFailure(yield* Effect.exit(requireApiKey(harness.auth)))).toBe(true);
         }),
       );
       expect(state.message).toBe("Signed out of Cursor.");
-      expect(yield* harness.auth.readApiKey).toBeUndefined();
-      expect(yield* other.auth.requireApiKey).toBe("other-key");
+      expect(yield* readApiKey(harness.auth)).toBeUndefined();
+      expect(yield* requireApiKey(other.auth)).toBe("other-key");
       expect(harness.changes).toEqual([false]);
     }).pipe(Effect.scoped),
   );
@@ -245,7 +248,7 @@ it.layer(NodeServices.layer)("CursorAuth", (it) => {
       expect(harness.loginOptions()?.signal?.aborted).toBe(true);
       yield* Effect.sync(() => harness.complete.resolve());
       yield* Effect.promise(() => harness.returned.promise);
-      expect(yield* harness.auth.readApiKey).toBeUndefined();
+      expect(yield* readApiKey(harness.auth)).toBeUndefined();
     }).pipe(Effect.scoped),
   );
 
@@ -265,7 +268,7 @@ it.layer(NodeServices.layer)("CursorAuth", (it) => {
         ),
       );
       expect(Exit.isFailure(result)).toBe(true);
-      expect(yield* harness.auth.requireApiKey).toBe("browser-key");
+      expect(yield* requireApiKey(harness.auth)).toBe("browser-key");
     }).pipe(Effect.scoped),
   );
 
@@ -275,7 +278,7 @@ it.layer(NodeServices.layer)("CursorAuth", (it) => {
       Effect.gen(function* () {
         const harness = yield* makeHarness({ apiKey: " explicit-key " });
         yield* Effect.promise(() => harness.store.save(harness.credentials));
-        expect(yield* harness.auth.requireApiKey).toBe("explicit-key");
+        expect(yield* requireApiKey(harness.auth)).toBe("explicit-key");
         expect(Exit.isFailure(yield* Effect.exit(harness.auth.controller.start(owner)))).toBe(true);
         expect(
           Exit.isFailure(yield* Effect.exit(harness.auth.controller.logout(Effect.void))),
@@ -285,13 +288,42 @@ it.layer(NodeServices.layer)("CursorAuth", (it) => {
       }).pipe(Effect.scoped),
   );
 
+  it.effect.each<{ name: string; apiKey?: string; teamId?: string; expected?: CursorTeam }>([
+    { name: "the default team for browser sign-in" },
+    {
+      name: "CURSOR_TEAM_ID for browser sign-in",
+      teamId: " 42 ",
+      expected: { id: 42, name: undefined },
+    },
+    ...["abc", "0", "-1", "1.5", "1e3"].map((teamId) => ({
+      name: `the default team for an invalid CURSOR_TEAM_ID "${teamId}"`,
+      teamId,
+    })),
+    { name: "the default team for an explicit API key", apiKey: "explicit-key" },
+    {
+      name: "CURSOR_TEAM_ID for an explicit API key",
+      apiKey: "explicit-key",
+      teamId: "42",
+      expected: { id: 42, name: undefined },
+    },
+  ])("uses $name", ({ apiKey, teamId, expected }) =>
+    Effect.gen(function* () {
+      const harness = yield* makeHarness({
+        ...(apiKey ? { apiKey } : {}),
+        ...(teamId ? { teamId } : {}),
+      });
+      yield* Effect.promise(() => harness.store.save(harness.credentials));
+      expect((yield* harness.auth.requireAccess).team).toEqual(expected);
+    }).pipe(Effect.scoped),
+  );
+
   it.effect("ignores expired browser credentials and rejects disabled sign-in", () =>
     Effect.gen(function* () {
       const harness = yield* makeHarness({ enabled: false });
       yield* Effect.promise(() =>
         harness.store.save({ ...harness.credentials, apiKeyExpiresAtMs: 0 }),
       );
-      expect(yield* harness.auth.readApiKey).toBeUndefined();
+      expect(yield* readApiKey(harness.auth)).toBeUndefined();
       expect(Exit.isFailure(yield* Effect.exit(harness.auth.controller.start(owner)))).toBe(true);
     }).pipe(Effect.scoped),
   );