{"record":{"id":"fa72ed1ffcdc1047","repo":"coleam00/Archon","slug":"mcp-env-vars-missing","errorCode":"mcp_env_vars_missing","errorMessage":"MCP config references undefined env vars: ${uniqueVars.join(', ')}. These will be empty strings — MCP servers may fail to authenticate.","messagePattern":"MCP config references undefined env vars: (.+?)\\. These will be empty strings — MCP servers may fail to authenticate\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/providers/src/claude/provider.ts","lineNumber":623,"sourceCode":"            matchers as HookCallbackMatcher[];\n        }\n      }\n    }\n  }\n\n  // mcp → load config and set mcpServers + allowedTools wildcards\n  if (nodeConfig.mcp) {\n    const mcpPath = nodeConfig.mcp;\n    const { servers, serverNames, missingVars } = await loadMcpConfig(mcpPath, cwd);\n    options.mcpServers = servers as Options['mcpServers'];\n    const mcpWildcards = serverNames.map(name => `mcp__${name}__*`);\n    options.allowedTools = [...(options.allowedTools ?? []), ...mcpWildcards];\n    getLog().info({ serverNames, mcpPath }, 'claude.mcp_config_loaded');\n    if (missingVars.length > 0) {\n      const uniqueVars = [...new Set(missingVars)];\n      getLog().warn({ missingVars: uniqueVars }, 'claude.mcp_env_vars_missing');\n      warnings.push({\n        code: 'mcp_env_vars_missing',\n        message: `MCP config references undefined env vars: ${uniqueVars.join(', ')}. These will be empty strings — MCP servers may fail to authenticate.`,\n      });\n    }\n    // Haiku models don't support tool search (lazy loading for many tools)\n    if (options.model?.toLowerCase().includes('haiku')) {\n      getLog().warn({ model: options.model }, 'claude.mcp_haiku_tool_search_unsupported');\n      warnings.push({\n        code: 'mcp_haiku_tool_search',\n        message:\n          'Using Haiku model with MCP servers — tool search (lazy loading for many tools) is not supported on Haiku. Consider using Sonnet or Opus.',\n      });\n    }\n  }\n\n  // Native skill selection. The SDK requires Skill to remain allowed when an\n  // explicit tool list is present; without a list, its normal tool set applies.\n  if (selectsSkills) {\n    if (!options.allowedTools?.includes('Skill')) {","sourceCodeStart":605,"sourceCodeEnd":641,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/providers/src/claude/provider.ts#L605-L641","documentation":"When loading the MCP config for a Claude node, the provider scans the config for environment-variable references that are undefined in the process environment and warns (code mcp_env_vars_missing) that they will expand to empty strings, which commonly breaks server authentication.","triggerScenarios":"An MCP server entry in the generated MCP config references `${VAR}` (or analogous env expansion) and VAR is not set in the environment running the provider.","commonSituations":"Forgetting to export an API token before running the workflow; running in CI where the secret was not passed through; .env file not loaded into the process.","solutions":["Export the missing variables before the run (e.g. `export GITHUB_TOKEN=...`) or put them in the loaded .env.","Pass the env vars through to the container/child process explicitly.","Remove the unused env reference from the MCP config if the server does not need it."],"exampleFix":"// before\narchon run workflow.yaml\n// warning: MCP config references undefined env vars: GITHUB_TOKEN\n// after\nGITHUB_TOKEN=ghp_xxx archon run workflow.yaml","handlingStrategy":"validation","validationCode":"const config = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));\nconst refs = [...JSON.stringify(config).matchAll(/\\$\\{([A-Z0-9_]+)\\}/g)].map(m => m[1]);\nconst missing = [...new Set(refs)].filter(v => !(v in process.env));\nif (missing.length) throw new Error(`set env before run: ${missing.join(', ')}`);","typeGuard":null,"tryCatchPattern":"const result = await provider.sendQuery(...);\nif (result.warnings.some(w => w.code === 'mcp_env_vars_missing')) {\n  // stop and export the listed vars, then re-run\n}","preventionTips":["Keep MCP env vars in a loaded .env and verify with a preflight check.","Pass required secrets explicitly into CI and containers.","Prune unused env references from MCP server configs."],"tags":["mcp","env-vars","claude","authentication"],"backgroundTag":"missing-env-var","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}