{"record":{"id":"c906f9e46f884adc","repo":"langchain-ai/deepagents","slug":"invalid-mcp-config-at-mcp-config-path-exc","errorCode":null,"errorMessage":"Invalid MCP config at {mcp_config_path}: {exc}","messagePattern":"Invalid MCP config at (.+?): (.+?)","errorType":"validation","errorClass":"MCPConfigError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/client/launch/server_manager.py","lineNumber":287,"sourceCode":"        return\n\n    from deepagents_code.mcp_tools import MCPConfigError, load_mcp_config\n\n    try:\n        load_mcp_config(mcp_config_path)\n    except MCPConfigError:\n        raise\n    except FileNotFoundError as exc:\n        msg = f\"MCP config file not found: {mcp_config_path}\"\n        raise MCPConfigError(msg) from exc\n    except (ValueError, TypeError) as exc:\n        # `ValueError` covers `json.JSONDecodeError` (subclass) and the\n        # shape/field validators in `_validate_server_config`; `TypeError`\n        # covers the wrong-type branches. Bare `RuntimeError` is\n        # deliberately NOT caught — it would mask unrelated bugs\n        # (recursion, reentrancy, stdlib internals) as config errors.\n        msg = f\"Invalid MCP config at {mcp_config_path}: {exc}\"\n        raise MCPConfigError(msg) from exc\n\n\n# ------------------------------------------------------------------\n# Server startup\n# ------------------------------------------------------------------\n\n\nasync def start_server_and_get_agent(\n    *,\n    assistant_id: str,\n    model_name: str | None = None,\n    summarization_model: str | None = None,\n    model_params: dict[str, Any] | None = None,\n    cli_max_retries: int | None = None,\n    profile_overrides: dict[str, Any] | None = None,\n    auto_approve: bool = False,\n    interrupt_shell_only: bool = False,\n    shell_allow_list: list[str] | None = None,","sourceCodeStart":269,"sourceCodeEnd":305,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/client/launch/server_manager.py#L269-L305","documentation":"`_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.","triggerScenarios":"`--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`.","commonSituations":"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.","solutions":["Read the `: {exc}` detail in the message — it names the JSON parse error or failing validator","Validate the file with `python -m json.tool <path>` to find syntax errors","Compare the file against the expected MCP server-config schema (mcpServers-style object) and fix types/fields","Regenerate the config with the current tool version if the schema changed between versions"],"exampleFix":"// before\n{\"mcpServers\": [\"fs\"]}  # wrong shape: list where object expected\n// after\n{\"mcpServers\": {\"fs\": {\"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-fs\"]}}}","handlingStrategy":"validation","validationCode":"import json\n\ndef validate_mcp_config(path: str) -> None:\n    with open(path) as f:\n        cfg = json.load(f)  # raises JSONDecodeError before launch\n    if not isinstance(cfg, dict) or not isinstance(cfg.get(\"mcpServers\"), dict):\n        raise ValueError(\"mcpServers must be an object\")","typeGuard":"def is_mcp_config(obj: object) -> bool:\n    return isinstance(obj, dict) and isinstance(obj.get(\"mcpServers\"), dict)","tryCatchPattern":"try:\n    await start_server_and_get_agent(..., mcp_config_path=path)\nexcept MCPConfigError as e:\n    print(f\"fix MCP config: {e}\")  # detail after ': ' names the parse/validator error\n    raise","preventionTips":["Run `python -m json.tool` on hand-edited configs","Keep the mcpServers schema (object of named server objects)","Never save YAML/JSONC with a .json extension","Regenerate configs after upgrading across schema versions"],"tags":["mcp","config","validation","json"],"backgroundTag":"schema-validation-failed","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}