run_command passes HTTP kwargs to stdio transport when transport is unspecified

[strawgate]

When transport is not explicitly passed (stays None), run_command in cli/run.py forwards HTTP-specific kwargs like port and host to server.run_async(). run_async resolves None transport to settings.transport (default "stdio"), then passes these kwargs to run_stdio_async which doesn't accept them, causing TypeError.

Introduced in #3833 when if port: was changed to if port is not None: — the old truthiness check happened to filter out port=0 but also prevented any port from reaching stdio.

The fix needs to resolve the effective transport before deciding which kwargs to forward.

🤖 Generated with Claude Code

[marvin-context-protocol]

Claude finished @strawgate's task in 4m 3s —— View job

---

Triage

tl;dr — Confirmed bug. When transport is None in run_command, the guard if transport != "stdio": passes (None != "stdio" is True), leaking host/port/path kwargs into run_async(). That method resolves None → settings.transport (default "stdio") and forwards the kwargs to run_stdio_async(**transport_kwargs), which doesn't accept them → TypeError.

Recommendation

Resolve the effective transport in run_command before building kwargs, mirroring the pattern already used in cli.py:604–606. One-line addition plus a condition change — no new abstractions needed.

Findings

Root cause is in src/fastmcp/cli/run.py:240–254:

kwargs = {}
if transport is not None:
    kwargs["transport"] = transport
# Only pass HTTP-specific options for non-stdio transports
if transport != "stdio":          # ← BUG: None != "stdio" is True
    if host is not None:
        kwargs["host"] = host
    if port is not None:
        kwargs["port"] = port
    if path is not None:
        kwargs["path"] = path

When transport=None, host/port/path are forwarded unconditionally. Then in transport.py:58–67, run_async resolves the transport:

if transport is None:
    transport = fastmcp.settings.transport  # default: "stdio"
# ...
if transport == "stdio":
    await self.run_stdio_async(show_banner=show_banner, **transport_kwargs)

run_stdio_async (transport.py:184–188) only accepts show_banner, log_level, and stateless — the extra host/port/path kwargs raise TypeError.

The correct pattern already exists in cli.py:604–606:

final_transport = transport if transport is not None else config.deployment.transport

which is then used to guard HTTP kwargs at line 648: if final_transport != "stdio":.

Detailed Action Plan

File: src/fastmcp/cli/run.py

Step 1: Add a local import and resolve the effective transport (before line 240):

import fastmcp as _fastmcp

# Resolve effective transport before deciding which kwargs to forward
effective_transport = transport if transport is not None else _fastmcp.settings.transport

Step 2: Change the guard on line 243 from transport to effective_transport:

-    if transport != "stdio":
+    if effective_transport != "stdio":

The full corrected block becomes:

import fastmcp as _fastmcp
effective_transport = transport if transport is not None else _fastmcp.settings.transport

kwargs = {}
if transport is not None:
    kwargs["transport"] = transport
# Only pass HTTP-specific options for non-stdio transports
if effective_transport != "stdio":
    if host is not None:
        kwargs["host"] = host
    if port is not None:
        kwargs["port"] = port
    if path is not None:
        kwargs["path"] = path

Step 3: Add a test in tests/cli/test_run.py to prevent regression. The test should call run_command with transport=None and host/port set, mocking run_async and asserting that HTTP kwargs are not forwarded when the effective transport is "stdio":

async def test_run_command_no_transport_with_host_port_defaults_to_stdio(self, tmp_path):
    """Test that HTTP kwargs aren't passed to stdio when transport is None."""
    from unittest.mock import AsyncMock, patch
    from fastmcp.cli.run import run_command

    test_file = tmp_path / "server.py"
    test_file.write_text("""
import fastmcp
mcp = fastmcp.FastMCP("TestServer")
""")

    with patch("fastmcp.server.server.FastMCP.run_async", new_callable=AsyncMock) as run_mock:
        await run_command(str(test_file), host="0.0.0.0", port=9000)
        run_mock.assert_called_once()
        call_kwargs = run_mock.call_args[1]
        assert "host" not in call_kwargs
        assert "port" not in call_kwargs

Related Files

File	Relevance	Lines
src/fastmcp/cli/run.py	Contains the bug in run_command	240–254
src/fastmcp/server/mixins/transport.py	run_async resolves None → settings and dispatches to run_stdio_async	43–75, 184–224
src/fastmcp/cli/cli.py	Already resolves final_transport correctly — model for the fix	604–606, 648
src/fastmcp/settings.py	Default transport = "stdio"	257
tests/cli/test_run.py	Existing tests — no coverage for transport=None + HTTP kwargs	—

---

Marvin Context Protocol | Type /marvin to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.