@stigmer/react 0.0.78 → 0.0.80

package/src/agent/index.ts

@@ -26,7 +26,7 @@ export type {
   AgentEnvFormVariable,
 } from "./AgentEnvForm";
 
-export { diffEnvSpec } from "../environment/diffEnvSpec";
+export { diffEnv } from "../environment/diffEnv";
 
 export { useAgentSetup } from "./useAgentSetup";
 export type {

package/src/agent/useAgentSetup.ts

@@ -10,7 +10,7 @@ import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
 import { usePersonalEnvironment } from "../environment/usePersonalEnvironment";
 import { buildPersonalInstanceInput } from "../agent-instance/buildPersonalInstanceInput";
-import { diffEnvSpec } from "../environment/diffEnvSpec";
+import { diffEnv } from "../environment/diffEnv";
 import {
   agentSetupReducer,
   INITIAL_STATE,
@@ -106,8 +106,8 @@ export interface UseAgentSetupReturn {
   /**
    * Evaluate whether an agent is ready to use or needs env var collection.
    *
-   * Fetches the full agent to read its `env_spec`, checks for an existing
-   * personal instance, and diffs env_spec keys against the personal
+   * Fetches the full agent to read its `env` declarations, checks for an
+   * existing personal instance, and diffs env keys against the personal
    * environment. Returns `"ready"` when the agent can be used immediately,
    * or `"needsEnvVars"` when the caller should present {@link AgentEnvForm}.
    */
@@ -143,7 +143,7 @@ export interface UseAgentSetupReturn {
  *
  * When a user picks an agent in the {@link AgentPicker}, this hook
  * determines whether the agent requires credentials (via its
- * `env_spec`), checks what the user has already provided in their
+ * `env` declarations), checks what the user has already provided in their
  * personal environment, and either reports the agent as ready or
  * identifies the missing variables so the caller can render
  * {@link AgentEnvForm}.
@@ -173,7 +173,7 @@ export interface UseAgentSetupReturn {
  * @param org - Organization slug. Pass `null` to disable.
  * @param poolKeys - Optional set of env-var keys already available
  *   from the session env pool (manual secrets, one-time env vars from
- *   other components). When provided, agents whose `env_spec` keys
+ *   other components). When provided, agents whose `env` keys
  *   are fully covered by `poolKeys` + personal env auto-resolve to
  *   `ready` without prompting. Reactive — when `poolKeys` changes,
  *   `needsEnvVars` is re-evaluated.
@@ -221,10 +221,10 @@ export function useAgentSetup(
       try {
         const agent = await stigmer.agent.getByReference(ref);
         const agentName = agent.metadata?.name ?? ref.slug;
-        const envSpecData = agent.spec?.envSpec?.data;
+        const envDeclarations = agent.spec?.env;
 
-        // No env_spec — agent is immediately ready (direct mode).
-        if (!envSpecData || Object.keys(envSpecData).length === 0) {
+        // No env declarations — agent is immediately ready (direct mode).
+        if (!envDeclarations || Object.keys(envDeclarations).length === 0) {
           const resolution: AgentResolution = { mode: "direct" };
           dispatch({
             type: "RESOLVE_READY",
@@ -235,7 +235,7 @@ export function useAgentSetup(
           return { status: "ready", agentRef: ref, agentName, resolution };
         }
 
-        // Agent has env_spec — check for existing personal instance.
+        // Agent has env declarations — check for existing personal instance.
         const agentLabel = `${ref.org}/${ref.slug}`;
         const instanceList = await stigmer.agentInstance.list(
           create(ListAgentInstancesRequestSchema, {
@@ -265,8 +265,8 @@ export function useAgentSetup(
         const existingKeys = new Set(
           Object.keys(personalEnv.environment?.spec?.data ?? {}),
         );
-        const personalOnlyMissing = diffEnvSpec(envSpecData, existingKeys);
-        const missingVariables = diffEnvSpec(envSpecData, existingKeys, poolKeys);
+        const personalOnlyMissing = diffEnv(envDeclarations, existingKeys);
+        const missingVariables = diffEnv(envDeclarations, existingKeys, poolKeys);
 
         if (personalOnlyMissing.length === 0) {
           // Personal env covers all keys — create personal instance.

package/src/environment/EnvVarForm.tsx

@@ -9,7 +9,7 @@ import { ScrollFade } from "../internal/ScrollFade";
 /**
  * Describes a single environment variable the form should collect.
  *
- * Typically derived from a resource's `env_spec.data` entries (Agent,
+ * Typically derived from a resource's `env` entries (Agent,
  * McpServer, or any resource that declares required environment
  * variables). The caller is responsible for filtering out variables
  * the user has already provided (i.e. only pass the *missing* ones).
@@ -19,8 +19,14 @@ export interface EnvVarFormVariable {
   readonly key: string;
   /** When true, the input renders as a password field with a visibility toggle. */
   readonly isSecret: boolean;
-  /** Help text shown below the input. From the resource's env_spec description. */
+  /** Help text shown below the input. From the resource's env declaration description. */
   readonly description?: string;
+  /**
+   * When true, this variable is not required for the resource to function.
+   * Callers can use this to filter optional vars out of forms or to show
+   * them separately from required vars.
+   */
+  readonly optional?: boolean;
 }
 
 /** Options reported by the form alongside the collected values on submit. */
@@ -110,7 +116,7 @@ export interface EnvVarFormProps {
 
 /**
  * Compact form that collects environment variable values for any
- * resource that declares an `env_spec` (Agents, MCP servers, etc.).
+ * resource that declares `env` variables (Agents, MCP servers, etc.).
  *
  * Renders one labeled input per variable. Secret variables use a
  * password field with a visibility toggle. The form validates that

package/src/environment/EnvironmentListPanel.tsx

@@ -18,11 +18,26 @@ export interface EnvironmentListPanelProps {
   /** Optional label filter — only environments matching ALL labels are shown. */
   readonly labels?: Record<string, string>;
   /**
-   * Exclude environments whose labels contain all key-value pairs in this
-   * record. Useful for filtering the personal environment out of the
-   * organization list: `excludeLabels={{ "stigmer.ai/personal": "true" }}`.
+   * Exclude environments whose labels match one or more label sets.
+   *
+   * A single record uses AND semantics — the environment must match
+   * **all** key-value pairs to be excluded. Pass an array of records
+   * for OR-of-AND semantics: the environment is excluded when **any**
+   * record fully matches.
+   *
+   * @example
+   * ```tsx
+   * // Exclude personal envs only (single record — backward-compatible)
+   * excludeLabels={{ "stigmer.ai/personal": "true" }}
+   *
+   * // Exclude personal AND managed envs (array of records)
+   * excludeLabels={[
+   *   { "stigmer.ai/personal": "true" },
+   *   { "stigmer.ai/managed": "true" },
+   * ]}
+   * ```
    */
-  readonly excludeLabels?: Record<string, string>;
+  readonly excludeLabels?: Record<string, string> | Record<string, string>[];
   /** Fired when a user selects (expands) an environment. */
   readonly onEnvironmentSelect?: (env: Environment) => void;
   /** When `true`, variable editors render in read-only mode. */
@@ -82,13 +97,16 @@ export function EnvironmentListPanel({
   }
 
   const filtered = useMemo(() => {
-    if (!excludeLabels || Object.keys(excludeLabels).length === 0) {
-      return environments;
-    }
+    if (!excludeLabels) return environments;
+    const labelSets = Array.isArray(excludeLabels)
+      ? excludeLabels
+      : [excludeLabels];
+    if (labelSets.length === 0) return environments;
+
     return environments.filter((env) => {
       const envLabels = env.metadata?.labels ?? {};
-      const shouldExclude = Object.entries(excludeLabels).every(
-        ([k, v]) => envLabels[k] === v,
+      const shouldExclude = labelSets.some((labelSet) =>
+        Object.entries(labelSet).every(([k, v]) => envLabels[k] === v),
       );
       return !shouldExclude;
     });

package/src/environment/{diffEnvSpec.ts → diffEnv.ts}

@@ -4,38 +4,38 @@ import type { EnvVarFormVariable } from "./EnvVarForm";
  * Computes the list of environment variables a resource requires that
  * the user has not yet provided.
  *
- * Compares a resource's declared `env_spec.data` keys against a set of
+ * Compares a resource's declared `env` keys against a set of
  * keys already present in the user's personal environment **and** an
  * optional session-level env pool (manual secrets, one-time env vars
  * from other components). Variables whose keys are missing from both
  * sources are returned as {@link EnvVarFormVariable} entries suitable
  * for rendering in {@link EnvVarForm}.
  *
- * Works with any resource that declares an `EnvironmentSpec` — Agents,
+ * Works with any resource that declares env var declarations — Agents,
  * MCP servers, or future resource types.
  *
  * This is a pure function with no side effects — it can be unit-tested
  * independently of hooks, providers, or API calls.
  *
- * @param envSpecData - The resource's `spec.envSpec.data` record.
- *   Each entry declares a variable the resource needs, with `isSecret`
- *   and an optional `description`.
+ * @param envDeclarations - The resource's `spec.env` record.
+ *   Each entry declares a variable the resource needs, with `isSecret`,
+ *   an optional `description`, and an `optional` flag.
  * @param existingKeys - Keys already present in the user's personal
  *   environment (or any environment being checked against).
  * @param poolKeys - Optional additional keys from the session env pool
  *   (manual secrets, one-time env vars from other agents/MCP servers).
  *   When provided, variables satisfied by the pool are also excluded
  *   from the "missing" list.
- * @returns Variables from `envSpecData` not found in either key set.
+ * @returns Variables from `envDeclarations` not found in either key set.
  */
-export function diffEnvSpec(
-  envSpecData: Record<string, { isSecret: boolean; description?: string }>,
+export function diffEnv(
+  envDeclarations: Record<string, { isSecret: boolean; description?: string; optional?: boolean }>,
   existingKeys: Set<string>,
   poolKeys?: Set<string>,
 ): EnvVarFormVariable[] {
   const missing: EnvVarFormVariable[] = [];
 
-  for (const [key, value] of Object.entries(envSpecData)) {
+  for (const [key, value] of Object.entries(envDeclarations)) {
     if (existingKeys.has(key)) continue;
     if (poolKeys?.has(key)) continue;
 
@@ -43,6 +43,7 @@ export function diffEnvSpec(
       key,
       isSecret: value.isSecret,
       ...(value.description && { description: value.description }),
+      ...(value.optional && { optional: true }),
     });
   }
 

package/src/environment/index.ts

@@ -35,7 +35,7 @@ export type {
   EnvVarFormVariable,
   EnvVarFormSubmitOptions,
 } from "./EnvVarForm";
-export { diffEnvSpec } from "./diffEnvSpec";
+export { diffEnv } from "./diffEnv";
 export { useSessionEnvPool } from "./useSessionEnvPool";
 export type {
   SessionEnvPoolInput,

package/src/execution/SessionVariablesInput.tsx

@@ -22,7 +22,7 @@ export interface SessionVariablesInputProps {
    * between the variable and the agent/MCP server that needs it.
    *
    * Built by `SessionComposer` from the selected agent's and MCP
-   * servers' `env_spec` declarations.
+   * servers' `env` declarations.
    *
    * @example
    * ```ts

package/src/index.ts

@@ -221,6 +221,7 @@ export {
   useMcpServerConnect,
   useMcpServerOAuthConnect,
   useMcpServerCredentials,
+  useOAuthGrantStatus,
   OAuthCallbackHandler,
   McpServerPicker,
   McpServerConfigPanel,
@@ -255,6 +256,7 @@ export type {
   OAuthCallbackHandlerProps,
   OAuthCallbackParams,
   UseMcpServerCredentialsReturn,
+  UseOAuthGrantStatusReturn,
   McpServerAuthMode,
 } from "./mcp-server";
 
@@ -298,7 +300,7 @@ export type {
   GitHubRepoPickerProps,
 } from "./github";
 
-// Agent — data hook, count hook, list hook, search hook, picker, detail view, env form, setup orchestration, env_spec diffing, and default agent
+// Agent — data hook, count hook, list hook, search hook, picker, detail view, env form, setup orchestration, env diffing, and default agent
 export {
   useAgent,
   useAgentCount,
@@ -307,7 +309,7 @@ export {
   AgentPicker,
   AgentDetailView,
   AgentEnvForm,
-  diffEnvSpec,
+  diffEnv,
   useAgentSetup,
   useDefaultAgent,
 } from "./agent";

package/src/library/parse-resource-yaml.ts

@@ -9,8 +9,6 @@ import type {
   StdioServerConfigInput,
   HttpServerConfigInput,
   ToolApprovalPolicyInput,
-  EnvSpecInput,
-  EnvVarInput,
   ResourceRef,
 } from "@stigmer/sdk";
 import type { StigmerResourceKind } from "./detect-stigmer-resource";
@@ -47,7 +45,7 @@ export type ParsedResource =
  *
  * Handles the conversion from proto-style snake_case YAML field names to
  * the camelCase TypeScript SDK input types, including nested structures
- * like `mcp_server_usages`, `sub_agents`, and `env_spec`.
+ * like `mcp_server_usages`, `sub_agents`, and `env`.
  *
  * The `org` parameter **always overrides** `metadata.org` in the YAML.
  * This matches the UX intent of "Apply to [my-org]" — the user explicitly
@@ -207,7 +205,7 @@ function buildAgentInput(
     ...optionalField("mcpServerUsages", extractMcpServerUsages(spec)),
     ...optionalField("skillRefs", extractResourceRefs(spec, "skill_refs")),
     ...optionalField("subAgents", extractSubAgents(spec)),
-    ...optionalField("envSpec", extractEnvSpec(spec)),
+    ...optionalField("env", extractEnv(spec)),
   };
 }
 
@@ -333,7 +331,7 @@ function buildMcpServerInput(
       "pinnedToolApprovals",
       extractToolApprovalPolicy,
     ),
-    ...optionalField("envSpec", extractEnvSpec(spec)),
+    ...optionalField("env", extractEnv(spec)),
   };
 }
 
@@ -389,35 +387,46 @@ function extractToolApprovalPolicy(
 // Shared extractors
 // ---------------------------------------------------------------------------
 
-function extractEnvSpec(
+function extractEnv(
   spec: Record<string, unknown>,
-): EnvSpecInput | undefined {
-  const envSpecRaw = spec.env_spec ?? spec.envSpec;
-  if (!isPlainObject(envSpecRaw)) return undefined;
+): Record<string, { isSecret?: boolean; description?: string; optional?: boolean }> | undefined {
+  // Support both new flat `env` and legacy nested `env_spec.data` / `envSpec.data`.
+  let envMap: Record<string, unknown> | undefined;
+
+  const envRaw = spec.env;
+  if (isPlainObject(envRaw)) {
+    envMap = envRaw;
+  } else {
+    const envSpecRaw = spec.env_spec ?? spec.envSpec;
+    if (isPlainObject(envSpecRaw)) {
+      const data = envSpecRaw.data ?? envSpecRaw.variables;
+      if (isPlainObject(data)) {
+        envMap = data;
+      }
+    }
+  }
 
-  // Proto uses `data` as the map field name; SDK uses `variables`.
-  const data = envSpecRaw.data ?? envSpecRaw.variables;
-  if (!isPlainObject(data)) return undefined;
+  if (!envMap) return undefined;
 
-  const variables: Record<string, EnvVarInput> = {};
+  const result: Record<string, { isSecret?: boolean; description?: string; optional?: boolean }> = {};
   let hasEntries = false;
 
-  for (const [key, val] of Object.entries(data)) {
+  for (const [key, val] of Object.entries(envMap)) {
     if (!isPlainObject(val)) continue;
 
-    const value = typeof val.value === "string" ? val.value : "";
     const isSecret = val.is_secret ?? val.isSecret;
     const description = val.description;
+    const optional = val.optional;
 
-    variables[key] = {
-      value,
+    result[key] = {
       ...(typeof isSecret === "boolean" && { isSecret }),
       ...(typeof description === "string" && { description }),
+      ...(typeof optional === "boolean" && { optional }),
     };
     hasEntries = true;
   }
 
-  return hasEntries ? { variables } : undefined;
+  return hasEntries ? result : undefined;
 }
 
 function extractResourceRef(raw: Record<string, unknown>): ResourceRef {

package/src/library/serialize-resource-yaml.ts

@@ -15,7 +15,7 @@ import type {
   ToolApprovalPolicy,
 } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
-import type { EnvironmentSpec } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import type { EnvVarDeclaration } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
 
 /**
  * Serializes a proto `Agent` into the canonical Stigmer YAML format.
@@ -147,10 +147,10 @@ function buildAgentSpec(
     result.sub_agents = spec.subAgents.map(serializeSubAgent);
   }
 
-  if (spec.envSpec) {
-    const envSpec = serializeEnvSpec(spec.envSpec);
-    if (envSpec) {
-      result.env_spec = envSpec;
+  if (hasEntries(spec.env)) {
+    const env = serializeEnv(spec.env);
+    if (env) {
+      result.env = env;
     }
   }
 
@@ -271,10 +271,10 @@ function buildMcpServerSpec(
       spec.pinnedToolApprovals.map(serializeToolApprovalPolicy);
   }
 
-  if (spec.envSpec) {
-    const envSpec = serializeEnvSpec(spec.envSpec);
-    if (envSpec) {
-      result.env_spec = envSpec;
+  if (hasEntries(spec.env)) {
+    const env = serializeEnv(spec.env);
+    if (env) {
+      result.env = env;
     }
   }
 
@@ -361,20 +361,17 @@ function serializeResourceRef(
   return result;
 }
 
-function serializeEnvSpec(
-  envSpec: EnvironmentSpec,
-): Record<string, unknown> | undefined {
-  if (!hasEntries(envSpec.data)) return undefined;
+function serializeEnv(
+  env: { [key: string]: EnvVarDeclaration },
+): Record<string, Record<string, unknown>> | undefined {
+  const keys = Object.keys(env);
+  if (keys.length === 0) return undefined;
 
-  const data: Record<string, Record<string, unknown>> = {};
+  const result: Record<string, Record<string, unknown>> = {};
 
-  for (const [key, val] of Object.entries(envSpec.data)) {
+  for (const [key, val] of Object.entries(env)) {
     const entry: Record<string, unknown> = {};
 
-    if (val.value) {
-      entry.value = val.value;
-    }
-
     if (val.isSecret) {
       entry.is_secret = val.isSecret;
     }
@@ -383,17 +380,13 @@ function serializeEnvSpec(
       entry.description = val.description;
     }
 
-    data[key] = entry;
-  }
-
-  const result: Record<string, unknown> = {};
+    if (val.optional) {
+      entry.optional = val.optional;
+    }
 
-  if (envSpec.description) {
-    result.description = envSpec.description;
+    result[key] = entry;
   }
 
-  result.data = data;
-
   return result;
 }
 

package/src/mcp-server/McpServerDetailView.tsx

@@ -10,7 +10,7 @@ import type {
 } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
 import type { ToolApprovalPolicy, McpServerSpec } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
 import { ValidationState } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
-import type { EnvironmentValue } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import type { EnvVarDeclaration } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { useMcpServer } from "./useMcpServer";
 import { useMcpServerConnect } from "./useMcpServerConnect";
@@ -73,6 +73,13 @@ export interface McpServerDetailViewProps {
   readonly credentialPoolValues?: (
     key: string,
   ) => import("@stigmer/sdk").EnvVarInput | undefined;
+  /**
+   * The authenticated user's active organization slug.
+   * Used for OAuth token storage — tokens are stored in the user's personal
+   * environment within this org, not the MCP server's org.
+   * When omitted, falls back to the `org` prop (MCP server's org).
+   */
+  readonly activeOrg?: string;
   /** Additional CSS classes for the root container. */
   readonly className?: string;
 }
@@ -110,6 +117,7 @@ export function McpServerDetailView({
   defaultCapabilityTab = "tools",
   defaultShowCredentialForm = false,
   credentialPoolValues,
+  activeOrg,
   className,
 }: McpServerDetailViewProps) {
   const { mcpServer, isLoading, error, refetch } = useMcpServer(org, slug);
@@ -133,7 +141,7 @@ export function McpServerDetailView({
     if (!mcpServer?.metadata?.id) return;
 
     try {
-      await oauth.startOAuth(mcpServer.metadata.id);
+      await oauth.startOAuth(mcpServer.metadata.id, activeOrg ?? org);
       credentials.refetch();
       refetch();
     } catch {
@@ -258,9 +266,9 @@ export function McpServerDetailView({
         <ServerConfigSection serverType={spec.serverType} />
       )}
 
-      {spec?.envSpec && Object.keys(spec.envSpec.data).length > 0 && (
-        <EnvSpecSection
-          data={spec.envSpec.data}
+      {spec?.env && Object.keys(spec.env).length > 0 && (
+        <EnvSection
+          data={spec.env}
           oauthTargetEnvVar={credentials.oauthTargetEnvVar}
         />
       )}
@@ -278,6 +286,7 @@ export function McpServerDetailView({
           oauthPhase={oauth.phase}
           authMode={credentials.authMode}
           isOAuthConnected={credentials.isOAuthConnected}
+          accessTokenExpiresAt={credentials.accessTokenExpiresAt}
           tokenLifetimeHint={credentials.tokenLifetimeHint}
         />
 
@@ -346,6 +355,7 @@ function ConnectBar({
   oauthPhase,
   authMode,
   isOAuthConnected,
+  accessTokenExpiresAt,
   tokenLifetimeHint,
 }: {
   readonly isConnecting: boolean;
@@ -359,6 +369,7 @@ function ConnectBar({
   readonly oauthPhase: OAuthConnectPhase;
   readonly authMode: "manual" | "oauth";
   readonly isOAuthConnected: boolean;
+  readonly accessTokenExpiresAt: bigint;
   readonly tokenLifetimeHint: string | null;
 }) {
   const isOAuthBusy =
@@ -384,6 +395,8 @@ function ConnectBar({
 
   const statusText = (() => {
     if (authMode === "oauth" && isOAuthConnected) {
+      const expiryLabel = formatTokenExpiry(accessTokenExpiresAt);
+      if (expiryLabel) return `Tokens refresh automatically \u00B7 ${expiryLabel}`;
       const hint = tokenLifetimeHint && tokenLifetimeHint !== "never"
         ? ` \u00B7 Session lasts ~${tokenLifetimeHint}`
         : "";
@@ -480,6 +493,20 @@ function formatConnectionSummary(toolCount: number, policyCount: number): string
   return `${toolLabel}, ${policyLabel}`;
 }
 
+function formatTokenExpiry(expiresAtSeconds: bigint): string | null {
+  if (expiresAtSeconds === BigInt(0)) return null;
+  const nowSeconds = BigInt(Math.floor(Date.now() / 1000));
+  const remainingSeconds = expiresAtSeconds - nowSeconds;
+  if (remainingSeconds <= BigInt(0)) return "Token expired";
+  const minutes = Number(remainingSeconds / BigInt(60));
+  if (minutes < 1) return "Expires in <1 min";
+  if (minutes < 60) return `Expires in ${minutes} min`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `Expires in ${hours}h ${minutes % 60}m`;
+  const days = Math.floor(hours / 24);
+  return `Expires in ${days}d`;
+}
+
 // ---------------------------------------------------------------------------
 // Internal section components
 // ---------------------------------------------------------------------------
@@ -760,11 +787,11 @@ function ResourceTemplatesList({
   );
 }
 
-function EnvSpecSection({
+function EnvSection({
   data,
   oauthTargetEnvVar,
 }: {
-  readonly data: { [key: string]: EnvironmentValue };
+  readonly data: { [key: string]: EnvVarDeclaration };
   readonly oauthTargetEnvVar: string | null;
 }) {
   const entries = Object.entries(data).sort(([a], [b]) =>
@@ -789,6 +816,11 @@ function EnvSpecSection({
                   oauth
                 </span>
               )}
+              {env.optional && (
+                <span className="shrink-0 rounded bg-muted px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground/70">
+                  optional
+                </span>
+              )}
               {env.description && (
                 <span className="text-xs text-muted-foreground">
                   {env.description}

package/src/mcp-server/McpServerPicker.tsx

@@ -155,6 +155,13 @@ export interface McpServerPickerProps {
    * pre-populated.
    */
   readonly poolValues?: (key: string) => EnvVarInput | undefined;
+  /**
+   * The authenticated user's active organization slug.
+   * Used for OAuth token storage — tokens are stored in the user's personal
+   * environment within this org, not the MCP server's org.
+   * When omitted, falls back to the `org` prop.
+   */
+  readonly activeOrg?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -250,6 +257,7 @@ export function McpServerPicker({
   setup,
   initialServerKey,
   poolValues,
+  activeOrg,
 }: McpServerPickerProps) {
   const instanceId = useId();
   const listId = `${instanceId}-list`;
@@ -408,7 +416,7 @@ export function McpServerPicker({
           onSignIn: async () => {
             if (!entry.mcpServer.metadata?.id) return;
             try {
-              await oauth.startOAuth(entry.mcpServer.metadata.id);
+              await oauth.startOAuth(entry.mcpServer.metadata.id, activeOrg ?? org);
               setup.onServerAdded(ref);
             } catch {
               // error state managed by oauth hook

package/src/mcp-server/OAuthCallbackHandler.tsx

@@ -7,7 +7,9 @@ import type { OAuthCallbackMessage } from "./useMcpServerOAuthConnect";
 
 /** Parameters extracted from the OAuth callback URL. */
 export interface OAuthCallbackParams {
+  /** The authorization code returned by the OAuth provider. */
   readonly code: string;
+  /** The opaque state token used to correlate the callback with the originating request. */
   readonly state: string;
 }
 

package/src/mcp-server/index.ts

@@ -19,6 +19,9 @@ export type {
 export { useMcpServer } from "./useMcpServer";
 export type { UseMcpServerReturn } from "./useMcpServer";
 
+export { useOAuthGrantStatus } from "./useOAuthGrantStatus";
+export type { UseOAuthGrantStatusReturn } from "./useOAuthGrantStatus";
+
 export { McpServerPicker } from "./McpServerPicker";
 export type {
   McpServerPickerProps,

package/src/mcp-server/mcpServerSetupReducer.ts

@@ -35,15 +35,15 @@ export function toServerKey(ref: ResourceRef): string {
  *
  * Phases:
  * - `"loading"` — Fetching the full `McpServer` resource (spec + status).
- * - `"needsSetup"` — The server has an `env_spec` with variables missing
- *   from the user's personal environment. The UI should present a
- *   credential collection form.
+ * - `"needsSetup"` — The server has `env` declarations with variables
+ *   missing from the user's personal environment. The UI should present
+ *   a credential collection form.
  * - `"submitting"` — Environment variables are being persisted (save path)
  *   or collected (one-time path). The UI should show a loading indicator
  *   on the submit button.
  * - `"ready"` — The server is fully configured and ready for session
  *   creation. Carries the effective `enabledTools` list. Covers both
- *   the "no env_spec needed" and "env vars resolved" cases.
+ *   the "no env needed" and "env vars resolved" cases.
  */
 export type McpServerSetupPhase =
   | {