{"record":{"id":"5c98d97aa4d36817","repo":"langchain-ai/deepagents","slug":"server-server-name-args-must-be-a-list","errorCode":null,"errorMessage":"Server '{server_name}' 'args' must be a list","messagePattern":"Server '(.+?)' 'args' must be a list","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/mcp_tools.py","lineNumber":923,"sourceCode":"                        f\"a string, got {type(value).__name__}\"\n                    )\n                    raise TypeError(error_msg)\n    elif server_type == \"stdio\":\n        if \"command\" not in server_config:\n            error_msg = f\"Server '{server_name}' missing required 'command' field\"\n            raise ValueError(error_msg)\n\n        if \"url\" in server_config:\n            error_msg = (\n                f\"Server '{server_name}' has type 'stdio' but also declares \"\n                \"a 'url' field. Remove 'url' or set \"\n                '`\"type\": \"http\"` (or `\"sse\"`) for a remote server.'\n            )\n            raise ValueError(error_msg)\n\n        if \"args\" in server_config and not isinstance(server_config[\"args\"], list):\n            error_msg = f\"Server '{server_name}' 'args' must be a list\"\n            raise TypeError(error_msg)\n\n        if \"env\" in server_config and not isinstance(server_config[\"env\"], dict):\n            error_msg = f\"Server '{server_name}' 'env' must be a dictionary\"\n            raise TypeError(error_msg)\n    else:\n        error_msg = (\n            f\"Server '{server_name}' has unsupported transport type '{server_type}'. \"\n            \"Supported types: stdio, sse, http\"\n        )\n        raise ValueError(error_msg)\n\n    auth = server_config.get(\"auth\")\n    if auth is not None:\n        if auth != \"oauth\":\n            msg = (\n                f\"Server '{server_name}' has unsupported auth value \"\n                f\"{auth!r}. Only 'oauth' is supported.\"\n            )","sourceCodeStart":905,"sourceCodeEnd":941,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/mcp_tools.py#L905-L941","documentation":"For stdio servers, `args` is the list of command-line arguments passed to the subprocess and must be a list of strings. `_validate_server_config` raises this TypeError when `args` is present but not a list (e.g. a single string), preventing malformed argv from reaching the process launcher.","triggerScenarios":"A stdio server entry contains `args` as a non-list value — e.g. `\"args\": \"-y server.ts\"` or `\"args\": {\"flag\": true}` — reached through `select_server`, `resolve_and_load_mcp_tools`, or `_validate_mcp_config_servers`/`_drop_invalid_mcp_config_servers`.","commonSituations":"Writing all arguments as one space-separated string instead of a list; JSON where args became an object; YAML flow-style mistakes; converting a shell command line directly into `args` without splitting it.","solutions":["Change `args` to a list of separate argument strings, e.g. [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"].","Split a single command string with shlex.split(...) when building config programmatically.","Omit `args` entirely if the command takes no arguments (it is optional).","Ensure no stray quoting: each element is one argv token, no shell quoting inside elements."],"exampleFix":"// before\n\"args\": \"-y @modelcontextprotocol/server-filesystem /tmp\"\n// after\n\"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"]","handlingStrategy":"type-guard","validationCode":"def validate_args(name: str, cfg: dict) -> None:\n    args = cfg.get(\"args\")\n    if args is not None and not (isinstance(args, list) and all(isinstance(a, str) for a in args)):\n        raise TypeError(f\"Server '{name}' 'args' must be a list of strings\")","typeGuard":"def has_valid_args(cfg: dict) -> bool:\n    args = cfg.get(\"args\")\n    return args is None or (isinstance(args, list) and all(isinstance(a, str) for a in args))","tryCatchPattern":"try:\n    tools = resolve_and_load_mcp_tools(config)\nexcept TypeError as e:\n    if \"'args' must be a list\" in str(e):\n        name = extract_server_name(str(e))\n        cfg = config[\"servers\"][name]\n        if isinstance(cfg.get(\"args\"), str):\n            cfg[\"args\"] = shlex.split(cfg[\"args\"])\n        tools = resolve_and_load_mcp_tools(config)\n    else:\n        raise","preventionTips":["Always write args as a JSON/YAML array of strings, one argv token per element.","Use shlex.split to convert a command string into args programmatically.","Do not include shell quoting inside args elements; there is no shell in between.","Lint configs so args entries are strings, not numbers or nested objects."],"tags":["mcp","config-validation","typeerror","stdio"],"backgroundTag":"mcp-server-config-invalid","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}