Support for API Gateway Path Prefixes in SSE Client URL Handling

[lizzzcai]

Is your feature request related to a problem? Please describe.

When using the client SDK to connect MCP server behind an API gateway that adds a deployment-specific prefix (e.g., /gateway_prefix/<deployment_name>), the backend mcp server is unaware of this prefix and only exposes routes like /v1/sse and /v1/messages. The client SDK currently only supports url and uses urljoin to resolve endpoint URLs, which causes the gateway prefix to be dropped when joining paths that start with /. This results in incorrect routing through the gateway.

debug logs:

❯ python3 client.py
DEBUG:asyncio:Using selector: KqueueSelector
INFO:mcp.client.sse:Connecting to SSE endpoint: https://example.com/gateway_prefix/<deployment_name>/v1/sse
DEBUG:httpcore.connection:connect_tcp.started host='https://example.com' port=443 local_address=None timeout=5 socket_options=None
DEBUG:httpcore.connection:connect_tcp.complete return_value=<httpcore._backends.anyio.AnyIOStream object at 0x10889fef0>
DEBUG:httpcore.connection:start_tls.started ssl_context=<ssl.SSLContext object at 0x10895ca50> server_hostname='example.com' timeout=5
DEBUG:httpcore.connection:start_tls.complete return_value=<httpcore._backends.anyio.AnyIOStream object at 0x107fb45c0>
DEBUG:httpcore.http11:send_request_headers.started request=<Request [b'GET']>
DEBUG:httpcore.http11:send_request_headers.complete
DEBUG:httpcore.http11:send_request_body.started request=<Request [b'GET']>
DEBUG:httpcore.http11:send_request_body.complete
DEBUG:httpcore.http11:receive_response_headers.started request=<Request [b'GET']>
DEBUG:httpcore.http11:receive_response_headers.complete return_value=(b'HTTP/1.1', 200, b'OK', [(b'cache-control', b'no-store'), (b'content-type', b'text/event-stream; charset=utf-8'), (b'date', b'Fri, 23 May 2025 15:45:20 GMT'), (b'x-accel-buffering', b'no'), (b'x-upstream-service-time', b'7'), (b'transfer-encoding', b'chunked')])
INFO:httpx:HTTP Request: GET https://example.com/gateway_prefix/<deployment_name>/v1/sse "HTTP/1.1 200 OK" <== correct sse endpoint
DEBUG:mcp.client.sse:SSE connection established
DEBUG:httpcore.http11:receive_response_body.started request=<Request [b'GET']>
DEBUG:mcp.client.sse:Received SSE event: endpoint
DEBUG:mcp.client.sse:urljoin: https://example.com/gateway_prefix/<deployment_name>/v1/sse + /v1/messages/?session_id=80b1237100a34eaa9795a5993661c76a <== wrong messages endpoint
INFO:mcp.client.sse:Received endpoint URL: https://example.com/v1/messages/?session_id=80b1237100a34eaa9795a5993661c76a
INFO:mcp.client.sse:Starting post writer with endpoint URL: https://example.com/v1/messages/?session_id=80b1237100a34eaa9795a5993661c76a

Describe the solution you'd like
The client SDK should preserve the gateway prefix when joining endpoint URLs, so that requests are routed correctly through the gateway. Ideally, the SDK should provide a way to configure or detect the gateway prefix and ensure all endpoint URLs are constructed with it.

Describe alternatives you've considered

Additional context

Example:

url = "https://example.com/gateway_prefix/<deployment_name>/v1/sse"
path = "/v1/messages"
urljoin(url, path)
# Actual:   https://example.com/v1/messages
# Expected: https://example.com/gateway_prefix/<deployment_name>/v1/messages

This is a common pattern for API gateways and reverse proxies, so supporting this would improve compatibility.

similar request:
#412 (comment)
#733
#386