langchain-ai/deepagents · error · FileNotFoundError

MCP config file not found: {config_path}

Error message

MCP config file not found: {config_path}

What it means

`_load_mcp_config_json` opens the MCP config file at the given path to parse it as JSON. If the path does not exist on disk it raises this FileNotFoundError before any parsing. This is an environment/path problem, not a JSON problem.

Source

Thrown at libs/code/deepagents_code/mcp_tools.py:1132

def _load_mcp_config_json(config_path: str) -> dict[str, Any]:
    """Load MCP configuration JSON with parser diagnostics.

    Args:
        config_path: Path to the MCP JSON configuration file.

    Returns:
        Parsed configuration dictionary.

    Raises:
        FileNotFoundError: If config file doesn't exist.
        json.JSONDecodeError: If config file contains invalid JSON.
    """
    path = Path(config_path)

    if not path.exists():
        error_msg = f"MCP config file not found: {config_path}"
        raise FileNotFoundError(error_msg)

    try:
        with path.open(encoding="utf-8") as file_obj:
            return json.load(file_obj)
    except json.JSONDecodeError as exc:
        # Build a layered message: core reason, an actionable hint for common
        # mistakes, then a caret snippet last so the auto-appended
        # "line X column Y" suffix reads as the location of the caret.
        parts = [f"Invalid JSON in MCP config file: {exc.msg}"]
        hint = _json_error_hint(exc)
        if hint is not None:
            parts.append(hint)
        snippet = _json_error_snippet(exc.doc, exc.lineno, exc.colno, pos=exc.pos)
        if snippet is not None:
            parts.append(snippet)
        error_msg = "\n".join(parts)
        raise json.JSONDecodeError(error_msg, exc.doc, exc.pos) from exc

View on GitHub (pinned to a1af029e6e)

Solutions

1. Check the path with `ls <config_path>` / Path.exists() and fix typos or point at the actual file.
2. Use an absolute path, or run the command from the directory containing the config.
3. Create the config file if it genuinely doesn't exist yet, e.g. `{"mcpServers": {}}` skeleton (then add servers).

Example fix

// before
load_mcp_config("./mcp.json")  # run from another cwd -> not found
// after
load_mcp_config("/home/me/project/.mcp.json")

from pathlib import Path
cfg = Path(config_path).expanduser().resolve()
if not cfg.is_file():
    raise SystemExit(f"config not found: {cfg}")
load_mcp_config(str(cfg))

def config_exists(path: str) -> bool:
    from pathlib import Path
    return Path(path).expanduser().is_file()

try:
    load_mcp_config(path)
except FileNotFoundError:
    logging.error("MCP config %s missing; create it or pass --config", path)
    sys.exit(2)

When it happens

Trigger: Calling the config loader (via _load_mcp_config_top_level) with a path that doesn't exist: a typo'd path, a relative path resolved from a different working directory, or a file deleted/moved after the path string was computed.

Common situations: Pointing dcode at ~/.cursor/mcp.json or .mcp.json that was never created; running from a different cwd so './mcp.json' resolves elsewhere; switching machines where the config was never synced; passing the project directory instead of the config file path.

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

• MCP config file not found: {mcp_config_path}
• Could not resolve {label} path {raw_path!r}: {exc}. Ensure t
• Invalid MCP config at {mcp_config_path}: {exc}
• {prefix}.{name} must be a dictionary, got {type(values).__na
• ManagedConfigError(provider.status)

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/dd12e7e753f539ec. Report an issue: GitHub.