{"record":{"id":"056a2da087b80476","repo":"langchain-ai/deepagents","slug":"mcpservers-field-must-be-a-dictionary","errorCode":null,"errorMessage":"'mcpServers' field must be a dictionary","messagePattern":"'mcpServers' field must be a dictionary","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/mcp_tools.py","lineNumber":1171,"sourceCode":"    \"\"\"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)\n\n\ndef _drop_invalid_mcp_config_servers(\n    config: dict[str, Any],","sourceCodeStart":1153,"sourceCodeEnd":1189,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/mcp_tools.py#L1153-L1189","documentation":"The config contains an `mcpServers` key, but `_validate_mcp_config_top_level` additionally requires it to be a dictionary mapping server names to server config objects. If the value is any other JSON type (string, array, number, null) this TypeError is raised.","triggerScenarios":"Config like {\"mcpServers\": [\"fs\", \"git\"]} (list of names), {\"mcpServers\": \"fs\"} (string), or {\"mcpServers\": null}; also files where the servers were written as an array of objects instead of a keyed object.","commonSituations":"Converting a list of servers from another tool without converting to a keyed object; a script that overwrote mcpServers with a serialized string; template placeholders left as null.","solutions":["Convert the value to an object keyed by server name: {\"mcpServers\": {\"fs\": {\"command\": \"mcp-server-fs\"}}}.","If the value is a JSON array of server objects, index each one by its name field when rebuilding the object.","Replace null/placeholder values with a real server map or an empty object (then add servers)."],"exampleFix":"// before\n{\"mcpServers\": [{\"name\": \"fs\", \"command\": \"mcp-server-fs\"}]}\n// after\n{\"mcpServers\": {\"fs\": {\"command\": \"mcp-server-fs\"}}}","handlingStrategy":"type-guard","validationCode":"cfg = json.load(open(path))\nservers = cfg.get(\"mcpServers\")\nif not isinstance(servers, dict):\n    raise SystemExit(\"'mcpServers' must be an object keyed by server name\")","typeGuard":"def is_server_map(cfg: object) -> bool:\n    return isinstance(cfg, dict) and isinstance(cfg.get(\"mcpServers\"), dict)","tryCatchPattern":"try:\n    load_mcp_config(path)\nexcept TypeError as e:\n    if \"'mcpServers' field must be a dictionary\" in str(e):\n        convert_list_to_map(path)\n    else:\n        raise","preventionTips":["Key servers by name in the JSON object; don't use arrays of {name, ...} objects.","Add a JSON schema check (type: object) for mcpServers in CI.","Be careful when scripts rewrite the config — confirm they preserve the dict shape."],"tags":["config","mcp","type-error","validation"],"backgroundTag":"schema-validation-failed","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}