{"record":{"id":"edb437d195816cae","repo":"langchain-ai/deepagents","slug":"mcp-config-must-contain-mcpservers-field-expect","errorCode":null,"errorMessage":"MCP config must contain 'mcpServers' field. Expected format: {\"mcpServers\": {\"server-name\": {...}}}","messagePattern":"MCP config must contain 'mcpServers' field\\. Expected format: (.+?)\\}\\}","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/mcp_tools.py","lineNumber":1167,"sourceCode":"        raise json.JSONDecodeError(error_msg, exc.doc, exc.pos) from exc\n\n\ndef _validate_mcp_config_top_level(config: dict[str, Any]) -> None:\n    \"\"\"Validate top-level MCP configuration fields.\n\n    Args:\n        config: Parsed MCP config dictionary.\n\n    Raises:\n        TypeError: If top-level fields have wrong types.\n        ValueError: If required top-level fields are missing.\n    \"\"\"\n    if \"mcpServers\" not in config:\n        error_msg = (\n            \"MCP config must contain 'mcpServers' field. \"\n            'Expected format: {\"mcpServers\": {\"server-name\": {...}}}'\n        )\n        raise ValueError(error_msg)\n\n    if not isinstance(config[\"mcpServers\"], dict):\n        error_msg = \"'mcpServers' field must be a dictionary\"\n        raise TypeError(error_msg)\n\n    if not config[\"mcpServers\"]:\n        error_msg = \"'mcpServers' field is empty - no servers configured\"\n        raise ValueError(error_msg)\n\n\ndef _validate_mcp_config_servers(config: dict[str, Any]) -> None:\n    \"\"\"Validate every server in an MCP configuration.\n\n    Args:\n        config: Parsed MCP config dictionary.\n    \"\"\"\n    for server_name, server_config in config[\"mcpServers\"].items():\n        _validate_server_config(server_name, server_config)","sourceCodeStart":1149,"sourceCodeEnd":1185,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/mcp_tools.py#L1149-L1185","documentation":"After loading and JSON-parsing the config file, `_validate_mcp_config_top_level` requires the top-level object to have an `mcpServers` key holding the server definitions. A JSON file that parses fine but lacks this key raises this ValueError describing the expected shape. The library only recognizes the {\"mcpServers\": {\"server-name\": {...}}} format.","triggerScenarios":"Passing a config file whose root is e.g. {\"servers\": {...}}, a bare array of servers, a Claude-Desktop-style file using a different key, or any JSON object without 'mcpServers' (e.g. a package.json passed by mistake).","commonSituations":"Using a config exported from another MCP client with a different top-level schema; hand-writing the file and nesting servers directly at the root; pointing the loader at the wrong JSON file entirely.","solutions":["Rename the top-level key to 'mcpServers' and nest each server dict under it.","If the file is an array of servers, wrap it: {\"mcpServers\": {name: serverDef, ...}}.","Verify you're loading the intended MCP config file, not another JSON document."],"exampleFix":"// before\n{\"fs\": {\"command\": \"mcp-server-fs\"}}\n// after\n{\"mcpServers\": {\"fs\": {\"command\": \"mcp-server-fs\"}}}","handlingStrategy":"validation","validationCode":"import json\ncfg = json.load(open(path))\nif \"mcpServers\" not in cfg:\n    raise SystemExit(\"config must have top-level 'mcpServers' object\")","typeGuard":"def has_mcp_servers(cfg: object) -> bool:\n    return isinstance(cfg, dict) and \"mcpServers\" in cfg","tryCatchPattern":"try:\n    load_mcp_config(path)\nexcept ValueError as e:\n    if \"'mcpServers' field\" in str(e):\n        rewrite_top_level_key(path)\n    else:\n        raise","preventionTips":["Validate the config against the {\"mcpServers\": {...}} schema in CI.","Copy example configs from this library's docs, not from other MCP clients with different schemas.","Keep MCP configs in dedicated files (e.g. .mcp.json), never reuse unrelated JSON files."],"tags":["config","mcp","validation","json-schema"],"backgroundTag":"schema-validation-failed","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}