HKUDS/Vibe-Trading · error · ValueError

stdio MCP servers require a command

Error message

stdio MCP servers require a command

What it means

Raised by validate_transport_config when the resolved transport is stdio but the command field is empty or whitespace. stdio MCP servers launch a local process, so a command is mandatory.

Source

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

            raise ValueError("HTTP MCP servers require an explicit type of 'sse' or 'streamableHttp'")
        return "stdio"

    @model_validator(mode="after")
    def validate_transport_config(self) -> "MCPServerConfig":
        """Validate transport-specific MCP server configuration.

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

View on GitHub (pinned to 80ffdda44c)

Solutions

  1. Set command to the executable to run, e.g. command: npx with args for the package.
  2. If a URL server was intended, set url plus explicit type: sse/streamableHttp instead of leaving type as stdio.
  3. Check that env-var interpolation in the config actually resolves to a value.

Example fix

# before
mcp_servers:
  fs:
    type: stdio
    args: ["-y", "@modelcontextprotocol/server-filesystem"]

# after
mcp_servers:
  fs:
    type: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem"]
Defensive patterns

Strategy: validation

Validate before calling

def stdio_entry_valid(entry: dict) -> bool:
    transport = entry.get('type') or ('stdio' if entry.get('command') else None)
    if transport == 'stdio':
        return bool(str(entry.get('command', '')).strip())
    return True

Prevention

When it happens

Trigger: An MCP server entry with type: stdio (or implied stdio) and a missing/blank command; entries that only set args or env hoping the command is inherited.

Common situations: Copy-paste template missing the command line; environment-variable substitution producing an empty string; overriding a stdio server definition at runtime and dropping command.

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/fd2ab831c7d3cdc7. Report an issue: GitHub.