langchain-ai/deepagents · error · ValueError

Server ' ' with type ' ' missing required 'url' field

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.

Solutions

Add the 'url' field to the server config
Set "type": "stdio" if the server is actually launched via command
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"}}

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

Always pair remote 'type' with 'url' in config templates
Validate configs at load time, before attempting connections
Keep example configs in the repo as canonical shapes

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 argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: 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)