Skip to content

feature: add --transport CLI flag (stdio/sse/streamable-http) for containerized deployments #59

Description

Context

paper_search_mcp/server.py:main() calls mcp.run(transport="stdio") unconditionally. Works cleanly for stdio subprocess consumers (Claude Desktop, Cursor, Claude Code skill).

Problem

Consumers that run the MCP as a networked service cannot use it directly:

  • Container deployments behind HTTP/SSE MCP gateways (agentgateway, Docker MCP gateway's HTTP route, ToolHive)
  • Kubernetes deployments where the backend is reached via a Service, not a forked subprocess
  • Remote MCP scenarios where the MCP lifecycle isn't owned by the client

The current workaround is an extra container running sparfenyuk/mcp-proxy to bridge stdio↔HTTP.

Proposal

Add CLI args to main(), preserving stdio as default. Sketch:

import argparse
from mcp.server.fastmcp import FastMCP
# ... existing imports ...

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--transport", choices=["stdio", "sse", "streamable-http"], default="stdio")
    parser.add_argument("--host", default="127.0.0.1")
    parser.add_argument("--port", type=int, default=8000)
    parser.add_argument("--path", default="/mcp")
    args = parser.parse_args()

    # host/port/path are init-time settings on FastMCP v1.x (mcp>=1.8.0)
    mcp = FastMCP(
        "paper_search_server",
        host=args.host,
        port=args.port,
        streamable_http_path=args.path,
    )
    # ... existing tool registrations ...
    mcp.run(transport=args.transport)

Requires bumping the mcp[cli] floor from >=1.6.0 to >=1.8.0 (streamable-http transport landed in v1.8.0).

Precedent

--transport {stdio,sse,streamable-http} is the emerging convention for multi-transport MCP servers — used by FastMCP's own CLI (fastmcp run --transport ...), Grafana, Notion, and mcp-atlassian, plus client-side in Claude Code (claude mcp add --transport ...), Gemini CLI, and ToolHive. Not universal (many servers remain stdio-only), but the clearest shared shape.

Backward compatibility

Happy to submit a PR if this would be accepted.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions