{"record":{"id":"d4bdf5e23f803cda","repo":"langchain-ai/deepagents","slug":"mcpservers-field-is-empty-no-servers-configure","errorCode":null,"errorMessage":"'mcpServers' field is empty - no servers configured","messagePattern":"'mcpServers' field is empty - no servers configured","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/mcp_tools.py","lineNumber":1175,"sourceCode":"\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],\n) -> tuple[dict[str, Any], dict[str, str]]:\n    \"\"\"Remove invalid server entries without rejecting valid siblings.\n\n    Callers use this only after config precedence has been resolved, so an","sourceCodeStart":1157,"sourceCodeEnd":1193,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/mcp_tools.py#L1157-L1193","documentation":"The `mcpServers` key is present and is a dictionary, but it contains no server entries. `_validate_mcp_config_top_level` raises this ValueError because a config with zero MCP servers is almost certainly a mistake — the agent would silently run with no MCP tools.","triggerScenarios":"Loading a config file containing {\"mcpServers\": {}}, typically a freshly scaffolded or emptied file, passed to _load_mcp_config_top_level.","commonSituations":"Creating a placeholder config before adding servers; a merge or migration script that dropped all server entries; a shared repo config where servers live in user-local files and the project file is intentionally empty.","solutions":["Add at least one server entry under 'mcpServers', e.g. {\"mcpServers\": {\"fs\": {\"command\": \"mcp-server-fs\", \"args\": [\"/path\"]}}}.","If the empty file is intentional scaffolding, don't pass it to the loader — point at the real config.","Check whether a script/editor emptied the file and restore the server entries from version control."],"exampleFix":"// before\n{\"mcpServers\": {}}\n// after\n{\"mcpServers\": {\"filesystem\": {\"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"]}}}","handlingStrategy":"validation","validationCode":"cfg = json.load(open(path))\nif not cfg.get(\"mcpServers\"):\n    raise SystemExit(\"no MCP servers configured; add entries under 'mcpServers'\")","typeGuard":"def has_any_server(cfg: dict) -> bool:\n    return bool(cfg.get(\"mcpServers\"))","tryCatchPattern":"try:\n    load_mcp_config(path)\nexcept ValueError as e:\n    if \"no servers configured\" in str(e):\n        point_at_real_config()  # or add server entries\n    else:\n        raise","preventionTips":["Never commit placeholder-empty configs where a real one is expected.","After any script edits the config, assert len(cfg['mcpServers']) > 0.","Keep project and personal server entries in separate files so one can't blank the other."],"tags":["config","mcp","validation","empty-config"],"backgroundTag":"empty-list-config","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}