langchain-ai/deepagents · error · MCPConfigError

MCP config file not found: {mcp_config_path}

Error message

MCP config file not found: {mcp_config_path}

What it means

Before spawning the server, `_preflight_validate_mcp_config` runs `load_mcp_config` on the explicit `--mcp-config` path in the parent process so config problems surface as a clean MCPConfigError instead of an opaque truncated log dump from inside the subprocess. When the file at `mcp_config_path` does not exist, the FileNotFoundError is re-raised as this MCPConfigError including the path.

Source

Thrown at libs/code/deepagents_code/client/launch/server_manager.py:279

        mcp_config_path: Explicit path passed via `--mcp-config`, or `None`.
        no_mcp: When `True`, MCP is disabled and validation is skipped.

    Raises:
        MCPConfigError: If the config file is malformed or missing required
            fields. Message includes the offending path for context.
    """
    if no_mcp or not mcp_config_path:
        return

    from deepagents_code.mcp_tools import MCPConfigError, load_mcp_config

    try:
        load_mcp_config(mcp_config_path)
    except MCPConfigError:
        raise
    except FileNotFoundError as exc:
        msg = f"MCP config file not found: {mcp_config_path}"
        raise MCPConfigError(msg) from exc
    except (ValueError, TypeError) as exc:
        # `ValueError` covers `json.JSONDecodeError` (subclass) and the
        # shape/field validators in `_validate_server_config`; `TypeError`
        # covers the wrong-type branches. Bare `RuntimeError` is
        # deliberately NOT caught — it would mask unrelated bugs
        # (recursion, reentrancy, stdlib internals) as config errors.
        msg = f"Invalid MCP config at {mcp_config_path}: {exc}"
        raise MCPConfigError(msg) from exc


# ------------------------------------------------------------------
# Server startup
# ------------------------------------------------------------------


async def start_server_and_get_agent(
    *,
    assistant_id: str,

View on GitHub (pinned to a1af029e6e)

Solutions

1. Check the path in the message exists: run `ls <path>` and correct typos
2. Use an absolute path for --mcp-config to avoid cwd-dependent resolution
3. Recreate the MCP config file if it was deleted, or point --mcp-config at a valid config
4. If MCP is not needed, pass the no_mcp flag (--no-mcp) to skip validation entirely

Example fix

// before
$ dcode --mcp-config ./mcfg.json  # FileNotFoundError -> MCPConfigError
// after
$ dcode --mcp-config /home/me/.config/dcode/mcp.json

from pathlib import Path

def mcp_config_exists(path: str | None) -> bool:
    return bool(path) and Path(path).expanduser().resolve().is_file()

try:
    await start_server_and_get_agent(..., mcp_config_path=path)
except MCPConfigError as e:
    if "not found" in str(e):
        print(f"check path: {e}")  # fix or pass --no-mcp
    else:
        raise

When it happens

Trigger: Passing `--mcp-config /path/to/config.json` where the file is missing — typo'd path, file deleted/moved after CLI config was written, relative path resolved from a different working directory, or a stale path stored in a wrapper script.

Common situations: Typo in the path; running dcode from a different cwd than when the path was recorded; dotfile config pointing at a temp file that was cleaned up; case-sensitivity issues on Linux paths.

Related errors

• MCP config file not found: {config_path}
• Invalid MCP config at {mcp_config_path}: {exc}
• {prefix}.{name} must be a dictionary, got {type(values).__na
• ManagedConfigError(provider.status)
• ManagedConfigError(ProviderStatus(name, path, ProviderHealth

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