langchain-ai/deepagents · error · TypeError

{prefix}.args must be a list, got {type(args).__name__}

Error message

{prefix}.args must be a list, got {type(args).__name__}

What it means

`resolve_mcp_server_env` requires the `args` field of an MCP server entry to be a list; each element is then validated and env-interpolated as a string. If `args` is any other container type (string, dict, tuple), `TypeError` is raised naming the server path and the actual type.

Source

Thrown at libs/code/deepagents_code/mcp_config.py:161

    Raises:
        TypeError: If a supported field has the wrong type — a non-string
            scalar value, or `args`/`env`/`headers` with the wrong container
            type.
        RuntimeError: If a required environment variable is unset.
    """  # noqa: DOC502 - `RuntimeError` is raised by `_interpolate_env`
    resolved: dict[str, Any] = copy.deepcopy(dict(server_config))
    prefix = f"mcpServers.{server_name}"

    for name in ("command", "url"):
        if name in resolved:
            resolved[name] = _resolve_string(resolved[name], field=f"{prefix}.{name}")

    if "args" in resolved:
        args = resolved["args"]
        if not isinstance(args, list):
            msg = f"{prefix}.args must be a list, got {type(args).__name__}"
            raise TypeError(msg)
        resolved["args"] = [
            _resolve_string(value, field=f"{prefix}.args[{index}]")
            for index, value in enumerate(args)
        ]

    for name in ("env", "headers"):
        if name not in resolved:
            continue
        values = resolved[name]
        if not isinstance(values, dict):
            msg = f"{prefix}.{name} must be a dictionary, got {type(values).__name__}"
            raise TypeError(msg)
        resolved[name] = _resolve_mapping_values(values, field=f"{prefix}.{name}")

    return resolved

View on GitHub (pinned to a1af029e6e)

Solutions

1. Change `args` to a JSON list of strings: `"args": ["-y", "@model/server"]`.
2. If args came as one string, split it into list elements rather than relying on shell splitting (no shell word-splitting is performed).
3. Validate the server entry's shape before connecting — every element must also be a string (see error `mcpServers.<name>.args[i] must be a string`).

Example fix

// before
{"command": "npx", "args": "-y @modelcontextprotocol/server-everything"}
// after
{"command": "npx", "args": ["-y", "@modelcontextprotocol/server-everything"]}

def check_args(cfg: dict) -> str | None:
    if "args" in cfg and not isinstance(cfg["args"], list):
        return f"args must be a list, got {type(cfg['args']).__name__}"
    return None

def is_str_list(v: object) -> TypeGuard[list[str]]:
    return isinstance(v, list) and all(isinstance(x, str) for x in v)

try:
    resolved = resolve_mcp_server_env(server_name, server_config)
except TypeError as exc:
    if ".args must be a list" in str(exc):
        raise SystemExit(f"Fix {server_name}: wrap args in a JSON array") from exc
    raise

When it happens

Trigger: Calling `resolve_mcp_server_env` (directly, via login, `/mcp connect` preflight, or header resolution) with a server config where `args` is a string or object instead of a JSON array, e.g. `args: "-y @model/server"` or `args: {"0": "-y"}`.

Common situations: Hand-editing `mcpServers` entries and writing args as a single space-joined string; copying a Docker `CMD`-style config that uses a dict; converting configs from tools that serialize args differently; YAML configs where args collapsed to a scalar.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• {field} must be a string, got {type(value).__name__}
• Server '{server_name}' missing required 'command' field
• Server '{server_name}' has type 'stdio' but also declares a
• Server '{server_name}' 'args' must be a list
• Server '{server_name}' 'env' must be a dictionary

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