feat: add url_prefix support to FastMCP SSE

[pridkett]

Previously the paths for SSE were hardcoded to /sse and /messages this made it hard to run behind an API gateway. Requests to the /sse endpoint, even if proxied properly, would return /messages for the location of the /messages endpoint even if it should've been /api/v1/my_mcp_server/messages. This brings in a new parameter to FastMCP, url_prefix, that allows you set a prefix of something such as /api/v1/my_mcp_server and have the serve function properly. This can be passed either on the FastMCP constructor or with the environment variable FASTMCP_URL_PREFIX.

DCO-1.1 Signed-off-by: Patrick Wagstrom [email protected]

Motivation and Context

There are situations when you may want something like an API Gateway to front multiple MCP servers, in this case they can't all serve the endpoints of /sse and /messages, but unfortunately, those were hardcoded. An because of the way that the connection is kept open on /sse, you can't always use body rewrite features inside of the API gateway to change the URLs.

How Has This Been Tested?

I created, with the assistance of Claude, tests/server/fastmcp/test_url_prefix.py which covers most of the tests. I've also tested this locally with my API gateway and observed that it works.

Breaking Changes

None observed

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

On the last one, if the other environment variables like FASTMCP_HOST and FASTMCP_PORT had a spot in the documentation, I'd add FASTMCP_URL_PREFIX next to them, but I didn't see where that might be.

Additional context

Without this, it still is possible to run multiple MCP servers behind an API gateway, but you need to run them in stdio mode and use Supergateway with the --ssePath and --messagePath flags set.

[pridkett]

This is pretty similar to #246 - I'll let the maintainers figure out if we should do this with url_prefix or use sse_path/message_path as in #246.