langchain-ai/deepagents · error · ValueError

Server '{server_name}' with type '{server_type}' missing req

Error message

Server '{server_name}' with type '{server_type}' missing required 'url' field

What it means

Remote server types (in _SUPPORTED_REMOTE_TYPES, e.g. http/sse) require a 'url' field. Validation raises ValueError when the type is remote but 'url' is absent.

Source

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

        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)

        headers = server_config.get("headers")
        if headers is not None and not isinstance(headers, dict):
            error_msg = f"Server '{server_name}' 'headers' must be a dictionary"
            raise TypeError(error_msg)

        if isinstance(headers, dict):
            for name, value in headers.items():
                if not isinstance(value, str):
                    error_msg = (

View on GitHub (pinned to a1af029e6e)

Solutions

1. Add the 'url' field to the server config
2. Set "type": "stdio" if the server is actually launched via command
3. Validate config (resolve_and_load_mcp_tools / _validate_mcp_config_servers) before connecting

Example fix

// before
{"search": {"type": "http"}}
// after
{"search": {"type": "http", "url": "https://mcp.example.com/mcp"}}

def remote_entry_has_url(name: str, cfg: dict) -> bool:
    return cfg.get('type') not in ('http', 'sse', 'streamable-http') or 'url' in cfg

def is_remote_config(cfg: dict) -> bool:
    return cfg.get('type') in ('http', 'sse', 'streamable-http')

try:
    tools = await resolve_and_load_mcp_tools(config)
except ValueError as e:
    if "missing required 'url' field" in str(e):
        log.error('add a url for remote MCP server: %s', e)
    raise

When it happens

Trigger: Declaring {"type": "http"} or {"type": "sse"} without a 'url' key; omitting 'type' such that it resolves to a remote type while only providing command fields.

Common situations: Partial config from a template missing the url; server migrated from stdio to remote with the url left blank; provider config copy-paste dropping the url line.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 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}' config must be a dictionary
• 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/61c978f25222946a. Report an issue: GitHub.