MCP config file not found: ${mcpPath} (resolved to ${fullPat

Error message

MCP config file not found: ${mcpPath} (resolved to ${fullPath})

What it means

loadMcpConfig reads the file at the given path (resolved against cwd when relative) and translates Node's ENOENT into a clear error showing both the path you passed and the resolved absolute path. It exists so a wrong or missing MCP config path fails immediately with actionable context instead of an opaque fs error.

Source

Thrown at packages/providers/src/mcp/config.ts:140

}

/**
 * Load MCP server config from a JSON file and expand environment variables.
 */
export async function loadMcpConfig(
  mcpPath: string,
  cwd: string,
  envSource: EnvSource = process.env
): Promise<LoadedMcpConfig> {
  const fullPath = isAbsolute(mcpPath) ? mcpPath : resolve(cwd, mcpPath);

  let raw: string;
  try {
    raw = await readFile(fullPath, 'utf-8');
  } catch (err) {
    const e = err as NodeJS.ErrnoException;
    if (e.code === 'ENOENT') {
      throw new Error(`MCP config file not found: ${mcpPath} (resolved to ${fullPath})`);
    }
    throw new Error(`Failed to read MCP config file: ${mcpPath} - ${e.message}`);
  }

  let parsed: Record<string, unknown>;
  try {
    parsed = JSON.parse(raw) as Record<string, unknown>;
  } catch (parseErr) {
    const detail = (parseErr as SyntaxError).message;
    throw new Error(`MCP config file is not valid JSON: ${mcpPath} - ${detail}`);
  }

  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
    throw new Error(`MCP config must be a JSON object (Record<string, ServerConfig>): ${mcpPath}`);
  }

  const normalized = normalizeMcpConfig(parsed, mcpPath);
  const { expanded, missingVars } = expandEnvVars(normalized, envSource);

View on GitHub (pinned to 0773b97458)

Solutions

Check the resolved path in the message and create or restore the file there.
Pass an absolute mcpPath or verify cwd is the directory you expect.
ls the directory and correct a typo in the filename or extension (.json vs .jsonc).

Example fix

// before
await loadMcpConfig('.mcp.json', process.cwd()); // file actually at ~/.archon/.mcp.json
// after
await loadMcpConfig(join(os.homedir(), '.archon', '.mcp.json'), process.cwd());

Defensive patterns

Strategy: validation

Validate before calling

import { accessSync, constants } from 'fs';
const full = isAbsolute(p) ? p : resolve(cwd, p);
accessSync(full, constants.F_OK); // throws ENOENT early with your own message
await loadMcpConfig(p, cwd);

Try / catch

// catch (err) {
//   if (err.message.includes('MCP config file not found')) {
//     logger.error(`Check path; resolved target missing: ${err.message}`);
//     process.exitCode = 1;
//   } else throw err;
// }

Prevention

Use absolute paths (path.resolve/join from a known anchor) instead of relative defaults.
Check file existence (fs.access / existsSync) before configuring MCP.
Log cwd at startup in CI so relative-path resolution is debuggable.

When it happens

Trigger: Calling loadMcpConfig(path, cwd) where the file does not exist: typo'd filename, wrong cwd, file deleted, or a relative path resolved against an unexpected working directory.

Common situations: Referencing ~/.claude.json or .mcp.json that was never created; running from a different directory than assumed in CI; path built from an env var that is unset/empty; config renamed after an upgrade.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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