What causes "Server '{server_name}' 'args' must be a list" in langchain-ai/deepagents?

Change `args` to a list of separate argument strings, e.g. ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"].

langchain-ai/deepagents · error · TypeError

Server '{server_name}' 'args' must be a list

Error message

Server '{server_name}' 'args' must be a list

What it means

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.

Source

Thrown at libs/code/deepagents_code/mcp_tools.py:923

                        f"a string, got {type(value).__name__}"
                    )
                    raise TypeError(error_msg)
    elif server_type == "stdio":
        if "command" not in server_config:
            error_msg = f"Server '{server_name}' missing required 'command' field"
            raise ValueError(error_msg)

        if "url" in server_config:
            error_msg = (
                f"Server '{server_name}' has type 'stdio' but also declares "
                "a 'url' field. Remove 'url' or set "
                '`"type": "http"` (or `"sse"`) for a remote server.'
            )
            raise ValueError(error_msg)

        if "args" in server_config and not isinstance(server_config["args"], list):
            error_msg = f"Server '{server_name}' 'args' must be a list"
            raise TypeError(error_msg)

        if "env" in server_config and not isinstance(server_config["env"], dict):
            error_msg = f"Server '{server_name}' 'env' must be a dictionary"
            raise TypeError(error_msg)
    else:
        error_msg = (
            f"Server '{server_name}' has unsupported transport type '{server_type}'. "
            "Supported types: stdio, sse, http"
        )
        raise ValueError(error_msg)

    auth = server_config.get("auth")
    if auth is not None:
        if auth != "oauth":
            msg = (
                f"Server '{server_name}' has unsupported auth value "
                f"{auth!r}. Only 'oauth' is supported."
            )

View on GitHub (pinned to a1af029e6e)

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.

Example fix

// before
"args": "-y @modelcontextprotocol/server-filesystem /tmp"
// after
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

Defensive patterns

Strategy: type-guard

Validate before calling

def validate_args(name: str, cfg: dict) -> None:
    args = cfg.get("args")
    if args is not None and not (isinstance(args, list) and all(isinstance(a, str) for a in args)):
        raise TypeError(f"Server '{name}' 'args' must be a list of strings")

Type guard

def has_valid_args(cfg: dict) -> bool:
    args = cfg.get("args")
    return args is None or (isinstance(args, list) and all(isinstance(a, str) for a in args))

Try / catch

try:
    tools = resolve_and_load_mcp_tools(config)
except TypeError as e:
    if "'args' must be a list" in str(e):
        name = extract_server_name(str(e))
        cfg = config["servers"][name]
        if isinstance(cfg.get("args"), str):
            cfg["args"] = shlex.split(cfg["args"])
        tools = resolve_and_load_mcp_tools(config)
    else:
        raise

Prevention

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.

When it happens

Trigger: 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`.

Common situations: 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.

Related errors

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/5c98d97aa4d36817. Report an issue: GitHub.