Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

fix(cli): forward path, stateless and log-level to SDK MCPServer servers (#5870)

ε“ˆεŸΊη±³6dcec217f020
diff --git a/fastmcp_slim/fastmcp/cli/run.py b/fastmcp_slim/fastmcp/cli/run.py
index 4cf24034b..03344a769 100644
--- a/fastmcp_slim/fastmcp/cli/run.py
+++ b/fastmcp_slim/fastmcp/cli/run.py
@@ -240,7 +240,15 @@ async def run_command(
# handle the SDK's own high-level MCPServer (not a fastmcp.FastMCP)
if isinstance(server, SDKServer):
- await run_v1_server_async(server, host=host, port=port, transport=transport)
+ await run_v1_server_async(
+ server,
+ host=host,
+ port=port,
+ path=path,
+ stateless=stateless,
+ log_level=log_level,
+ transport=transport,
+ )
return
kwargs: dict[str, Any] = {}
@@ -318,6 +326,9 @@ async def run_v1_server_async(
host: str | None = None,
port: int | None = None,
transport: TransportType | None = None,
+ path: str | None = None,
+ stateless: bool = False,
+ log_level: LogLevelType | None = None,
) -> None:
"""Run a FastMCP 1.x server using async methods.
@@ -326,6 +337,13 @@ async def run_v1_server_async(
host: Host to bind to
port: Port to bind to
transport: Transport protocol to use
+ path: Route path for the HTTP endpoint (Streamable HTTP or SSE)
+ stateless: Whether to run Streamable HTTP without sessions. The SDK's
+ SSE transport has no stateless mode, so it is ignored for SSE.
+ log_level: Log level to apply to the server settings. ``MCPServer`` only
+ accepts ``log_level`` at construction time, but its HTTP runners read
+ ``settings.log_level`` (for uvicorn), so the setting is updated before
+ starting. The stdio runner does not consult it.
"""
# In v1 (MCPServer), host/port are no longer stored on `settings`; they are
# passed directly to the transport runners as keyword arguments.
@@ -334,13 +352,23 @@ async def run_v1_server_async(
bind_kwargs["host"] = host
if port is not None:
bind_kwargs["port"] = port
+ if log_level is not None:
+ # MCPServer has no run-time `log_level` kwarg. Its HTTP runners pass
+ # `settings.log_level` to uvicorn, so update the setting the SDK reads.
+ server.settings.log_level = log_level
match transport:
case "stdio":
await server.run_stdio_async()
case "http" | "streamable-http" | None:
+ if path is not None:
+ bind_kwargs["streamable_http_path"] = path
+ if stateless:
+ bind_kwargs["stateless_http"] = True
await server.run_streamable_http_async(**bind_kwargs)
case "sse":
+ if path is not None:
+ bind_kwargs["sse_path"] = path
await server.run_sse_async(**bind_kwargs)
diff --git a/tests/cli/test_run.py b/tests/cli/test_run.py
index 342c7ecee..b87f76986 100644
--- a/tests/cli/test_run.py
+++ b/tests/cli/test_run.py
@@ -356,7 +356,8 @@ async def async_echo(text: str) -> str:
SDKServer, "run_streamable_http_async", new_callable=AsyncMock
) as run_mock:
await run_command(str(test_file), transport="http")
- run_mock.assert_called_once()
+ # No path/stateless flags: defaults must be left to the SDK.
+ run_mock.assert_called_once_with()
async def test_run_v1_server_streamable_http(self, tmp_path):
"""Test that v1 server uses async streamable-http method."""
@@ -389,7 +390,7 @@ async def async_echo(text: str) -> str:
SDKServer, "run_streamable_http_async", new_callable=AsyncMock
) as run_mock:
await run_command(str(test_file), transport="streamable-http")
- run_mock.assert_called_once()
+ run_mock.assert_called_once_with()
async def test_run_v1_server_sse(self, tmp_path):
"""Test that v1 server uses async sse method."""
@@ -422,7 +423,7 @@ async def async_echo(text: str) -> str:
SDKServer, "run_sse_async", new_callable=AsyncMock
) as run_mock:
await run_command(str(test_file), transport="sse")
- run_mock.assert_called_once()
+ run_mock.assert_called_once_with()
async def test_run_v1_server_default_transport(self, tmp_path):
"""Test that v1 server uses streamable-http by default."""
@@ -455,7 +456,7 @@ async def async_echo(text: str) -> str:
SDKServer, "run_streamable_http_async", new_callable=AsyncMock
) as run_mock:
await run_command(str(test_file))
- run_mock.assert_called_once()
+ run_mock.assert_called_once_with()
async def test_run_v1_server_with_host_port(self, tmp_path):
"""Test that v1 server receives host/port settings."""
@@ -490,7 +491,217 @@ async def async_echo(text: str) -> str:
await run_command(
str(test_file), transport="http", host="0.0.0.0", port=9000
)
- run_mock.assert_called_once()
+ # Only host/port are forwarded; path/stateless stay at SDK defaults.
+ run_mock.assert_called_once_with(host="0.0.0.0", port=9000)
+
+ async def test_run_v1_server_transport_is_fourth_positional(self):
+ """The documented positional call must keep binding ``transport`` fourth.
+
+ ``run_v1_server_async(server, host, port, "sse")`` previously bound
+ ``"sse"`` to ``path`` and started Streamable HTTP instead of SSE.
+ """
+ from unittest.mock import AsyncMock, patch
+
+ from mcp.server.mcpserver import MCPServer as SDKServer
+
+ from fastmcp.cli.run import run_v1_server_async
+
+ server = SDKServer("V1Server")
+ with (
+ patch.object(
+ SDKServer, "run_stdio_async", new_callable=AsyncMock
+ ) as stdio_mock,
+ patch.object(
+ SDKServer, "run_streamable_http_async", new_callable=AsyncMock
+ ) as http_mock,
+ patch.object(
+ SDKServer, "run_sse_async", new_callable=AsyncMock
+ ) as sse_mock,
+ ):
+ await run_v1_server_async(server, "0.0.0.0", 9000, "sse")
+
+ sse_mock.assert_awaited_once_with(host="0.0.0.0", port=9000)
+ http_mock.assert_not_awaited()
+ stdio_mock.assert_not_awaited()
+
+ async def test_run_v1_server_http_with_path_and_stateless(self, tmp_path):
+ """Test that v1 Streamable HTTP receives --path and --stateless."""
+ from unittest.mock import AsyncMock, patch
+
+ from mcp.server.mcpserver import MCPServer as SDKServer
+
+ from fastmcp.cli.run import run_command
+
+ test_file = tmp_path / "v1_server.py"
+ test_file.write_text("""
+from mcp.server.mcpserver import MCPServer as FastMCP
+
+mcp = FastMCP("V1Server")
+""")
+
+ with patch.object(
+ SDKServer, "run_streamable_http_async", new_callable=AsyncMock
+ ) as run_mock:
+ await run_command(
+ str(test_file), transport="http", path="/custom", stateless=True
+ )
+ run_mock.assert_called_once_with(
+ streamable_http_path="/custom", stateless_http=True
+ )
+
+ async def test_run_v1_server_streamable_http_with_path(self, tmp_path):
+ """Test that v1 Streamable HTTP receives --path."""
+ from unittest.mock import AsyncMock, patch
+
+ from mcp.server.mcpserver import MCPServer as SDKServer
+
+ from fastmcp.cli.run import run_command
+
+ test_file = tmp_path / "v1_server.py"
+ test_file.write_text("""
+from mcp.server.mcpserver import MCPServer as FastMCP
+
+mcp = FastMCP("V1Server")
+""")
+
+ with patch.object(
+ SDKServer, "run_streamable_http_async", new_callable=AsyncMock
+ ) as run_mock:
+ await run_command(
+ str(test_file), transport="streamable-http", path="/custom"
+ )
+ run_mock.assert_called_once_with(streamable_http_path="/custom")
+
+ async def test_run_v1_server_stateless_without_path(self, tmp_path):
+ """Test that --stateless alone leaves the SDK path default untouched."""
+ from unittest.mock import AsyncMock, patch
+
+ from mcp.server.mcpserver import MCPServer as SDKServer
+
+ from fastmcp.cli.run import run_command
+
+ test_file = tmp_path / "v1_server.py"
+ test_file.write_text("""
+from mcp.server.mcpserver import MCPServer as FastMCP
+
+mcp = FastMCP("V1Server")
+""")
+
+ with patch.object(
+ SDKServer, "run_streamable_http_async", new_callable=AsyncMock
+ ) as run_mock:
+ await run_command(str(test_file), transport="http", stateless=True)
+ run_mock.assert_called_once_with(stateless_http=True)
+
+ async def test_run_v1_server_sse_with_path(self, tmp_path):
+ """Test that v1 SSE receives --path (and no unsupported stateless kwarg)."""
+ from unittest.mock import AsyncMock, patch
+
+ from mcp.server.mcpserver import MCPServer as SDKServer
+
+ from fastmcp.cli.run import run_command
+
+ test_file = tmp_path / "v1_server.py"
+ test_file.write_text("""
+from mcp.server.mcpserver import MCPServer as FastMCP
+
+mcp = FastMCP("V1Server")
+""")
+
+ with patch.object(
+ SDKServer, "run_sse_async", new_callable=AsyncMock
+ ) as run_mock:
+ # The SDK has no stateless SSE mode; only sse_path may be forwarded.
+ await run_command(
+ str(test_file), transport="sse", path="/custom", stateless=True
+ )
+ run_mock.assert_called_once_with(sse_path="/custom")
+
+ async def test_run_v1_server_forwards_cli_options(self, tmp_path):
+ """Test that run_command threads every parsed option into the v1 runner."""
+ from unittest.mock import ANY, AsyncMock, patch
+
+ from fastmcp.cli.run import run_command
+
+ test_file = tmp_path / "v1_server.py"
+ test_file.write_text("""
+from mcp.server.mcpserver import MCPServer as FastMCP
+
+mcp = FastMCP("V1Server")
+""")
+
+ with patch(
+ "fastmcp.cli.run.run_v1_server_async", new_callable=AsyncMock
+ ) as run_mock:
+ await run_command(
+ str(test_file),
+ transport="http",
+ host="0.0.0.0",
+ port=9000,
+ path="/custom",
+ stateless=True,
+ log_level="DEBUG",
+ )
+
+ run_mock.assert_awaited_once_with(
+ ANY,
+ host="0.0.0.0",
+ port=9000,
+ path="/custom",
+ stateless=True,
+ log_level="DEBUG",
+ transport="http",
+ )
+
+ async def test_run_v1_server_applies_log_level(self, tmp_path):
+ """Test that --log-level is applied to the SDK server settings."""
+ from unittest.mock import patch
+
+ from mcp.server.mcpserver import MCPServer as SDKServer
+
+ from fastmcp.cli.run import run_command
+
+ test_file = tmp_path / "v1_server.py"
+ test_file.write_text("""
+from mcp.server.mcpserver import MCPServer as FastMCP
+
+mcp = FastMCP("V1Server")
+""")
+
+ captured: dict[str, str] = {}
+
+ async def capture_log_level(server_self, **_kwargs):
+ captured["log_level"] = server_self.settings.log_level
+
+ with patch.object(SDKServer, "run_streamable_http_async", capture_log_level):
+ await run_command(str(test_file), transport="http", log_level="DEBUG")
+
+ assert captured["log_level"] == "DEBUG"
+
+ async def test_run_v1_server_keeps_default_log_level(self, tmp_path):
+ """Test that the SDK log level is untouched when --log-level is absent."""
+ from unittest.mock import patch
+
+ from mcp.server.mcpserver import MCPServer as SDKServer
+
+ from fastmcp.cli.run import run_command
+
+ test_file = tmp_path / "v1_server.py"
+ test_file.write_text("""
+from mcp.server.mcpserver import MCPServer as FastMCP
+
+mcp = FastMCP("V1Server")
+""")
+
+ captured: dict[str, str] = {}
+
+ async def capture_log_level(server_self, **_kwargs):
+ captured["log_level"] = server_self.settings.log_level
+
+ with patch.object(SDKServer, "run_streamable_http_async", capture_log_level):
+ await run_command(str(test_file), transport="http")
+
+ assert captured["log_level"] == "INFO"
class TestSkipSource: