diff --git a/docs/clients/client.mdx b/docs/clients/client.mdx index c56ce634e..ea5971a99 100644 --- a/docs/clients/client.mdx +++ b/docs/clients/client.mdx @@ -102,7 +102,7 @@ config = { "mcpServers": { "server_name": { # Remote HTTP/SSE server - "transport": "streamable-http", # or "sse" + "transport": "http", # or "sse" "url": "https://api.example.com/mcp", "headers": {"Authorization": "Bearer token"}, "auth": "oauth" # or bearer token string diff --git a/docs/clients/transports.mdx b/docs/clients/transports.mdx index 94c94833c..d02aaf6f2 100644 --- a/docs/clients/transports.mdx +++ b/docs/clients/transports.mdx @@ -41,7 +41,7 @@ Streamable HTTP is the recommended transport for web-based deployments, providin - **Class:** `fastmcp.client.transports.StreamableHttpTransport` - **Inferred From:** URLs starting with `http://` or `https://` (default for HTTP URLs since v2.3.0) that do not contain `/sse/` in the path -- **Server Compatibility:** Works with FastMCP servers running in `streamable-http` mode +- **Server Compatibility:** Works with FastMCP servers running in `http` mode #### Basic Usage @@ -150,7 +150,7 @@ client = Client(transport) - **Use Streamable HTTP when:** - Setting up new deployments (recommended default) - You need bidirectional streaming - - You're connecting to FastMCP servers running in `streamable-http` mode + - You're connecting to FastMCP servers running in `http` mode - **Use SSE when:** - Connecting to legacy FastMCP servers running in `sse` mode @@ -397,7 +397,7 @@ config = { # Remote HTTP server "weather": { "url": "https://weather-api.example.com/mcp", - "transport": "streamable-http" + "transport": "http" }, # Local stdio server "assistant": { @@ -408,7 +408,7 @@ config = { # Another remote server "calendar": { "url": "https://calendar-api.example.com/mcp", - "transport": "streamable-http" + "transport": "http" } } } diff --git a/docs/deployment/running-server.mdx b/docs/deployment/running-server.mdx index 591cba32c..6436c82da 100644 --- a/docs/deployment/running-server.mdx +++ b/docs/deployment/running-server.mdx @@ -105,7 +105,7 @@ When using Stdio transport, you will typically *not* run the server yourself as Streamable HTTP is a modern, efficient transport for exposing your MCP server via HTTP. It is the recommended transport for web-based deployments. -To run a server using Streamable HTTP, you can use the `run()` method with the `transport` argument set to `"streamable-http"`. This will start a Uvicorn server on the default host (`127.0.0.1`), port (`8000`), and path (`/mcp/`). +To run a server using Streamable HTTP, you can use the `run()` method with the `transport` argument set to `"http"`. This will start a Uvicorn server on the default host (`127.0.0.1`), port (`8000`), and path (`/mcp/`). ```python {6} server.py from fastmcp import FastMCP @@ -113,7 +113,7 @@ from fastmcp import FastMCP mcp = FastMCP() if __name__ == "__main__": - mcp.run(transport="streamable-http") + mcp.run(transport="http") ``` ```python {5} client.py import asyncio @@ -128,6 +128,10 @@ if __name__ == "__main__": ``` + +For backward compatibility, wherever `"http"` is accepted as a transport name, you can also pass `"streamable-http"` as a fully supported alias. This is particularly useful when upgrading from FastMCP 1.x in the official Python SDK and FastMCP \<= 2.9, where `"streamable-http"` was the standard name. + + To customize the host, port, path, or log level, provide appropriate keyword arguments to the `run()` method. @@ -138,7 +142,7 @@ mcp = FastMCP() if __name__ == "__main__": mcp.run( - transport="streamable-http", + transport="http", host="127.0.0.1", port=4200, path="/my-custom-path", @@ -158,7 +162,6 @@ if __name__ == "__main__": ``` - ### SSE @@ -250,7 +253,7 @@ def hello(name: str) -> str: async def main(): # Use run_async() in async contexts - await mcp.run_async(transport="streamable-http") + await mcp.run_async(transport="http") if __name__ == "__main__": asyncio.run(main()) diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx index 4e59b3557..d63a077a4 100644 --- a/docs/getting-started/installation.mdx +++ b/docs/getting-started/installation.mdx @@ -47,7 +47,7 @@ FastMCP root path: ~/Developer/fastmcp Upgrading from the official MCP SDK's FastMCP 1.0 to FastMCP 2.0 is generally straightforward. The core server API is highly compatible, and in many cases, changing your import statement from `from mcp.server.fastmcp import FastMCP` to `from fastmcp import FastMCP` will be sufficient. -```python {1-5} +```python {5} # Before # from mcp.server.fastmcp import FastMCP @@ -56,8 +56,9 @@ from fastmcp import FastMCP mcp = FastMCP("My MCP Server") ``` + -Prior to `fastmcp==2.3.0` and `mcp==1.8.0`, the 2.x API always mirrored the 1.0 API. However, as the projects diverge, this can not be guaranteed. You may see deprecation warnings if you attempt to use 1.0 APIs in FastMCP 2.x. Please refer to this documentation for details on new capabilities. +Prior to `fastmcp==2.3.0` and `mcp==1.8.0`, the 2.x API always mirrored the official 1.0 API. However, as the projects diverge, this can not be guaranteed. You may see deprecation warnings if you attempt to use 1.0 APIs in FastMCP 2.x. Please refer to this documentation for details on new capabilities. ## Versioning and Breaking Changes diff --git a/docs/integrations/anthropic.mdx b/docs/integrations/anthropic.mdx index 476569b42..6e2651a7c 100644 --- a/docs/integrations/anthropic.mdx +++ b/docs/integrations/anthropic.mdx @@ -31,7 +31,7 @@ def roll_dice(n_dice: int) -> list[int]: return [random.randint(1, 6) for _ in range(n_dice)] if __name__ == "__main__": - mcp.run(transport="streamable-http", port=8000) + mcp.run(transport="http", port=8000) ``` ## Deploy the Server @@ -175,7 +175,7 @@ def roll_dice(n_dice: int) -> list[int]: if __name__ == "__main__": print(f"\n---\n\n🔑 Dice Roller access token:\n\n{access_token}\n\n---\n") - mcp.run(transport="streamable-http", port=8000) + mcp.run(transport="http", port=8000) ``` ### Client Authentication diff --git a/docs/integrations/chatgpt.mdx b/docs/integrations/chatgpt.mdx index c5c2f1194..a4d2c6942 100644 --- a/docs/integrations/chatgpt.mdx +++ b/docs/integrations/chatgpt.mdx @@ -102,7 +102,7 @@ def create_server( if __name__ == "__main__": mcp = create_server("path/to/records.json") - mcp.run(transport="streamable-http", port=8000) + mcp.run(transport="http", port=8000) ``` ### Deploy the Server diff --git a/docs/integrations/claude-code.mdx b/docs/integrations/claude-code.mdx index 8727de5d5..ad99f5c38 100644 --- a/docs/integrations/claude-code.mdx +++ b/docs/integrations/claude-code.mdx @@ -32,7 +32,7 @@ def roll_dice(n_dice: int) -> list[int]: return [random.randint(1, 6) for _ in range(n_dice)] if __name__ == "__main__": - mcp.run(transport="streamable-http", port=8000) + mcp.run(transport="http", port=8000) ``` ## Connect to Claude Code diff --git a/docs/integrations/openai.mdx b/docs/integrations/openai.mdx index fe3447dec..2d1940b9b 100644 --- a/docs/integrations/openai.mdx +++ b/docs/integrations/openai.mdx @@ -38,7 +38,7 @@ def roll_dice(n_dice: int) -> list[int]: return [random.randint(1, 6) for _ in range(n_dice)] if __name__ == "__main__": - mcp.run(transport="streamable-http", port=8000) + mcp.run(transport="http", port=8000) ``` ### Deploy the Server @@ -172,7 +172,7 @@ def roll_dice(n_dice: int) -> list[int]: if __name__ == "__main__": print(f"\n---\n\n🔑 Dice Roller access token:\n\n{access_token}\n\n---\n") - mcp.run(transport="streamable-http", port=8000) + mcp.run(transport="http", port=8000) ``` #### Client Authentication diff --git a/docs/patterns/cli.mdx b/docs/patterns/cli.mdx index 84654975b..9c01d133d 100644 --- a/docs/patterns/cli.mdx +++ b/docs/patterns/cli.mdx @@ -42,11 +42,12 @@ This command runs the server directly in your current Python environment. You ar | Option | Flag | Description | | ------ | ---- | ----------- | -| Transport | `--transport`, `-t` | Transport protocol to use (`stdio`, `streamable-http`, or `sse`) | +| Transport | `--transport`, `-t` | Transport protocol to use (`stdio`, `http`, or `sse`) | | Host | `--host` | Host to bind to when using http transport (default: 127.0.0.1) | | Port | `--port`, `-p` | Port to bind to when using http transport (default: 8000) | | Log Level | `--log-level`, `-l` | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | + #### Server Specification @@ -79,14 +80,14 @@ if __name__ == "__main__": You can run it with Streamable HTTP transport regardless of what's in the `__main__` block: ```bash -fastmcp run server.py --transport streamable-http --port 8000 +fastmcp run server.py --transport http --port 8000 ``` **Examples** ```bash # Run a local server with Streamable HTTP transport on a custom port -fastmcp run server.py --transport streamable-http --port 8000 +fastmcp run server.py --transport http --port 8000 # Connect to a remote server and proxy as a stdio server fastmcp run https://example.com/mcp-server @@ -112,14 +113,14 @@ The `dev` command is a shortcut for testing a server over STDIO only. When the I 1. Select "STDIO" from the transport dropdown 2. Connect manually -This command does not support HTTP testing. To test a server over HTTP: -1. Start your server manually with HTTP transport using either: +This command does not support HTTP testing. To test a server over Streamable HTTP or SSE: +1. Start your server manually with the appropriate transport using either the command line: ```bash - fastmcp run server.py --transport streamable-http + fastmcp run server.py --transport http ``` - or + or by setting the transport in your code: ```bash - python server.py # Assuming your __main__ block sets HTTP transport + python server.py # Assuming your __main__ block sets Streamable HTTP transport ``` 2. Open the MCP Inspector separately and connect to your running server diff --git a/docs/python-sdk/fastmcp-client-transports.mdx b/docs/python-sdk/fastmcp-client-transports.mdx index a4f9d22e6..08910b09c 100644 --- a/docs/python-sdk/fastmcp-client-transports.mdx +++ b/docs/python-sdk/fastmcp-client-transports.mdx @@ -168,11 +168,11 @@ Transport for connecting to one or more MCP servers defined in an MCPConfig. "mcpServers": { "weather": { "url": "https://weather-api.example.com/mcp", - "transport": "streamable-http" + "transport": "http" }, "calendar": { "url": "https://calendar-api.example.com/mcp", - "transport": "streamable-http" + "transport": "http" } } } diff --git a/docs/servers/auth/bearer.mdx b/docs/servers/auth/bearer.mdx index 900bebe5a..74344a02e 100644 --- a/docs/servers/auth/bearer.mdx +++ b/docs/servers/auth/bearer.mdx @@ -19,7 +19,7 @@ The [MCP specification](https://modelcontextprotocol.io/specification/2025-03-26 Bearer Token authentication is a common way to secure HTTP-based APIs. In this model, the client sends a token (usually a JSON Web Token or JWT) in the `Authorization` header with the "Bearer" scheme. The server then validates this token to grant or deny access. -FastMCP supports Bearer Token authentication for its HTTP-based transports (`streamable-http` and `sse`), allowing you to protect your server from unauthorized access. +FastMCP supports Bearer Token authentication for its HTTP-based transports (`http` and `sse`), allowing you to protect your server from unauthorized access. ## Authentication Strategy diff --git a/docs/servers/proxy.mdx b/docs/servers/proxy.mdx index 5a9bffccd..5ebff6a04 100644 --- a/docs/servers/proxy.mdx +++ b/docs/servers/proxy.mdx @@ -118,7 +118,7 @@ config = { "mcpServers": { "default": { # For single server configs, 'default' is commonly used "url": "https://example.com/mcp", - "transport": "streamable-http" + "transport": "http" } } } @@ -145,11 +145,11 @@ config = { "mcpServers": { "weather": { "url": "https://weather-api.example.com/mcp", - "transport": "streamable-http" + "transport": "http" }, "calendar": { "url": "https://calendar-api.example.com/mcp", - "transport": "streamable-http" + "transport": "http" } } } diff --git a/docs/servers/server.mdx b/docs/servers/server.mdx index 1cb5f089b..f8c4eda21 100644 --- a/docs/servers/server.mdx +++ b/docs/servers/server.mdx @@ -158,8 +158,8 @@ if __name__ == "__main__": # This runs the server, defaulting to STDIO transport mcp.run() - # To use a different transport, e.g., HTTP: - # mcp.run(transport="streamable-http", host="127.0.0.1", port=9000) + # To use a different transport, e.g., Streamable HTTP: + # mcp.run(transport="http", host="127.0.0.1", port=9000) ``` FastMCP supports several transport options: @@ -260,7 +260,7 @@ Transport settings are provided when running the server and control network beha ```python # Configure transport when running mcp.run( - transport="streamable-http", + transport="http", host="0.0.0.0", # Bind to all interfaces port=9000, # Custom port log_level="DEBUG", # Override global log level @@ -268,7 +268,7 @@ mcp.run( # Or for async usage await mcp.run_async( - transport="streamable-http", + transport="http", host="127.0.0.1", port=8080, ) diff --git a/docs/tutorials/rest-api.mdx b/docs/tutorials/rest-api.mdx index 1b6ae1288..cb1453644 100644 --- a/docs/tutorials/rest-api.mdx +++ b/docs/tutorials/rest-api.mdx @@ -82,7 +82,7 @@ mcp = FastMCP.from_openapi( ) if __name__ == "__main__": - mcp.run(transport="streamable-http", port=8000) + mcp.run(transport="http", port=8000) ``` And that's it! With just a few lines of code, you've created an MCP server that exposes the entire JSONPlaceholder API as a collection of tools. @@ -195,7 +195,7 @@ mcp = FastMCP.from_openapi( ) if __name__ == "__main__": - mcp.run(transport="streamable-http", port=8000) + mcp.run(transport="http", port=8000) ``` With this configuration: - `GET /users/{id}` becomes a `ResourceTemplate`. diff --git a/docs/updates.mdx b/docs/updates.mdx index 27f7afb39..5f2e8c708 100644 --- a/docs/updates.mdx +++ b/docs/updates.mdx @@ -107,7 +107,7 @@ img="https://www.jlowin.dev/_image?href=%2F_astro%2Fhero.M_hv6gEB.png&w=1000&h=5 cta="Read more" > -FastMCP 2.3 introduces full support for Streamable HTTP, a modern alternative to SSE that simplifies MCP deployments over the web. It’s efficient, reliable, and now the default HTTP transport. Just run your server with transport="streamable-http" and connect clients via a standard URL—FastMCP handles the rest. No special setup required. This release makes deploying MCP servers easier and more portable than ever. +FastMCP 2.3 introduces full support for Streamable HTTP, a modern alternative to SSE that simplifies MCP deployments over the web. It’s efficient, reliable, and now the default HTTP transport. Just run your server with transport="http" and connect clients via a standard URL—FastMCP handles the rest. No special setup required. This release makes deploying MCP servers easier and more portable than ever. diff --git a/tests/cli/test_cli.py b/tests/cli/test_cli.py index 4897cc6dd..a199a24c1 100644 --- a/tests/cli/test_cli.py +++ b/tests/cli/test_cli.py @@ -328,6 +328,41 @@ class TestRunCommand: assert result.exit_code == 0 mock_server.run.assert_called_once_with(transport="sse") + def test_run_command_with_http_transports(self, temp_python_file): + """Test run command with both http and streamable-http transport options.""" + # Test "http" transport + with ( + patch("fastmcp.cli.run.parse_file_path") as mock_parse, + patch("fastmcp.cli.run.import_server") as mock_import, + ): + mock_parse.return_value = (temp_python_file, None) + mock_server = MagicMock() + mock_server.name = "test_server" + mock_import.return_value = mock_server + + result = runner.invoke( + cli.app, ["run", str(temp_python_file), "--transport", "http"] + ) + assert result.exit_code == 0 + mock_server.run.assert_called_once_with(transport="http") + + # Test "streamable-http" transport (alias for http) + with ( + patch("fastmcp.cli.run.parse_file_path") as mock_parse, + patch("fastmcp.cli.run.import_server") as mock_import, + ): + mock_parse.return_value = (temp_python_file, None) + mock_server = MagicMock() + mock_server.name = "test_server" + mock_import.return_value = mock_server + + result = runner.invoke( + cli.app, + ["run", str(temp_python_file), "--transport", "streamable-http"], + ) + assert result.exit_code == 0 + mock_server.run.assert_called_once_with(transport="streamable-http") + def test_run_command_with_host(self, temp_python_file): """Test run command with host option.""" with ( diff --git a/tests/client/test_streamable_http.py b/tests/client/test_streamable_http.py index 858c8f285..3fec43f82 100644 --- a/tests/client/test_streamable_http.py +++ b/tests/client/test_streamable_http.py @@ -110,6 +110,7 @@ async def streamable_http_server( yield f"{url}/mcp/" +@pytest.fixture() async def streamable_http_server_with_streamable_http_alias() -> AsyncGenerator[ str, None ]: @@ -216,3 +217,41 @@ class TestTimeout: ) as client: with pytest.raises(McpError): await client.call_tool("sleep", {"seconds": 0.2}, timeout=0.1) + + +async def test_fastmcp_run_with_streamable_http_alias(): + """Test that FastMCP.run() works with 'streamable-http' transport alias.""" + server = fastmcp_server() + + # This should work without error - testing that the alias is recognized + import threading + import time + + def run_server(): + try: + server.run(transport="streamable-http", port=0, log_level="error") + except Exception: + # Expected to fail when port is 0, but we're just testing the transport parsing + pass + + # Run in a separate thread briefly to test transport argument parsing + thread = threading.Thread(target=run_server, daemon=True) + thread.start() + time.sleep(0.1) # Give it a moment to start and parse arguments + # Thread will exit naturally when the function completes + + +async def test_fastmcp_run_async_with_streamable_http_alias(): + """Test that FastMCP.run_async() works with 'streamable-http' transport alias.""" + server = fastmcp_server() + + # Test that run_async accepts the streamable-http alias + try: + # Use a timeout to prevent hanging + await asyncio.wait_for( + server.run_async(transport="streamable-http", port=0, log_level="error"), + timeout=0.1, + ) + except (asyncio.TimeoutError, Exception): + # Expected to fail/timeout, but we're testing that the transport is accepted + pass