Add Streamable HTTP Transport to MCPServerHTTP #1905

BrandonShar · 2025-06-04T00:03:51Z

Unfortunately for #1716, it turns out the underlying library was not backwards compatible.

This re-implementation adds a param to allow the user to specify what type of server they're connecting to.

Note: I considered adding an auto option (and that still may be a good idea), but I thought i'd keep it simple for the ~~first~~ attempt at this.

Fixes #1632

hyperlint-ai · 2025-06-04T00:04:08Z

PR Change Summary

Re-implemented Streamable HTTP Transport as an opt-in feature, allowing users to specify the server type when connecting.

Added support for Streamable HTTP transport in MCPServerHTTP
Updated documentation to reflect the new transport option
Modified example code to include transport parameter
Clarified usage instructions for defining the MCP server

Modified Files

docs/mcp/client.md

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

BrandonShar · 2025-06-04T00:04:20Z

pydantic_ai_slim/pydantic_ai/mcp.py

@@ -358,22 +357,38 @@ async def main():
    For example, if `tool_prefix='foo'`, then a tool named `bar` will be registered as `foo_bar`
    """

+    transport: Literal['sse', 'streamable-http'] = 'sse'


These arguments match the underlying terms that FastMCP uses

If you have a chance, could you see if it would be easy to implement an 'auto' option that still defaults to SSE for backward compatibility, but switches to streamable-http when the path is /mcp?

BrandonShar · 2025-06-04T00:04:42Z

tests/test_mcp.py

+
+
+@pytest.fixture
+def mcp_server(request: pytest.FixtureRequest):


this feels complex, but I couldn't figure out a simpler way.

BrandonShar · 2025-06-04T00:05:09Z

tests/test_mcp.py

@@ -31,7 +36,6 @@
 pytestmark = [
    pytest.mark.skipif(not imports_successful(), reason='mcp and openai not installed'),
    pytest.mark.anyio,
-    pytest.mark.vcr,


calling this out, I think all VCR tests are marked individually, but something about this blocked not the initial connection but the subsequent calls within the server.

No, this is correct. You need to use --record-mode=rewrite when running the first time for the first test.

BrandonShar · 2025-06-04T02:58:23Z

I am confused about the test failure. Seems like a dependency issue maybe just in CI? I hate to say the tests pass on my machine, but... 😄

DouweM · 2025-06-10T21:02:19Z

docs/mcp/client.md

@@ -18,22 +18,19 @@ pip/uv-add "pydantic-ai-slim[mcp]"

 PydanticAI comes with two ways to connect to MCP servers:

- [`MCPServerHTTP`][pydantic_ai.mcp.MCPServerHTTP] which connects to an MCP server using the [HTTP SSE](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse) transport
+- [`MCPServerHTTP`][pydantic_ai.mcp.MCPServerHTTP] which connects to an MCP server using the [HTTP SSE](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse) or [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport


Suggested change

- [`MCPServerHTTP`][pydantic_ai.mcp.MCPServerHTTP] which connects to an MCP server using the [HTTP SSE](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse) or [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport

- [`MCPServerHTTP`][pydantic_ai.mcp.MCPServerHTTP] which connects to an MCP server using the [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) or older [HTTP SSE](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse) transport

DouweM · 2025-06-10T21:02:32Z

docs/mcp/client.md

 - [`MCPServerStdio`][pydantic_ai.mcp.MCPServerStdio] which runs the server as a subprocess and connects to it using the [stdio](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#stdio) transport

 Examples of both are shown below; [mcp-run-python](run-python.md) is used as the MCP server in both examples.

-### SSE Client
+### SSE or Streamable HTTP Client


Suggested change

### SSE or Streamable HTTP Client

### HTTP Client

DouweM · 2025-06-10T21:03:09Z

docs/mcp/client.md


-[`MCPServerHTTP`][pydantic_ai.mcp.MCPServerHTTP] connects over HTTP using the [HTTP + Server Sent Events transport](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse) to a server.
+[`MCPServerHTTP`][pydantic_ai.mcp.MCPServerHTTP] connects over HTTP using the [HTTP + Server Sent Events transport](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse) or the [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) to a server.


Suggested change

[`MCPServerHTTP`][pydantic_ai.mcp.MCPServerHTTP] connects over HTTP using the [HTTP + Server Sent Events transport](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse) or the [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) to a server.

[`MCPServerHTTP`][pydantic_ai.mcp.MCPServerHTTP] connects to a server over HTTP using [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) or [HTTP + Server Sent Events](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse).

DouweM · 2025-06-10T21:04:58Z

docs/mcp/client.md

-[Streamable HTTP](https://github.com/modelcontextprotocol/specification/pull/206) currently in development.
-
-Before creating the SSE client, we need to run the server (docs [here](run-python.md)):
+Before creating the client, we need to run the server (docs [here](run-python.md)):


Suggested change

Before creating the client, we need to run the server (docs [here](run-python.md)):

For backwards compatibility, the default transport is SSE. If your server instead uses Streamable HTTP, you have to specify the `transport='streamable-http'` option when creating `MCPServerHTTP`.

Before creating the client, we need to run the server (docs [here](run-python.md)):

DouweM · 2025-06-10T21:05:41Z

docs/mcp/client.md

@@ -84,6 +81,10 @@ Will display as follows:

 ![Logfire run python code](../img/logfire-run-python-code.png)

+#### Transport
+
+`MCPServerHTTP` supports both SSE (`sse`) and Streamable HTTP (`streamable-http`) servers which can be specified via the `transport` parameter.


I think we can drop this section as I suggested mentioning the transport arg above.

It'd be nice if we could also have a Streamable HTTP example!

DouweM · 2025-06-10T21:10:34Z

tests/test_mcp.py

+@pytest.fixture
+def mcp_server(request: pytest.FixtureRequest):
+    proc = multiprocessing.Process(target=request.param, daemon=True)
+    print('Staring streamable http server process on port port')


Suggested change

print('Staring streamable http server process on port port')

DouweM · 2025-06-10T21:10:40Z

tests/test_mcp.py

+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.connect(('localhost', 8000))
+                print('MCP server started.')


Suggested change

print('MCP server started.')

DouweM · 2025-06-10T21:12:25Z

tests/test_mcp.py

+
+
+def run_streamable_http_server() -> None:
+    """Run the SSE MCP Server"""


Suggested change

"""Run the SSE MCP Server"""

"""Run the Streamable HTTP MCP Server"""

DouweM · 2025-06-10T21:12:29Z

tests/test_mcp.py

@@ -42,6 +46,71 @@ def agent(openai_api_key: str):
    return Agent(model, mcp_servers=[server])


+def run_sse_server() -> None:
+    """Run the Streamable HTTP MCP server."""


Suggested change

"""Run the Streamable HTTP MCP server."""

"""Run the SSE MCP server."""

DouweM · 2025-06-10T21:12:51Z

tests/test_mcp.py

+    while attempt < max_attempts:
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.connect(('localhost', 8000))


We should use a randomly assigned port here, we can't be sure 8000 will be available

It looks like FastMCP has its own host and port settings, and the run method runs the entire server. Do we need to run it in a separate process at all? Could we use a thread? It looks like FastMCP.run calls anyio.run(self.run_sse_async). We could likely do something ourselves to run the run_sse_async async method in a thread.

DouweM · 2025-06-10T21:17:28Z

@BrandonShar Thanks for submitting this! Finally got around to reviewing it :)

It looks like you're trying to use a newer version of mcp, could you please update pyproject.toml as well? That may resolve the CI issue.

Kludex · 2025-06-12T13:48:38Z

tests/test_mcp.py

@@ -31,7 +36,6 @@
 pytestmark = [
    pytest.mark.skipif(not imports_successful(), reason='mcp and openai not installed'),
    pytest.mark.anyio,
-    pytest.mark.vcr,


No, this is correct. You need to use --record-mode=rewrite when running the first time for the first test.

Kludex · 2025-06-12T13:49:29Z

I forgot about this PR and implemented Add MCP Streamable HTTP implementation #1965

I'm not sure which PR should go though.

Kludex · 2025-06-13T08:36:51Z

Let's go with Add MCP Streamable HTTP implementation #1965.

I think we'll be adding a lot more stuff on the streaming implementation, so I think it's preferable to have those 2 classes.

Kludex · 2025-06-13T08:36:59Z

But thanks for the PR. 🙏

Add back streamable http as an opt in

069f99d

BrandonShar commented Jun 4, 2025

View reviewed changes

BrandonShar mentioned this pull request Jun 4, 2025

Streamable HTTP Implementaion #1632

Closed

RRRajput mentioned this pull request Jun 10, 2025

Do you have plans to support Streamable HTTP transmission functionality? When is it expected to be officially released? #1952

Closed

DouweM requested changes Jun 10, 2025

View reviewed changes

DouweM self-assigned this Jun 10, 2025

DouweM added the awaiting author revision label Jun 10, 2025

Kludex requested changes Jun 12, 2025

View reviewed changes

DouweM changed the title ~~Add back Streamable HTTP Transport as an opt-in~~ Add Streamable HTTP Transport to MCPServerHTTP Jun 12, 2025

Kludex closed this Jun 13, 2025



		@pytest.fixture
		def mcp_server(request: pytest.FixtureRequest):

	- [`MCPServerHTTP`][pydantic_ai.mcp.MCPServerHTTP] which connects to an MCP server using the [HTTP SSE](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse) or [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport
	- [`MCPServerHTTP`][pydantic_ai.mcp.MCPServerHTTP] which connects to an MCP server using the [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) or older [HTTP SSE](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse) transport


		[`MCPServerHTTP`][pydantic_ai.mcp.MCPServerHTTP] connects over HTTP using the [HTTP + Server Sent Events transport](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse) to a server.
		[`MCPServerHTTP`][pydantic_ai.mcp.MCPServerHTTP] connects over HTTP using the [HTTP + Server Sent Events transport](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse) or the [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) to a server.



		def run_streamable_http_server() -> None:
		"""Run the SSE MCP Server"""

	"""Run the SSE MCP Server"""
	"""Run the Streamable HTTP MCP Server"""

	"""Run the Streamable HTTP MCP server."""
	"""Run the SSE MCP server."""

Add Streamable HTTP Transport to MCPServerHTTP #1905

Add Streamable HTTP Transport to MCPServerHTTP #1905

Uh oh!

Conversation

BrandonShar commented Jun 4, 2025 • edited by DouweM Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hyperlint-ai bot commented Jun 4, 2025

PR Change Summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BrandonShar commented Jun 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DouweM commented Jun 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kludex commented Jun 12, 2025

Uh oh!

Kludex commented Jun 13, 2025

Uh oh!

Kludex commented Jun 13, 2025

Uh oh!

Uh oh!

BrandonShar commented Jun 4, 2025 •

edited by DouweM

Loading