feat: router proxy with streamable http server by default

Author: JoJoJoJoJoJoJo

README.md

@@ -94,7 +94,7 @@ mcpm add SERVER_URL --alias ALIAS # Add with a custom alias
 
 # 🛠️ Add custom server
 mcpm import stdio SERVER_NAME --command COMMAND --args ARGS --env ENV # Add a stdio MCP server to a client
-mcpm import sse SERVER_NAME --url URL # Add a SSE MCP server to a client
+mcpm import remote SERVER_NAME --url URL # Add a remote MCP server to a client
 mcpm import interact # Add a server by configuring it interactively
 
 # 📋 List and Remove

README.zh-CN.md

@@ -128,7 +128,7 @@ mcpm add SERVER_URL --alias ALIAS # 添加并使用自定义别名
 
 # 🛠️ 自定义添加
 mcpm import stdio SERVER_NAME --command COMMAND --args ARGS --env ENV # 手动添加一个 stdio MCP 服务器
-mcpm import sse SERVER_NAME --url URL # 手动添加一个 SSE MCP 服务器
+mcpm import remote SERVER_NAME --url URL # 手动添加一个 remote MCP 服务器
 mcpm import interact # 通过交互式添加一个服务器
 
 # 📋 列出和删除

docs/advanced_features.md

@@ -91,9 +91,9 @@ The router prefixes capabilities from different servers to avoid conflicts:
 - Resources: `webfetch:https://example.com`
 
 #### 4. Server Connections
-The router supports both STDIO (command-line) and SSE (HTTP) server connections. For example:
+The router supports both STDIO (command-line) and Remote (HTTP and SSE) server connections. For example:
 - STDIO: Python Interpreter, Blender
-- SSE: Web Search, Notion, Slack
+- Remote: Web Search, Notion, Slack
 
 #### 5. Shared Server Sessions
 The router maintains persistent connections to all configured servers, allowing multiple clients to share the same server sessions. This means:
@@ -105,9 +105,9 @@ The router maintains persistent connections to all configured servers, allowing
 ## Features
 
 - Aggregate multiple MCP servers as a single server
-- Support both SSE and STDIO connections to underlying servers
+- Support both Remote and STDIO connections to underlying servers
 - Namespace capabilities from different servers
-- Expose a unified SSE server interface
+- Expose a unified Remote server interface
 - Profile-based server access control
 - Dynamic configuration reloading
 - Share server connections among multiple clients (no need for separate server instances per client)

docs/router_tech_design.md

@@ -49,7 +49,7 @@ flowchart TB
 ```python
 import asyncio
 from mcpm.router import MCPRouter
-from mcpm.core.schema import STDIOServerConfig, SSEServerConfig
+from mcpm.core.schema import STDIOServerConfig, RemoteServerConfig
 
 async def main():
     # Create a router
@@ -64,16 +64,16 @@ async def main():
         )
     )
 
-    # Add an SSE server
+    # Add an Remote server
     await router.add_server(
         "example2",
-        SSEServerConfig(
-            url="http://localhost:3000/sse"
+        RemoteServerConfig(
+            url="http://localhost:3000/"
         )
     )
 
-    # Start the SSE server
-    await router.start_sse_server(host="localhost", port=8080)
+    # Start the Remote server
+    await router.start_remote_server(host="localhost", port=8080)
 
 if __name__ == "__main__":
     asyncio.run(main())
@@ -99,11 +99,11 @@ The main orchestrator class that provides a unified API for the application:
 
 Manages individual connections to downstream MCP servers:
 - Handles connection lifecycle for a single server
-- Supports different transport types (STDIO, SSE)
+- Supports different transport types (STDIO, Remote)
 - Provides methods to initialize, check health, and gracefully shut down connections
 - Exposes the server's capabilities to the router
 
-### `RouterSseTransport`
+### `RouterSseTransport` (deprecated)
 
 Extends the SSE server transport to handle client connections:
 - Provides an SSE server endpoint for clients to connect
@@ -130,7 +130,7 @@ Monitors configuration changes:
 Defines the configuration for connecting to downstream servers:
 - Base `ServerConfig` class with common properties
 - `STDIOServerConfig` for command-line based servers
-- `SSEServerConfig` for HTTP/SSE based servers
+- `RemoteServerConfig` for HTTP/SSE based servers
 - Stores necessary connection parameters (command, args, env, URL)
 
 ## Namespacing
@@ -148,19 +148,19 @@ This allows the router to route requests to the appropriate server based on the
 
 ### Downstream Connections (Router as Client)
 
-1. Router creates persistent connections to downstream MCP servers using STDIO or SSE
+1. Router creates persistent connections to downstream MCP servers using STDIO or remote (Streamable HTTP/SSE)
 2. Connections are maintained regardless of upstream client presence
 3. Server capabilities are fetched and aggregated with namespacing
 4. Connections are managed through the `ServerConnection` class
 5. Notifications from servers are routed to appropriate upstream clients
 
 ### Upstream Connections (Router as Server)
 
-1. Router provides an SSE server interface for upstream clients
+1. Router provides an streamable HTTP server interface for upstream clients
 2. Clients connect with a profile identifier to determine server visibility
 3. Client requests are routed to appropriate downstream servers based on profile
 4. Responses and notifications are delivered back to clients
-5. Session management is handled by `RouterSseTransport`
+5. Session management is handled by `RouterSseTransport`(deprecated)
 
 ## Request Routing and Namespacing
 
@@ -202,7 +202,7 @@ sequenceDiagram
 1. **Decoupling**: Upstream clients are decoupled from downstream servers
 2. **Resilience**: Client disconnections don't affect server connections
 3. **Aggregation**: Multiple capabilities from different servers appear as one
-4. **Flexibility**: Supports different transport protocols (STDIO, SSE)
+4. **Flexibility**: Supports different transport protocols (STDIO, Remote)
 5. **Scalability**: Can manage multiple clients and servers simultaneously
 6. **Profile-based Access**: Controls which servers are available to which clients
 7. **Dynamic Configuration**: Supports runtime changes to server configurations

pyproject.toml

@@ -7,7 +7,7 @@ name = "mcpm"
 dynamic = ["version"]
 description = "MCPM - Model Context Protocol Manager"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 license = "MIT"
 authors = [{ name = "MCPM Contributors" }]
 maintainers = [{ name = "Path Integral Institute" }]
@@ -30,6 +30,7 @@ dependencies = [
     "duckdb>=1.2.2",
     "psutil>=7.0.0",
     "prompt-toolkit>=3.0.0",
+    "deprecated>=1.2.18",
 ]
 
 [project.urls]

src/mcpm/clients/managers/claude_desktop.py

@@ -7,7 +7,7 @@
 from typing import Any, Dict
 
 from mcpm.clients.base import JSONClientManager
-from mcpm.core.schema import ServerConfig, SSEServerConfig
+from mcpm.core.schema import RemoteServerConfig, ServerConfig
 from mcpm.utils.router_server import format_server_url_with_proxy_headers
 
 logger = logging.getLogger(__name__)
@@ -117,7 +117,7 @@ def _format_router_server(self, profile_name, base_url) -> ServerConfig:
         return format_server_url_with_proxy_headers(self.client_key, profile_name, base_url)
 
     def to_client_format(self, server_config: ServerConfig) -> Dict[str, Any]:
-        if isinstance(server_config, SSEServerConfig):
+        if isinstance(server_config, RemoteServerConfig):
             # use mcp proxy to convert to stdio as sse is not supported for claude desktop yet
             return self.to_client_format(server_config.to_mcp_proxy_stdio())
         return super().to_client_format(server_config)

src/mcpm/commands/router.py

@@ -17,7 +17,7 @@
 
 from mcpm.clients.client_registry import ClientRegistry
 from mcpm.router.share import Tunnel
-from mcpm.utils.config import ConfigManager
+from mcpm.utils.config import MCPM_AUTH_HEADER, MCPM_PROFILE_HEADER, ConfigManager
 from mcpm.utils.platform import get_log_directory, get_pid_directory
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
@@ -116,8 +116,9 @@ def router():
 
 @router.command(name="on")
 @click.help_option("-h", "--help")
+@click.option("--sse", "-s", is_flag=True, help="Use SSE endpoint(deprecated)")
 @click.option("--verbose", "-v", is_flag=True, help="Enable verbose output")
-def start_router(verbose):
+def start_router(sse, verbose):
     """Start MCPRouter as a daemon process.
 
     Example:
@@ -140,12 +141,17 @@ def start_router(verbose):
     auth_enabled = config.get("auth_enabled", False)
     api_key = config.get("api_key")
 
+    if sse:
+        app_path = "mcpm.router.sse_app:app"
+    else:
+        app_path = "mcpm.router.app:app"
+
     # prepare uvicorn command
     uvicorn_cmd = [
         sys.executable,
         "-m",
         "uvicorn",
-        "mcpm.router.app:app",
+        app_path,
         "--host",
         host,
         "--port",
@@ -197,17 +203,29 @@ def start_router(verbose):
 
         api_key = api_key if auth_enabled else None
 
-        # Show URL with or without authentication based on API key availability
-        if api_key:
-            # Show authenticated URL
-            console.print(f"SSE Server URL: [green]http://{host}:{port}/sse?s={api_key}[/]")
-            console.print("\n[bold cyan]To use a specific profile with authentication:[/]")
-            console.print(f"[green]http://{host}:{port}/sse?s={api_key}&profile=<profile_name>[/]")
+        if sse:
+            console.print("\n[bold yellow]SSE router is not recommended[/]")
+            console.print(f"Remote Server URL: [green]http://{host}:{port}/sse[/]")
+            if api_key:
+                console.print("\n[bold cyan]To use a specific profile with authentication:[/]")
+                console.print(
+                    f"Remote Server URL with authentication: [green]http://{host}:{port}/sse?s={api_key}&profile=<profile_name>[/]"
+                )
+            else:
+                console.print("\n[bold cyan]To use a specific profile:[/]")
+                console.print(
+                    f"Remote Server URL with authentication: [green]http://{host}:{port}/sse?profile=<profile_name>[/]"
+                )
         else:
-            # Show URL without authentication
-            console.print(f"SSE Server URL: [green]http://{host}:{port}/sse[/]")
-            console.print("\n[bold cyan]To use a specific profile:[/]")
-            console.print(f"[green]http://{host}:{port}/sse?profile=<profile_name>[/]")
+            console.print(f"Remote Server URL: [green]http://{host}:{port}/mcp/[/]")
+            if api_key:
+                console.print("\n[bold cyan]To use a specific profile with authentication:[/]")
+                console.print("[bold]Request headers:[/]")
+                console.print(f"{MCPM_AUTH_HEADER}: {api_key}")
+            else:
+                console.print("\n[bold cyan]To use a specific profile:[/]")
+                console.print("[bold]Request headers:[/]")
+            console.print(f"{MCPM_PROFILE_HEADER}: <profile_name>")
 
         console.print("\n[yellow]Use 'mcpm router off' to stop the router.[/]")
 
@@ -432,16 +450,18 @@ def share(address, profile, http):
     share_url = tunnel.start_tunnel()
     share_pid = tunnel.proc.pid if tunnel.proc else None
     api_key = config.get("api_key") if config.get("auth_enabled") else None
-    share_url = share_url + "/sse"
+
+    share_url = share_url + "/mcp/"
     # save share pid and link to config
     config_manager.save_share_config(share_url, share_pid)
     profile = profile or "<your_profile>"
 
     # print share link
     console.print(f"[bold green]Router is sharing at {share_url}[/]")
-    console.print(
-        f"[green]Your profile can be accessed with the url {share_url}?{f's={api_key}&' if api_key else ''}profile={profile}[/]\n"
-    )
+    console.print(f"[green]Your profile can be accessed with the url {share_url}[/]\n")
+    if api_key:
+        console.print(f"[green]Authorize with header {MCPM_AUTH_HEADER}: {api_key}[/]")
+    console.print(f"[green]Specify profile with header {MCPM_PROFILE_HEADER}: {profile}[/]")
     console.print(
         "[bold yellow]Be careful about the share link, it will be exposed to the public. Make sure to share to trusted users only.[/]"
     )

src/mcpm/commands/target.py

@@ -56,10 +56,6 @@ def set_target(target):
             console.print(f"[bold green]Success:[/] Active client set to {scope}")
     else:
         # Set the active profile
-        active_profile = ClientRegistry.get_active_target()
-        if active_profile:
-            console.print(f"[bold green]Success:[/] Active profile set to {active_profile}")
-
         profiles = ProfileConfigManager().list_profiles()
         if scope not in profiles:
             console.print(f"[bold red]Error:[/] Unknown profile: {scope}")

src/mcpm/commands/target_operations/custom.py

@@ -5,7 +5,7 @@
 from rich.prompt import Confirm, Prompt
 
 from mcpm.commands.target_operations.common import client_add_server, determine_scope, profile_add_server
-from mcpm.core.schema import SSEServerConfig, STDIOServerConfig
+from mcpm.core.schema import RemoteServerConfig, STDIOServerConfig
 from mcpm.utils.display import print_server_config
 from mcpm.utils.scope import ScopeType
 
@@ -83,12 +83,12 @@ def stdio(server_name, command, args, env, target, force):
 @click.option("--target", "-t", help="Target to import server to")
 @click.option("--force", is_flag=True, help="Force reinstall if server is already installed")
 @click.help_option("-h", "--help")
-def sse(server_name, url, header, target, force):
+def remote(server_name, url, header, target, force):
     """Add a server by specifying a URL and headers.
     Examples:
 
     \b
-        mcpm import sse <server_name> --url <url> --header <key1>=<value1> --header <key2>=<value2>
+        mcpm import remote <server_name> --url <url> --header <key1>=<value1> --header <key2>=<value2>
     """
     scope_type, scope = determine_scope(target)
     if not scope:
@@ -103,7 +103,7 @@ def sse(server_name, url, header, target, force):
             console.print(f"[yellow]Ignoring invalid header: {item}[/]")
 
     try:
-        server_config = SSEServerConfig(
+        server_config = RemoteServerConfig(
             name=server_name,
             url=url,
             headers=headers,
@@ -123,9 +123,9 @@ def sse(server_name, url, header, target, force):
         success = profile_add_server(scope, server_config, force)
 
     if success:
-        console.print(f"[bold green]SSE server '{server_name}' added successfully to {scope_type} {scope}.")
+        console.print(f"[bold green]Remote server '{server_name}' added successfully to {scope_type} {scope}.")
     else:
-        console.print(f"[bold red]Failed to add SSE server '{server_name}' to {scope_type} {scope}.")
+        console.print(f"[bold red]Failed to add remote server '{server_name}' to {scope_type} {scope}.")
 
 
 @import_server.command()
@@ -142,7 +142,7 @@ def interact(target: str | None = None):
         console.print("[red]Server name cannot be empty.[/]")
         return
 
-    config_type = Prompt.ask("Select server type", choices=["stdio", "sse"], default="stdio")
+    config_type = Prompt.ask("Select server type", choices=["stdio", "remote"], default="stdio")
 
     if config_type == "stdio":
         command = Prompt.ask("Enter command (executable)")
@@ -166,8 +166,8 @@ def interact(target: str | None = None):
         except ValueError as e:
             console.print(f"[bold red]Error:[/] {e}")
             return
-    elif config_type == "sse":
-        url = Prompt.ask("Enter SSE server URL")
+    elif config_type == "remote":
+        url = Prompt.ask("Enter remote server URL")
         headers_input = Prompt.ask("Enter HTTP headers (format: KEY=VAL, comma-separated, optional)", default="")
         headers = {}
         if headers_input.strip():
@@ -176,7 +176,7 @@ def interact(target: str | None = None):
                     k, v = pair.split("=", 1)
                     headers[k.strip()] = v.strip()
         try:
-            server_config = SSEServerConfig(
+            server_config = RemoteServerConfig(
                 name=server_name,
                 url=url,
                 headers=headers,

src/mcpm/core/schema.py

@@ -53,7 +53,7 @@ def get_filtered_env_vars(self, env: Dict[str, str]) -> Dict[str, str]:
         return filtered_env
 
 
-class SSEServerConfig(BaseServerConfig):
+class RemoteServerConfig(BaseServerConfig):
     url: str
     headers: Dict[str, Any] = {}
 
@@ -75,7 +75,7 @@ def to_mcp_proxy_stdio(self) -> STDIOServerConfig:
         )
 
 
-ServerConfig = Union[STDIOServerConfig, SSEServerConfig]
+ServerConfig = Union[STDIOServerConfig, RemoteServerConfig]
 
 
 class Profile(BaseModel):