langchain-ai/deepagents · error · MCPConfigError

Invalid MCP config at {mcp_config_path}: {exc}

Error message

Invalid MCP config at {mcp_config_path}: {exc}

What it means

`_preflight_validate_mcp_config` catches ValueError (including json.JSONDecodeError and shape/field validator errors) and TypeError from `load_mcp_config` and re-raises them as this MCPConfigError with the offending path and reason. It means the MCP config file exists but its content is not a valid/expected server config. Bare RuntimeError is deliberately not caught so unrelated bugs are not masked as config errors.

Source

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

        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,
    model_name: str | None = None,
    summarization_model: str | None = None,
    model_params: dict[str, Any] | None = None,
    cli_max_retries: int | None = None,
    profile_overrides: dict[str, Any] | None = None,
    auto_approve: bool = False,
    interrupt_shell_only: bool = False,
    shell_allow_list: list[str] | None = None,

View on GitHub (pinned to a1af029e6e)

Solutions

1. Read the `: {exc}` detail in the message — it names the JSON parse error or failing validator
2. Validate the file with `python -m json.tool <path>` to find syntax errors
3. Compare the file against the expected MCP server-config schema (mcpServers-style object) and fix types/fields
4. Regenerate the config with the current tool version if the schema changed between versions

Example fix

// before
{"mcpServers": ["fs"]}  # wrong shape: list where object expected
// after
{"mcpServers": {"fs": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-fs"]}}}

import json

def validate_mcp_config(path: str) -> None:
    with open(path) as f:
        cfg = json.load(f)  # raises JSONDecodeError before launch
    if not isinstance(cfg, dict) or not isinstance(cfg.get("mcpServers"), dict):
        raise ValueError("mcpServers must be an object")

def is_mcp_config(obj: object) -> bool:
    return isinstance(obj, dict) and isinstance(obj.get("mcpServers"), dict)

try:
    await start_server_and_get_agent(..., mcp_config_path=path)
except MCPConfigError as e:
    print(f"fix MCP config: {e}")  # detail after ': ' names the parse/validator error
    raise

When it happens

Trigger: `--mcp-config` points at a file with invalid JSON (trailing commas, comments, truncated file), wrong top-level shape (e.g. a list instead of an object), wrong-typed fields (string where object expected — TypeError), or missing required server-config fields checked by `_validate_server_config`.

Common situations: Hand-edited JSON broken by a trailing comma; a config copied from a different tool with an incompatible schema; a YAML file saved with a .json extension; a config written by an older dcode version whose schema changed.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• {source}: {_display_path(path)}: malformed tools.json: expec
• {source}: {_display_path(path)}: tools[{index}] must be an o
• {source}: {_display_path(path)}: tools[{index}].{key} must b
• Server '{server_name}' cannot set both 'allowedTools' and 'd
• Server '{server_name}' '{field_name}' must be a list of stri

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