langchain-ai/deepagents · error · ValueError

Invalid server name {server_name!r}: server names must conta

Error message

Invalid server name {server_name!r}: server names must contain only alphanumerics, hyphens, and underscores.

What it means

_validate_server_config enforces a naming convention: server names must match _SERVER_NAME_RE (alphanumerics, hyphens, underscores only). This keeps names safe for lookup, display, and tool-name composition.

Source

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

    Performs only shape checks — `${VAR}` config interpolation is deferred
    to activation time so one unset env var only fails its own server
    rather than hiding every other MCP entry in the same file.

    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) "

View on GitHub (pinned to a1af029e6e)

Solutions

1. Rename the server key to use only [A-Za-z0-9_-]
2. Replace dots/spaces with hyphens or underscores
3. Sanitize names programmatically before passing configs to the library

Example fix

// before
{"mcpServers": {"my.server": {"type": "stdio", ...}}}
// after
{"mcpServers": {"my-server": {"type": "stdio", ...}}}

import re
_SERVER_NAME_RE = re.compile(r'[A-Za-z0-9_-]+')
def valid_server_name(name: str) -> bool:
    return bool(_SERVER_NAME_RE.fullmatch(name))

def is_valid_server_name(name: object) -> bool:
    return isinstance(name, str) and bool(re.fullmatch(r'[A-Za-z0-9_-]+', name))

try:
    tools = await resolve_and_load_mcp_tools(config)
except ValueError as e:
    if 'server names must contain' in str(e):
        config = {re.sub(r'[^A-Za-z0-9_-]', '-', k): v for k, v in config.items()}
        tools = await resolve_and_load_mcp_tools(config)
    else:
        raise

When it happens

Trigger: Declaring an MCP server key containing dots, slashes, spaces, or unicode characters in the config; passing such a name to select_server or resolve_and_load_mcp_tools.

Common situations: Copying server keys from other tools that allow dots (e.g. 'my.server'); names derived from URLs or file paths; internationalized names.

Related errors

• Invalid agent name: {agent_name!r} is reserved for dcode's o
• trusted_ask_user_tool must be named ask_user
• trusted_compaction_tool must be named compact_conversation
• Invalid MCP config at {mcp_config_path}: {exc}
• Invalid MCP server name {server_name!r}: token storage names

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