langchain-ai/deepagents · error · TypeError

Server '{server_name}' config must be a dictionary

Error message

Server '{server_name}' config must be a dictionary

What it means

Each server's config value must be a dict (mapping of connection fields). Anything else (string, list, null) is rejected with TypeError.

Source

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

    Args:
        server_name: Name of the server.
        server_config: Server configuration dictionary.

    Raises:
        TypeError: If config fields have wrong types.
        ValueError: If required fields are missing or server type is unsupported.
    """
    if not _SERVER_NAME_RE.fullmatch(server_name):
        error_msg = (
            f"Invalid server name {server_name!r}: server names must contain "
            "only alphanumerics, hyphens, and underscores."
        )
        raise ValueError(error_msg)

    if not isinstance(server_config, dict):
        error_msg = f"Server '{server_name}' config must be a dictionary"
        raise TypeError(error_msg)

    server_type = _resolve_server_type(server_config)

    if server_type in _SUPPORTED_REMOTE_TYPES:
        if "url" not in server_config:
            error_msg = (
                f"Server '{server_name}' with type '{server_type}' "
                "missing required 'url' field"
            )
            raise ValueError(error_msg)

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

View on GitHub (pinned to a1af029e6e)

Solutions

1. Change the server entry to a dict, e.g. {"type": "stdio", "command": ..., "args": [...] }
2. Validate the parsed config structure before passing it to the library
3. Fix templating/merge bugs that replace the object with a scalar

Example fix

// before
{"mcpServers": {"fs": "npx -y @modelcontextprotocol/server-fs"}}
// after
{"mcpServers": {"fs": {"type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-fs"]}}}

def valid_server_entry(entry: object) -> bool:
    return isinstance(entry, dict)
config = {k: v for k, v in raw.items() if valid_server_entry(v)}

def is_server_config(value: object) -> bool:
    return isinstance(value, dict)

try:
    tools = await resolve_and_load_mcp_tools(config)
except TypeError as e:
    if 'must be a dictionary' in str(e):
        log.error('malformed mcpServers entry: %s', e)
    raise

When it happens

Trigger: Config file where a server entry is a string URL instead of an object, or an empty/null entry; malformed JSON/YAML merging producing non-dict values.

Common situations: Hand-edited mcp config like "fs": "npx ..."; templating errors rendering a server entry as empty; schema drift from another tool's config format.

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

• Invalid MCP server name {server_name!r}: token storage names
• MCPServerInfo {self.name!r}: status={self.status!r} cannot c
• Server '{server_name}' with type '{server_type}' missing req
• Server '{server_name}' has type '{server_type}' (remote) but
• {what} must be absolute: {path}

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