coleam00/Archon · warning

mcp_env_vars_missing

mcp_env_vars_missing

Error message

MCP config references undefined env vars: ${uniqueVars.join(', ')}. These will be empty strings — MCP servers may fail to authenticate.

What it means

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.

Source

Thrown at packages/providers/src/claude/provider.ts:623

            matchers as HookCallbackMatcher[];
        }
      }
    }
  }

  // mcp → load config and set mcpServers + allowedTools wildcards
  if (nodeConfig.mcp) {
    const mcpPath = nodeConfig.mcp;
    const { servers, serverNames, missingVars } = await loadMcpConfig(mcpPath, cwd);
    options.mcpServers = servers as Options['mcpServers'];
    const mcpWildcards = serverNames.map(name => `mcp__${name}__*`);
    options.allowedTools = [...(options.allowedTools ?? []), ...mcpWildcards];
    getLog().info({ serverNames, mcpPath }, 'claude.mcp_config_loaded');
    if (missingVars.length > 0) {
      const uniqueVars = [...new Set(missingVars)];
      getLog().warn({ missingVars: uniqueVars }, 'claude.mcp_env_vars_missing');
      warnings.push({
        code: 'mcp_env_vars_missing',
        message: `MCP config references undefined env vars: ${uniqueVars.join(', ')}. These will be empty strings — MCP servers may fail to authenticate.`,
      });
    }
    // Haiku models don't support tool search (lazy loading for many tools)
    if (options.model?.toLowerCase().includes('haiku')) {
      getLog().warn({ model: options.model }, 'claude.mcp_haiku_tool_search_unsupported');
      warnings.push({
        code: 'mcp_haiku_tool_search',
        message:
          'Using Haiku model with MCP servers — tool search (lazy loading for many tools) is not supported on Haiku. Consider using Sonnet or Opus.',
      });
    }
  }

  // Native skill selection. The SDK requires Skill to remain allowed when an
  // explicit tool list is present; without a list, its normal tool set applies.
  if (selectsSkills) {
    if (!options.allowedTools?.includes('Skill')) {

View on GitHub (pinned to 0773b97458)

Solutions

1. Export the missing variables before the run (e.g. `export GITHUB_TOKEN=...`) or put them in the loaded .env.
2. Pass the env vars through to the container/child process explicitly.
3. Remove the unused env reference from the MCP config if the server does not need it.

Example fix

// before
archon run workflow.yaml
// warning: MCP config references undefined env vars: GITHUB_TOKEN
// after
GITHUB_TOKEN=ghp_xxx archon run workflow.yaml

const config = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
const refs = [...JSON.stringify(config).matchAll(/\$\{([A-Z0-9_]+)\}/g)].map(m => m[1]);
const missing = [...new Set(refs)].filter(v => !(v in process.env));
if (missing.length) throw new Error(`set env before run: ${missing.join(', ')}`);

const result = await provider.sendQuery(...);
if (result.warnings.some(w => w.code === 'mcp_env_vars_missing')) {
  // stop and export the listed vars, then re-run
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• mcp_haiku_tool_search
• mcp_env_vars_missing
• Authentication failed for ${owner}/${repo}. ${authHint}
• ${data.error}
• user_fetch_failed

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/fa72ed1ffcdc1047. Report an issue: GitHub.