langchain-ai/deepagents · error · ValueError

Server '{server_name}' has unsupported auth value {auth!r}.

Error message

Server '{server_name}' has unsupported auth value {auth!r}. Only 'oauth' is supported.

What it means

The optional `auth` field on an MCP server config currently accepts only the literal value `"oauth"` (OAuth browser-based login for remote servers). `_validate_server_config` raises this ValueError when `auth` is set to any other value, since no other auth mode is implemented.

Source

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

        if "env" in server_config and not isinstance(server_config["env"], dict):
            error_msg = f"Server '{server_name}' 'env' must be a dictionary"
            raise TypeError(error_msg)
    else:
        error_msg = (
            f"Server '{server_name}' has unsupported transport type '{server_type}'. "
            "Supported types: stdio, sse, http"
        )
        raise ValueError(error_msg)

    auth = server_config.get("auth")
    if auth is not None:
        if auth != "oauth":
            msg = (
                f"Server '{server_name}' has unsupported auth value "
                f"{auth!r}. Only 'oauth' is supported."
            )
            raise ValueError(msg)
        if server_type == "stdio":
            msg = (
                f"Server '{server_name}' uses stdio transport; "
                "'auth: oauth' is only valid for http/sse transports."
            )
            raise ValueError(msg)
        header_names = {name.lower() for name in (server_config.get("headers") or {})}
        if "authorization" in header_names:
            msg = (
                f"Server '{server_name}' cannot combine 'auth: oauth' "
                "with an 'Authorization' header."
            )
            raise ValueError(msg)

    _validate_tool_filter_fields(server_name, server_config)


def _validate_tool_filter_fields(

View on GitHub (pinned to a1af029e6e)

Solutions

Set `"auth": "oauth"` if the server supports OAuth login, or remove `auth` entirely if not using OAuth.
For token-based auth, remove `auth` and pass an Authorization header instead: "headers": {"Authorization": "Bearer <token>"}.
Check the library's supported values — currently only 'oauth' — before inventing a scheme name.
For other auth styles, supply credentials via headers/env appropriate to the transport.

Example fix

// before
{"api": {"type": "http", "url": "https://mcp.example.com", "auth": "bearer"}}
// after
{"api": {"type": "http", "url": "https://mcp.example.com", "headers": {"Authorization": "Bearer <token>"}}}

Defensive patterns

Strategy: validation

Validate before calling

def validate_auth(name: str, cfg: dict) -> None:
    auth = cfg.get("auth")
    if auth is not None and auth != "oauth":
        raise ValueError(f"Server '{name}' has unsupported auth value {auth!r}. Only 'oauth' is supported.")

Type guard

def has_valid_auth(cfg: dict) -> bool:
    auth = cfg.get("auth")
    return auth is None or auth == "oauth"

Try / catch

try:
    tools = resolve_and_load_mcp_tools(config)
except ValueError as e:
    if "unsupported auth value" in str(e):
        name = extract_server_name(str(e))
        cfg = config["servers"][name]
        cfg.pop("auth", None)
        cfg.setdefault("headers", {})["Authorization"] = f"Bearer {os.environ.get('MCP_TOKEN', '')}"
        tools = resolve_and_load_mcp_tools(config)
    else:
        raise

Prevention

Remember only "oauth" is a valid auth value; everything else must go through headers/env.
For bearer/API-key auth, use headers: {"Authorization": "Bearer <token>"} on http/sse servers.
Do not use boolean or scheme-name values like `auth: true` or `auth: basic`.
Check the library docs for supported auth values when upgrading versions.

When it happens

Trigger: A server entry sets `auth` to something other than "oauth" or omits it — e.g. `"auth": "bearer"`, `"auth": "api_key"`, `"auth": "basic"`, `"auth": true` — and validation runs via `select_server`, `resolve_and_load_mcp_tools`, or the batch config validators.

Common situations: Guessing auth mode names copied from generic MCP client docs; switching from header-token auth and writing `auth: bearer` instead of using an Authorization header; setting `auth: true` expecting auth to be 'enabled'; older configs using auth scheme names no longer supported.

Related errors

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