MCP env variables

Author: jahooma

.agents/notion-agent.ts

@@ -24,7 +24,7 @@ const definition: AgentDefinition = {
       command: 'npx',
       args: ['-y', '@notionhq/notion-mcp-server'],
       env: {
-        NOTION_TOKEN: 'ntn_***',
+        NOTION_TOKEN: '$NOTION_TOKEN',
       },
     },
   },

.agents/notion-researcher.ts

@@ -28,7 +28,7 @@ const definition: AgentDefinition = {
       command: 'npx',
       args: ['-y', '@notionhq/notion-mcp-server'],
       env: {
-        NOTION_TOKEN: 'ntn_***',
+        NOTION_TOKEN: '$NOTION_TOKEN',
       },
     },
   },

.agents/types/util-types.ts

@@ -135,6 +135,28 @@ export type Message =
 
 // ===== MCP Server Types =====
 
+/**
+ * MCP server configuration for stdio-based servers.
+ *
+ * Environment variables in `env` can be:
+ * - A plain string value (hardcoded, e.g., `'production'`)
+ * - A `$VAR_NAME` reference to read from local environment (e.g., `'$NOTION_TOKEN'`)
+ *
+ * The `$VAR_NAME` syntax reads from `process.env.VAR_NAME` at agent load time.
+ * This keeps secrets out of your agent definitions - store them in `.env.local` instead.
+ *
+ * @example
+ * ```typescript
+ * env: {
+ *   // Read NOTION_TOKEN from local .env file
+ *   NOTION_TOKEN: '$NOTION_TOKEN',
+ *   // Read MY_API_KEY from local env, pass as API_KEY to MCP server
+ *   API_KEY: '$MY_API_KEY',
+ *   // Hardcoded value (non-secret)
+ *   NODE_ENV: 'production',
+ * }
+ * ```
+ */
 export type MCPConfig =
   | {
       type?: 'stdio'

agents/types/util-types.ts

@@ -135,6 +135,28 @@ export type Message =
 
 // ===== MCP Server Types =====
 
+/**
+ * MCP server configuration for stdio-based servers.
+ *
+ * Environment variables in `env` can be:
+ * - A plain string value (hardcoded, e.g., `'production'`)
+ * - A `$VAR_NAME` reference to read from local environment (e.g., `'$NOTION_TOKEN'`)
+ *
+ * The `$VAR_NAME` syntax reads from `process.env.VAR_NAME` at agent load time.
+ * This keeps secrets out of your agent definitions - store them in `.env.local` instead.
+ *
+ * @example
+ * ```typescript
+ * env: {
+ *   // Read NOTION_TOKEN from local .env file
+ *   NOTION_TOKEN: '$NOTION_TOKEN',
+ *   // Read MY_API_KEY from local env, pass as API_KEY to MCP server
+ *   API_KEY: '$MY_API_KEY',
+ *   // Hardcoded value (non-secret)
+ *   NODE_ENV: 'production',
+ * }
+ * ```
+ */
 export type MCPConfig =
   | {
       type?: 'stdio'

common/src/templates/initial-agents-dir/types/util-types.ts

@@ -128,6 +128,28 @@ export type Message =
 
 // ===== MCP Server Types =====
 
+/**
+ * MCP server configuration for stdio-based servers.
+ *
+ * Environment variables in `env` can be:
+ * - A plain string value (hardcoded, e.g., `'production'`)
+ * - A `$VAR_NAME` reference to read from local environment (e.g., `'$NOTION_TOKEN'`)
+ *
+ * The `$VAR_NAME` syntax reads from `process.env.VAR_NAME` at agent load time.
+ * This keeps secrets out of your agent definitions - store them in `.env.local` instead.
+ *
+ * @example
+ * ```typescript
+ * env: {
+ *   // Read NOTION_TOKEN from local .env file
+ *   NOTION_TOKEN: '$NOTION_TOKEN',
+ *   // Read MY_API_KEY from local env, pass as API_KEY to MCP server
+ *   API_KEY: '$MY_API_KEY',
+ *   // Hardcoded value (non-secret)
+ *   NODE_ENV: 'production',
+ * }
+ * ```
+ */
 export type MCPConfig =
   | {
       type?: 'stdio'

sdk/src/agents/load-agents.ts

@@ -22,6 +22,64 @@ export type LoadedAgentDefinition = AgentDefinition & {
  */
 export type LoadedAgents = Record<string, LoadedAgentDefinition>
 
+/**
+ * Resolves environment variable references in MCP server configs.
+ * Values starting with `$` are treated as env var references (e.g., `'$NOTION_TOKEN'`).
+ *
+ * @param env - The env object from MCP config with possible $VAR_NAME references
+ * @param agentId - The agent ID for error messages
+ * @param mcpServerName - The MCP server name for error messages
+ * @returns Resolved env object with all $VAR_NAME values replaced with actual values
+ * @throws Error if a referenced environment variable is missing
+ */
+export function resolveMcpEnv(
+  env: Record<string, string> | undefined,
+  agentId: string,
+  mcpServerName: string,
+): Record<string, string> {
+  if (!env) return {}
+
+  const resolved: Record<string, string> = {}
+
+  for (const [key, value] of Object.entries(env)) {
+    if (value.startsWith('$')) {
+      // $VAR_NAME reference - resolve from process.env
+      const envVarName = value.slice(1) // Remove the leading $
+      const envValue = process.env[envVarName]
+
+      if (envValue === undefined) {
+        throw new Error(
+          `Missing environment variable '${envVarName}' required by agent '${agentId}' in mcpServers.${mcpServerName}.env.${key}`,
+        )
+      }
+
+      resolved[key] = envValue
+    } else {
+      // Plain string value - use as-is
+      resolved[key] = value
+    }
+  }
+
+  return resolved
+}
+
+/**
+ * Resolves all MCP server env references in an agent definition.
+ * Mutates the mcpServers object to replace $VAR_NAME references with resolved values.
+ *
+ * @param agent - The agent definition to process
+ * @throws Error if any referenced environment variable is missing
+ */
+export function resolveAgentMcpEnv(agent: AgentDefinition): void {
+  if (!agent.mcpServers) return
+
+  for (const [serverName, config] of Object.entries(agent.mcpServers)) {
+    if ('command' in config && config.env) {
+      config.env = resolveMcpEnv(config.env, agent.id, serverName)
+    }
+  }
+}
+
 /**
  * Validation error for an agent that failed validation.
  */
@@ -183,6 +241,18 @@ export async function loadLocalAgents({
           agentDefinition.handleSteps.toString()
       }
 
+      // Resolve $env references in MCP server configs
+      try {
+        resolveAgentMcpEnv(processedAgentDefinition)
+      } catch (error) {
+        if (verbose) {
+          console.error(
+            error instanceof Error ? error.message : String(error),
+          )
+        }
+        continue
+      }
+
       agents[processedAgentDefinition.id] = processedAgentDefinition
     } catch (error) {
       if (verbose) {