Add support for MCP servers #1100

Kludex · 2025-03-11T19:22:49Z

No description provided.

hyperlint-ai · 2025-03-11T19:23:09Z

PR Change Summary

Added support for MCP (Model Control Protocol) servers, enhancing integration capabilities for external services.

Introduced documentation for MCP servers integration.
Provided installation instructions for MCP support.
Included usage examples for HTTP/SSE and stdio-based servers.
Demonstrated how to connect to multiple MCP servers simultaneously.

Added Files

docs/api/mcp.md
docs/mcp_servers.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.

What is Hyperlint?

Hyperlint is an AI agent that helps you write, edit, and maintain your documentation.

Learn more about the Hyperlint AI reviewer and the checks that we can run on your documentation.

Kludex · 2025-03-11T19:23:08Z

pydantic_ai_slim/pydantic_ai/agent.py

@@ -148,6 +150,7 @@ def __init__(
        result_tool_description: str | None = None,
        result_retries: int | None = None,
        tools: Sequence[Tool[AgentDepsT] | ToolFuncEither[AgentDepsT, ...]] = (),
+        mcp_servers: dict[str, MCPServer] | None = None,


Not sure I use the name of the server... Maybe it can be a list...

github-actions · 2025-03-11T19:25:12Z

Docs Preview

commit:	`46cf989`
Preview URL:	https://0cf3982a-pydantic-ai-previews.pydantic.workers.dev

pydantic_ai_slim/pydantic_ai/_agent_graph.py

dmontagu · 2025-03-12T12:40:40Z

pydantic_ai_slim/pydantic_ai/_agent_graph.py

+
+    for server in ctx.deps.mcp_servers:
+        tools = await server.list_tools()
+        if tool_name in {tool.name for tool in tools}:


Do we need to do anything to ensure there aren’t naming conflicts between servers?

What should I do? Error? 🤔

I guess so, or namespace the tools by server or something

pydantic_ai_slim/pydantic_ai/agent.py

dmontagu · 2025-03-13T04:19:23Z

docs/mcp_servers.md

+async def main():
+    async with MCPServer.stdio('python', ['-m', 'pydantic_ai.mcp']) as server:
+        agent = Agent('openai:gpt-4o', mcp_servers=[server])
+        result = await agent.run('Can you convert 30 degrees celsius to fahrenheit?')
+    print(result.data)
+    #> 30 degrees Celsius is equal to 86 degrees Fahrenheit.


Is this using the server in any way? It would be nice if the example did do that. Or at least looked more like it did that lol.

Ah, I see that it is. I think you should make it more clear that this is using the example MCP server present in the pydantic_ai.mcp module.

I think it's also worth printing out the full message history here if it shows that a tool call related to the MCP server was made.

samuelcolvin

I think we need to change this so we have separate types for:

stdio servers where pydantic-ai is responsible for running the server as a subprocess
SSE where pydantic-ai is just connecting to a server running in a different process (maybe remotely)

Here's a rough sketch of running both:

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPSubprocessServer, MCPRemoteServer

agent = Agent(
    'openai:gpt-4o',
    mcp_servers=[
        MCPSubprocessServer('python', ('-m', 'my_mcp_server')),
        MCPRemoteServer('http://localhost:8000/sse')
    ],
)

async def main():
    async for agent.run_mcp_servers():
        ...

The advantage of this distinction are:

more type safe
easier to document the difference and clearer to the user what's going
no need to use run_mcp_servers for MCPRemoteServer which can use the existing http connection from cached_async_http_client
I also thing "subprocess" vs "remote" is a clearer distinction for most developers than "stdio" vs "sse" although of course we should document what transport they're using under the hood

samuelcolvin · 2025-03-13T10:03:54Z

docs/mcp_servers.md

@@ -0,0 +1,72 @@
+# MCP Servers


I think this should be called "MCP Client" since pydantic-ai is acting as a client

I'm using the same notation everybody is tho. Claude Desktop, Cursor, and Cline use the "MCP Server" terminology even on the STDIO.

right, but we're building an MCP client, so we should call it that.

But the chapter is about MCP Servers. It far better for SEO. No one uses the term client, even when you are configuring the client: Cursor, Claude Desktop, Cline.

Maybe rephrase the introduction phrase as something like:

PydanticAI supports integration with MCP Servers and act as a MCP client...

maybe link with https://modelcontextprotocol.io/introduction#general-architecture.

we should have a new section in docs:

mcp/index.md - a general introduction saying PydanticAI can be used as an MCP client or to build servers, and comes with some servers

mcp/client.md - this page - describing how to use PydanticAI as an MCP client

mcp/run-python.md - docs for MCP server to run Python code in a sandbox #1140

... more

docs/mcp_servers.md

samuelcolvin · 2025-03-13T11:01:13Z

docs/mcp_servers.md

+
+async def main():
+    async with MCPServer.sse(url='http://localhost:8000/sse') as mcp_server:
+        Agent('your-model', mcp_servers=[mcp_server])


I thought we were providing a way to set or initialise the server on an agent created in the global scope?

also, surely with and SSE server, we're just using an HTTP connection, so we should be able to use the existing http connection and we then don't need a context manager.

samuelcolvin · 2025-03-13T11:01:22Z

docs/mcp_servers.md

+proper initialization and cleanup of resources. You can use either an HTTP/SSE server or a
+stdio-based server.
+
+### HTTP/SSE Server


we need some explanation on what's going on here.

pydantic_ai_slim/pydantic_ai/_agent_graph.py

pydantic_ai_slim/pydantic_ai/mcp.py

Kludex · 2025-03-13T12:28:46Z

@samuelcolvin What happens if the user didn't use the following, and they have set a MCPSubprocessServer?

async with agent.run_mcp_servers():
    ...

Should we error? Or... ? Creating and recreating the server can be too resource intensive.

samuelcolvin · 2025-03-13T12:30:19Z

error.

pydantic_ai_slim/pyproject.toml

Wh1isper · 2025-03-13T12:55:03Z

We have to drop python 3.9 support if using mcp official lib, while it's ok for me

Kludex · 2025-03-13T13:07:44Z

We have to drop python 3.9 support if using mcp official lib, while it's ok for me

Nop. I rather support 3.9 on their side. Not much work for it.

Kludex · 2025-03-14T08:44:18Z

At this point, since the user has to do run_mcp_servers, and we have a global HTTP client, I think it would make sense to make Agent an async context manager.

async with Agent() as agent:  # This creates the HTTP client and runs the MCP servers.
    await agent.run('What is the capital of France?')

Honestly, just the HTTP client already justifies to make the Agent an async context manager.

samuelcolvin

otherwise looking good.

samuelcolvin · 2025-03-14T10:30:42Z

docs/mcp_servers.md

@@ -0,0 +1,72 @@
+# MCP Servers


right, but we're building an MCP client, so we should call it that.

samuelcolvin · 2025-03-14T10:33:15Z

docs/mcp_servers.md

+You can have a MCP server running on a remote server. In this case, you'd use the
+[`MCPRemoteServer`][pydantic_ai.mcp.MCPRemoteServer] class:
+
+```python {title="basic_mcp_setup.py" test="skip"}


Suggested change

```python {title="basic_mcp_setup.py" test="skip"}

```python {title="mcp_remote_server.py" test="skip"}

also, these examples need to be run!

Can you suggest how? It's a remote server. I've enabled the other one.

docs/mcp_servers.md

pydantic_ai_slim/pydantic_ai/mcp.py

Viicos · 2025-03-14T15:52:01Z

docs/mcp_servers.md

@@ -0,0 +1,72 @@
+# MCP Servers


Maybe rephrase the introduction phrase as something like:

PydanticAI supports integration with MCP Servers and act as a MCP client...

maybe link with https://modelcontextprotocol.io/introduction#general-architecture.

Viicos · 2025-03-14T15:54:49Z

docs/mcp_servers.md

+PydanticAI comes with two ways to connect to MCP servers:
+
+- [`MCPRemoteServer`][pydantic_ai.mcp.MCPRemoteServer] which connects to an MCP server using the [HTTP SSE](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse) transport
+- [`MCPSubprocessServer`][pydantic_ai.mcp.MCPSubprocessServer] which runs the server as a subprocess and connects to it using the [stdio](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio) transport


I find it a bit confusing that the MCP*Server classes are actually clients. Can't we name them MCP*Client?

I think we should see the object as a representation of the server.

docs/mcp_servers.md

pydantic_ai_slim/pydantic_ai/mcp.py

Viicos · 2025-03-14T16:18:29Z

pydantic_ai_slim/pydantic_ai/mcp.py

+    command: str
+    """The command to run."""
+
+    args: Sequence[str]


Unlikely but this will allow MCPSubprocessServer('python', '-m pydantic_ai_examples.mcp_server') which will not work as expected.

Maybe enforce list[str], or list[str] | tuple[str, ...]? Feel free to leave it as is.

Should I use https://docs.python.org/3/library/shlex.html ?

I'm not sure how shlex behaves on non Unix shells, and I think it's best to enforce a proper sequence of str instead of trying to parse str inputs

So either we leave it as is if you think passing a bare string will not be a common mistake, or change the type hint to list[str] | tuple[str, ...]?

If someone get this mistake, I'll fix it.

Co-authored-by: Samuel Colvin <s@muelcolvin.com>

samuelcolvin

I can do some work on the docs tomorrow.

samuelcolvin · 2025-03-16T23:35:36Z

docs/mcp_servers.md

@@ -0,0 +1,72 @@
+# MCP Servers


we should have a new section in docs:

mcp/index.md - a general introduction saying PydanticAI can be used as an MCP client or to build servers, and comes with some servers

mcp/client.md - this page - describing how to use PydanticAI as an MCP client

mcp/run-python.md - docs for MCP server to run Python code in a sandbox #1140

... more

samuelcolvin · 2025-03-16T23:37:01Z

pydantic_ai_slim/pydantic_ai/mcp.py

+
+
+@dataclass
+class MCPSubprocessServer(MCPServer):


I think I was wrong about this name, we should use the names MCP users which are clearly "stdio" and "sse", my mistake ✋ .

I guess we should call this MCPServerStdio, and the other one MCPServerSSE.

I think I was wrong about this name, we should use the names MCP users which are clearly "stdio" and "sse", my mistake ✋ .

I guess we should call this MCPServerStdio, and the other one MCPServerSSE.

...

Co-authored-by: Victorien <65306057+Viicos@users.noreply.github.com>

Kludex commented Mar 11, 2025

View reviewed changes

Kludex commented Mar 12, 2025

View reviewed changes

pydantic_ai_slim/pydantic_ai/_agent_graph.py Outdated Show resolved Hide resolved

dmontagu reviewed Mar 12, 2025

View reviewed changes

pydantic_ai_slim/pydantic_ai/agent.py Outdated Show resolved Hide resolved

dmontagu reviewed Mar 13, 2025

View reviewed changes

samuelcolvin requested changes Mar 13, 2025

View reviewed changes

samuelcolvin reviewed Mar 13, 2025

View reviewed changes

pydantic_ai_slim/pyproject.toml Outdated Show resolved Hide resolved

Kludex force-pushed the mcp-support branch from 7763ccd to 5d00f60 Compare March 14, 2025 07:48

Kludex mentioned this pull request Mar 14, 2025

Revert "refactor: reorganize message handling for better type safety and clarity" modelcontextprotocol/python-sdk#282

Merged

Kludex requested a review from samuelcolvin March 14, 2025 10:27

samuelcolvin reviewed Mar 14, 2025

View reviewed changes

Kludex commented Mar 14, 2025

View reviewed changes

pydantic_ai_slim/pydantic_ai/mcp.py Outdated Show resolved Hide resolved

Viicos reviewed Mar 14, 2025

View reviewed changes

Kludex added 10 commits March 16, 2025 12:01

Add support for MCP servers

c4f1726

Add MCP support

bfc4be6

Fix MCP Server

46c0f17

Done

0e51d39

fix docs

a7181e4

fix import

7e487c1

Add test

22483ad

Add last test

0cae308

Add tests

ae4dadd

Add tests

76b8759

Kludex and others added 14 commits March 16, 2025 12:01

Update docs

d23a9a0

bump to 1.4.1

131af07

Correct the uv lock

7f32d05

Apply suggestions from code review

1cf04ac

Co-authored-by: Samuel Colvin <s@muelcolvin.com>

Update pydantic_ai_slim/pydantic_ai/mcp.py

8648622

Change test

21b98ce

Change test

0518681

apply more comments

75fff0f

docstring

8770d0c

Add server instructions

fc9ef87

only 3.10 more

62f5436

Add links

abb4d39

Add name main

dd8f0c5

test only on 3.10+

9467c97

Kludex force-pushed the mcp-support branch from 13be997 to 9467c97 Compare March 16, 2025 11:01

Kludex and others added 2 commits March 16, 2025 13:14

Only the MCPRemoteServer test is failling

2238bc1

fix example tests

a5c8985

samuelcolvin reviewed Mar 16, 2025

View reviewed changes

samuelcolvin and others added 4 commits March 16, 2025 23:39

fix for 3.9

549d514

Add 100% coverage

5805745

Add note

4c27c44

Merge branch 'main' into mcp-support

94d733c

Kludex enabled auto-merge (squash) March 17, 2025 15:02

Viicos disabled auto-merge March 17, 2025 15:04

Kludex and others added 2 commits March 17, 2025 16:42

Apply suggestions from code review

5418e33

Co-authored-by: Victorien <65306057+Viicos@users.noreply.github.com>

Add Self import

46cf989

Kludex merged commit 444f5d0 into main Mar 17, 2025
16 checks passed

Kludex deleted the mcp-support branch March 17, 2025 16:23

samuelcolvin mentioned this pull request Mar 19, 2025

improved MCP documentation #1171

Merged

Viicos mentioned this pull request Apr 8, 2025

Shouldn't MCPServer/s available in the library be called MCPClient/s ? #1404

Closed

	```python {title="basic_mcp_setup.py" test="skip"}
	```python {title="mcp_remote_server.py" test="skip"}



		@dataclass
		class MCPSubprocessServer(MCPServer):

Add support for MCP servers #1100

Add support for MCP servers #1100

Conversation

Kludex commented Mar 11, 2025

hyperlint-ai bot commented Mar 11, 2025

PR Change Summary

Choose a reason for hiding this comment

github-actions bot commented Mar 11, 2025 • edited Loading

Docs Preview

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dmontagu Mar 13, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

samuelcolvin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Kludex commented Mar 13, 2025

samuelcolvin commented Mar 13, 2025

Wh1isper commented Mar 13, 2025

Kludex commented Mar 13, 2025

Kludex commented Mar 14, 2025 • edited Loading

samuelcolvin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Kludex Mar 14, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Kludex Mar 17, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

samuelcolvin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Mar 11, 2025 •

edited

Loading

dmontagu Mar 13, 2025 •

edited

Loading

Kludex commented Mar 14, 2025 •

edited

Loading

Kludex Mar 14, 2025 •

edited

Loading

Kludex Mar 17, 2025 •

edited

Loading