improved MCP documentation (#1171)

Co-authored-by: David Montague <[email protected]>

Author: samuelcolvin

.gitignore

@@ -15,3 +15,4 @@ examples/pydantic_ai_examples/.chat_app_messages.sqlite
 .vscode/
 /question_graph_history.json
 /docs-site/.wrangler/
+/CLAUDE.md

docs/img/logfire-run-python-code.png

@@ -0,0 +1,103 @@
+# Client
+
+PydanticAI can act as an [MCP client](https://modelcontextprotocol.io/quickstart/client), connecting to MCP servers
+to use their tools.
+
+## Install
+
+You need to either install [`pydantic-ai`](../install.md), or[`pydantic-ai-slim`](../install.md#slim-install) with the `mcp` optional group:
+
+```bash
+pip/uv-add 'pydantic-ai-slim[mcp]'
+```
+
+!!! note
+    MCP integration requires Python 3.10 or higher.
+
+## Usage
+
+PydanticAI comes with two ways to connect to MCP servers:
+
+- [`MCPServerSSE`][pydantic_ai.mcp.MCPServerSSE] which connects to an MCP server using the [HTTP SSE](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse) transport
+- [`MCPServerStdio`][pydantic_ai.mcp.MCPServerStdio] 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
+
+Examples of both are shown below; [mcp-run-python](run-python.md) is used as the MCP server in both examples.
+
+### SSE Client
+
+[`MCPServerSSE`][pydantic_ai.mcp.MCPServerSSE] connects over HTTP using the [HTTP + Server Sent Events transport](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse) to a server.
+
+!!! note
+    [`MCPServerSSE`][pydantic_ai.mcp.MCPServerSSE] requires an MCP server to be running and accepting HTTP connections before calling [`agent.run_mcp_servers()`][pydantic_ai.Agent.run_mcp_servers]. Running the server is not managed by PydanticAI.
+
+Before creating the SSE client, we need to run the server (docs [here](run-python.md)):
+
+```bash {title="run_sse_server.py"}
+npx @pydantic/mcp-run-python sse
+```
+
+```python {title="mcp_sse_client.py" py="3.10"}
+from pydantic_ai import Agent
+from pydantic_ai.mcp import MCPServerSSE
+
+server = MCPServerSSE(url='http://localhost:3001/sse')  # (1)!
+agent = Agent('openai:gpt-4o', mcp_servers=[server])  # (2)!
+
+
+async def main():
+    async with agent.run_mcp_servers():  # (3)!
+        result = await agent.run('How many days between 2000-01-01 and 2025-03-18?')
+    print(result.data)
+    #> There are 9,208 days between January 1, 2000, and March 18, 2025.
+```
+
+1. Define the MCP server with the URL used to connect.
+2. Create an agent with the MCP server attached.
+3. Create a client session to connect to the server.
+
+_(This example is complete, it can be run "as is" with Python 3.10+ — you'll need to add `asyncio.run(main())` to run `main`)_
+
+**What's happening here?**
+
+* The model is receiving the prompt "how many days between 2000-01-01 and 2025-03-18?"
+* The model decides "Oh, I've got this `run_python_code` tool, that will be a good way to answer this question", and writes some python code to calculate the answer.
+* The model returns a tool call
+* PydanticAI sends the tool call to the MCP server using the SSE transport
+* The model is called again with the return value of running the code
+* The model returns the final answer
+
+You can visualise this clearly, and even see the code that's run by adding three lines of code to instrument the example with [logfire](https://logfire.pydantic.dev/docs):
+
+```python {title="mcp_sse_client_logfire.py" test="skip"}
+import logfire
+
+logfire.configure()
+logfire.instrument_pydantic_ai()
+```
+
+Will display as follows:
+
+![Logfire run python code](../img/logfire-run-python-code.png)
+
+### MCP "stdio" Server
+
+The other transport offered by MCP is the [stdio transport](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio) where the server is run as a subprocess and communicates with the client over `stdin` and `stdout`. In this case, you'd use the [`MCPServerStdio`][pydantic_ai.mcp.MCPServerStdio] class.
+
+!!! note
+    When using [`MCPServerStdio`][pydantic_ai.mcp.MCPServerStdio] servers, the [`agent.run_mcp_servers()`][pydantic_ai.Agent.run_mcp_servers] context manager is responsible for starting and stopping the server.
+
+
+```python {title="mcp_stdio_client.py" py="3.10"}
+from pydantic_ai import Agent
+from pydantic_ai.mcp import MCPServerStdio
+
+server = MCPServerStdio('npx', ['-y', '@pydantic/mcp-run-python', 'stdio'])
+agent = Agent('openai:gpt-4o', mcp_servers=[server])
+
+
+async def main():
+    async with agent.run_mcp_servers():
+        result = await agent.run('How many days between 2000-01-01 and 2025-03-18?')
+    print(result.data)
+    #> There are 9,208 days between January 1, 2000, and March 18, 2025.
+```

docs/mcp/client.md

@@ -0,0 +1,29 @@
+# Model Context Protocol (MCP)
+
+PydanticAI supports [Model Context Protocol (MCP)](https://modelcontextprotocol.io) in three ways:
+
+1. [Agents](../agents.md) act as an MCP Client, connecting to MCP servers to use their tools, [learn more …](client.md)
+2. Agents can be used within MCP servers, [learn more …](server.md)
+3. As part of PydanticAI, we're building a number of MCP servers, [see below](#mcp-servers)
+
+## What is MCP?
+
+The Model Context Protocol is a standardized protocol that allow AI applications (including programmatic agents like PydanticAI, coding agents like [cursor](https://www.cursor.com/), and desktop applications like [Claude Desktop](https://claude.ai/download)) to connect to external tools and services using a common interface.
+
+As with other protocols, the dream of MCP is that a wide range of applications can speak to each other without the need for specific integrations.
+
+There is a great list of MCP servers at [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers).
+
+Some examples of what this means:
+
+* PydanticAI could use a web search service implemented as an MCP server to implement a deep research agent
+* Cursor could connect to the [Pydantic Logfire](https://github.com/pydantic/logfire-mcp) MCP server to search logs, traces and metrics to gain context while fixing a bug
+* PydanticAI, or any other MCP client could connect to our [Run Python](run-python.md) MCP server to run arbitrary Python code in a sandboxed environment
+
+## MCP Servers
+
+To add functionality to PydanticAI while making it as widely usable as possible, we're implementing some functionality as MCP servers.
+
+So far, we've only implemented one MCP server as part of PydanticAI:
+
+* [Run Python](run-python.md): A sandboxed Python interpreter that can run arbitrary code, with a focus on security and safety.

docs/mcp/index.md

@@ -0,0 +1,146 @@
+# MCP Run Python
+
+The **MCP Run Python** package is an MCP server that allows agents to execute Python code in a secure, sandboxed environment. It uses [Pyodide](https://pyodide.org/) to run Python code in a JavaScript environment, isolating execution from the host system.
+
+## Features
+
+* **Secure Execution**: Run Python code in a sandboxed WebAssembly environment
+* **Package Management**: Automatically detects and installs required dependencies
+* **Complete Results**: Captures standard output, standard error, and return values
+* **Asynchronous Support**: Runs async code properly
+* **Error Handling**: Provides detailed error reports for debugging
+
+## Installation
+
+The MCP Run Python server is distributed as an [NPM package](https://www.npmjs.com/package/@pydantic/mcp-run-python) and can be run directly using [`npx`](https://docs.npmjs.com/cli/v8/commands/npx):
+
+```bash
+npx @pydantic/mcp-run-python [stdio|sse]
+```
+
+Where:
+
+* `stdio`: Runs the server with [stdin/stdout transport](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio) (for subprocess usage)
+* `sse`: Runs the server with [HTTP Server-Sent Events transport](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse) (for remote connections)
+
+Usage of `@pydantic/mcp-run-python` with PydanticAI is described in the [client](client.md#mcp-stdio-server) documentation.
+
+## Direct Usage
+
+As well as using this server with PydanticAI, it can be connected to other MCP clients. For clarity, in this example we connect directly using the [Python MCP client](https://github.com/modelcontextprotocol/python-sdk).
+
+```python {title="mcp_run_python.py" py="3.10"}
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+code = """
+import numpy
+a = numpy.array([1, 2, 3])
+print(a)
+a
+"""
+
+
+async def main():
+    server_params = StdioServerParameters(
+        command='npx', args=['-y', '@pydantic/mcp-run-python', 'stdio']
+    )
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            tools = await session.list_tools()
+            print(len(tools.tools))
+            #> 1
+            print(repr(tools.tools[0].name))
+            #> 'run_python_code'
+            print(repr(tools.tools[0].inputSchema))
+            """
+            {'type': 'object', 'properties': {'python_code': {'type': 'string', 'description': 'Python code to run'}}, 'required': ['python_code'], 'additionalProperties': False, '$schema': 'http://json-schema.org/draft-07/schema#'}
+            """
+            result = await session.call_tool('run_python_code', {'python_code': code})
+            print(result.content[0].text)
+            """
+            <status>success</status>
+            <dependencies>["numpy"]</dependencies>
+            <output>
+            [1 2 3]
+            </output>
+            <return_value>
+            [
+              1,
+              2,
+              3
+            ]
+            </return_value>
+            """
+```
+
+## Dependencies
+
+Dependencies are installed when code is run.
+
+Dependencies can be defined in one of two ways:
+
+### Inferred from imports
+
+If there's no metadata, dependencies are inferred from imports in the code,
+as shown in the example [above](#direct-usage).
+
+### Inline script metadata
+
+As introduced in PEP 723, explained [here](https://packaging.python.org/en/latest/specifications/inline-script-metadata/#inline-script-metadata), and popularized by [uv](https://docs.astral.sh/uv/guides/scripts/#declaring-script-dependencies) — dependencies can be defined in a comment at the top of the file.
+
+This allows use of dependencies that aren't imported in the code, and is more explicit.
+
+```py {title="inline_script_metadata.py" py="3.10"}
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+code = """\
+# /// script
+# dependencies = ["pydantic", "email-validator"]
+# ///
+import pydantic
+
+class Model(pydantic.BaseModel):
+    email: pydantic.EmailStr
+
+print(Model(email='[email protected]'))
+"""
+
+
+async def main():
+    server_params = StdioServerParameters(
+        command='npx', args=['-y', '@pydantic/mcp-run-python', 'stdio']
+    )
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            result = await session.call_tool('run_python_code', {'python_code': code})
+            print(result.content[0].text)
+            """
+            <status>success</status>
+            <dependencies>["pydantic","email-validator"]</dependencies>
+            <output>
+            email='[email protected]'
+            </output>
+            """
+```
+
+It also allows versions to be pinned for non-binary packages (Pyodide only supports a single version for the binary packages it supports, like `pydantic` and `numpy`).
+
+E.g. you could set the dependencies to
+
+```python
+# /// script
+# dependencies = ["rich<13"]
+# ///
+```
+
+## Logging
+
+MCP Run Python supports emitting stdout and stderr from the python execution as [MCP logging messages](https://github.com/modelcontextprotocol/specification/blob/eb4abdf2bb91e0d5afd94510741eadd416982350/docs/specification/draft/server/utilities/logging.md?plain=1).
+
+For logs to be emitted you must set the logging level when connecting to the server. By default, the log level is set to the highest level, `emergency`.
+
+Currently, it's not possible to demonstrate this due to a bug in the Python MCP Client, see [modelcontextprotocol/python-sdk#201](https://github.com/modelcontextprotocol/python-sdk/issues/201#issuecomment-2727663121).

docs/mcp/run-python.md

@@ -0,0 +1,60 @@
+# Server
+
+PydanticAI models can also be used within MCP Servers.
+
+Here's a simple example of a [Python MCP server](https://github.com/modelcontextprotocol/python-sdk) using PydanticAI within a tool call:
+
+```py {title="mcp_server.py" py="3.10"}
+from mcp.server.fastmcp import FastMCP
+
+from pydantic_ai import Agent
+
+server = FastMCP('PydanticAI Server')
+server_agent = Agent(
+    'anthropic:claude-3-5-haiku-latest', system_prompt='always reply in rhyme'
+)
+
+
+@server.tool()
+async def poet(theme: str) -> str:
+    """Poem generator"""
+    r = await server_agent.run(f'write a poem about {theme}')
+    return r.data
+
+
+if __name__ == '__main__':
+    server.run()
+```
+
+This server can be queried with any MCP client. Here is an example using a direct Python client:
+
+```py {title="mcp_client.py" py="3.10"}
+import asyncio
+import os
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+
+async def client():
+    server_params = StdioServerParameters(
+        command='uv', args=['run', 'mcp_server.py', 'server'], env=os.environ
+    )
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            result = await session.call_tool('poet', {'theme': 'socks'})
+            print(result.content[0].text)
+            """
+            Oh, socks, those garments soft and sweet,
+            That nestle softly 'round our feet,
+            From cotton, wool, or blended thread,
+            They keep our toes from feeling dread.
+            """
+
+
+if __name__ == '__main__':
+    asyncio.run(client())
+```
+
+Note: [sampling](https://modelcontextprotocol.io/docs/concepts/sampling#sampling), whereby servers may request LLM completions from the client, is not yet supported in PydanticAI.