HKUDS/Vibe-Trading · error · ValueError

{transport} MCP servers require a url

Error message

{transport} MCP servers require a url

What it means

Raised by validate_transport_config when the resolved transport is sse or streamableHttp but the url field is empty. HTTP transports are entirely url-driven, so a blank url cannot proceed.

Source

Thrown at agent/src/config/schema.py:396

            The validated MCP server config instance.

        Raises:
            ValueError: If required fields are missing for the resolved
                transport or conflicting fields are provided.
        """
        transport = self.resolved_transport()

        if transport == "stdio":
            if not self.command.strip():
                raise ValueError("stdio MCP servers require a command")
            if self.url.strip() or self.headers:
                raise ValueError("stdio MCP servers do not accept url/headers")
            if self.auth is not None:
                raise ValueError("stdio MCP servers do not accept auth (OAuth is HTTP-only)")
            return self

        if not self.url.strip():
            raise ValueError(f"{transport} MCP servers require a url")
        if self.command.strip() or self.args or self.env:
            raise ValueError(f"{transport} MCP servers do not accept command/args/env")

        if self.auth is not None:
            # The OAuth provider owns the runtime Authorization header; a
            # hand-set static header alongside it is always a config error.
            if self.headers:
                raise ValueError(
                    "MCP servers using auth must not also set static headers "
                    "(the OAuth provider owns the Authorization header)"
                )
            # A refresh token must never traverse cleartext.
            if not self.url.strip().lower().startswith("https://"):
                raise ValueError("OAuth MCP servers require an https url")
        return self


class MCPServerConfigOverride(ConfigBase):

View on GitHub (pinned to 80ffdda44c)

Solutions

  1. Set the full endpoint url, e.g. url: https://mcp.example.com/sse.
  2. Verify any ${VAR} interpolation in the url resolves to a non-empty value.
  3. Ensure the url starts with https:// if auth is configured (plain http is otherwise accepted but discouraged).

Example fix

# before
mcp_servers:
  remote:
    type: streamableHttp

# after
mcp_servers:
  remote:
    type: streamableHttp
    url: https://mcp.example.com/mcp
Defensive patterns

Strategy: validation

Validate before calling

def http_mcp_has_url(entry: dict) -> bool:
    if entry.get('type') in ('sse', 'streamableHttp'):
        return bool(str(entry.get('url', '')).strip())
    return True

Prevention

When it happens

Trigger: An entry with type: sse/streamableHttp and no url, or a url of only whitespace; env-var templating that yields an empty string.

Common situations: Type set but url line accidentally deleted; secrets interpolation failing silently to ''; overriding a server at runtime and dropping url.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

AI-assisted analysis of HKUDS/Vibe-Trading@80ffdda44c (2026-08-28). Data as JSON: /api/errors/6b45dd6f98d07864. Report an issue: GitHub.