[3/n] Add an MCP stdio example (#322)

### Summary:
Spins up a stdio server with some local files, then asks the model
questions.

### Test Plan:
Run the example, see it work.


---
[//]: # (BEGIN SAPLING FOOTER)
* #324
* __->__ #322
* #336

Author: rm-openai

docs/mcp.md

@@ -0,0 +1,51 @@
+# Model context protocol
+
+The [Model context protocol](https://modelcontextprotocol.io/introduction) (aka MCP) is a way to provide tools and context to the LLM. From the MCP docs:
+
+> MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.
+
+The Agents SDK has support for MCP. This enables you to use a wide range of MCP servers to provide tools to your Agents.
+
+## MCP servers
+
+Currently, the MCP spec defines two kinds of servers, based on the transport mechanism they use:
+
+1. **stdio** servers run as a subprocess of your application. You can think of them as running "locally".
+2. **HTTP over SSE** servers run remotely. You connect to them via a URL.
+
+You can use the [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] and [`MCPServerSse`][agents.mcp.server.MCPServerSse] classes to connect to these servers.
+
+For example, this is how you'd use the [official MCP filesystem server](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem).
+
+```python
+async with MCPServerStdio(
+    params={
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
+    }
+) as server:
+    tools = await server.list_tools()
+```
+
+## Using MCP servers
+
+MCP servers can be added to Agents. The Agents SDK will call `list_tools()` on the MCP servers each time the Agent is run. This makes the LLM aware of the MCP server's tools. When the LLM calls a tool from an MCP server, the SDK calls `call_tool()` on that server.
+
+```python
+
+agent=Agent(
+    name="Assistant",
+    instructions="Use the tools to achieve the task",
+    mcp_servers=[mcp_server_1, mcp_server_2]
+)
+```
+
+## Caching
+
+Every time an Agent runs, it calls `list_tools()` on the MCP server. This can be a latency hit, especially if the server is a remote server. To automatically cache the list of tools, you can pass `cache_tools_list=True` to both [`MCPServerStdio`][agents.mcp.server.MCPServerStdio] and [`MCPServerSse`][agents.mcp.server.MCPServerSse]. You should only do this if you're certain the tool list will not change.
+
+If you want to invalidate the cache, you can call `invalidate_tools_cache()` on the servers.
+
+## End-to-end example
+
+View complete working examples at [examples/mcp](https://github.com/openai/openai-agents-python/tree/main/examples/mcp).

docs/ref/mcp/server.md

@@ -0,0 +1,3 @@
+# `MCP Servers`
+
+::: agents.mcp.server

docs/ref/mcp/util.md

@@ -0,0 +1,3 @@
+# `MCP Util`
+
+::: agents.mcp.util

examples/mcp/filesystem_example/README.md

@@ -0,0 +1,26 @@
+# MCP Filesystem Example
+
+This example uses the [fileystem MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem), running locally via `npx`.
+
+Run it via:
+
+```
+uv run python  python examples/mcp/filesystem_example/main.py
+```
+
+## Details
+
+The example uses the `MCPServerStdio` class from `agents`, with the command:
+
+```bash
+npx -y "@modelcontextprotocol/server-filesystem" <samples_directory>
+```
+
+It's only given access to the `sample_files` directory adjacent to the example, which contains some sample data.
+
+Under the hood:
+
+1. The server is spun up in a subprocess, and exposes a bunch of tools like `list_directory()`, `read_file()`, etc.
+2. We add the server instance to the Agent via `mcp_agents`.
+3. Each time the agent runs, we call out to the MCP server to fetch the list of tools via `server.list_tools()`.
+4. If the LLM chooses to use an MCP tool, we call the MCP server to run the tool via `server.run_tool()`.

examples/mcp/filesystem_example/main.py

@@ -0,0 +1,54 @@
+import asyncio
+import os
+import shutil
+
+from agents import Agent, Runner, trace
+from agents.mcp import MCPServer, MCPServerStdio
+
+
+async def run(mcp_server: MCPServer):
+    agent = Agent(
+        name="Assistant",
+        instructions="Use the tools to read the filesystem and answer questions based on those files.",
+        mcp_servers=[mcp_server],
+    )
+
+    # List the files it can read
+    message = "Read the files and list them."
+    print(f"Running: {message}")
+    result = await Runner.run(starting_agent=agent, input=message)
+    print(result.final_output)
+
+    # Ask about books
+    message = "What is my #1 favorite book?"
+    print(f"\n\nRunning: {message}")
+    result = await Runner.run(starting_agent=agent, input=message)
+    print(result.final_output)
+
+    # Ask a question that reads then reasons.
+    message = "Look at my favorite songs. Suggest one new song that I might like."
+    print(f"\n\nRunning: {message}")
+    result = await Runner.run(starting_agent=agent, input=message)
+    print(result.final_output)
+
+
+async def main():
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    samples_dir = os.path.join(current_dir, "sample_files")
+
+    async with MCPServerStdio(
+        params={
+            "command": "npx",
+            "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
+        }
+    ) as server:
+        with trace(workflow_name="MCP Filesystem Example"):
+            await run(server)
+
+
+if __name__ == "__main__":
+    # Let's make sure the user has npx installed
+    if not shutil.which("npx"):
+        raise RuntimeError("npx is not installed. Please install it with `npm install -g npx`.")
+
+    asyncio.run(main())

examples/mcp/filesystem_example/sample_files/favorite_books.txt

@@ -0,0 +1,20 @@
+1. To Kill a Mockingbird – Harper Lee
+2. Pride and Prejudice – Jane Austen
+3. 1984 – George Orwell
+4. The Hobbit – J.R.R. Tolkien
+5. Harry Potter and the Sorcerer’s Stone – J.K. Rowling
+6. The Great Gatsby – F. Scott Fitzgerald
+7. Charlotte’s Web – E.B. White
+8. Anne of Green Gables – Lucy Maud Montgomery
+9. The Alchemist – Paulo Coelho
+10. Little Women – Louisa May Alcott
+11. The Catcher in the Rye – J.D. Salinger
+12. Animal Farm – George Orwell
+13. The Chronicles of Narnia: The Lion, the Witch, and the Wardrobe – C.S. Lewis
+14. The Book Thief – Markus Zusak
+15. A Wrinkle in Time – Madeleine L’Engle
+16. The Secret Garden – Frances Hodgson Burnett
+17. Moby-Dick – Herman Melville
+18. Fahrenheit 451 – Ray Bradbury
+19. Jane Eyre – Charlotte Brontë
+20. The Little Prince – Antoine de Saint-Exupéry

examples/mcp/filesystem_example/sample_files/favorite_cities.txt

@@ -0,0 +1,4 @@
+- In the summer, I love visiting London.
+- In the winter, Tokyo is great.
+- In the spring, San Francisco.
+- In the fall, New York is the best.

examples/mcp/filesystem_example/sample_files/favorite_songs.txt

@@ -0,0 +1,10 @@
+1. "Here Comes the Sun" – The Beatles
+2. "Imagine" – John Lennon
+3. "Bohemian Rhapsody" – Queen
+4. "Shake It Off" – Taylor Swift
+5. "Billie Jean" – Michael Jackson
+6. "Uptown Funk" – Mark Ronson ft.  Bruno Mars
+7. "Don’t Stop Believin’" – Journey
+8. "Dancing Queen" – ABBA
+9. "Happy" – Pharrell Williams
+10. "Wonderwall" – Oasis

mkdocs.yml

@@ -28,6 +28,7 @@ nav:
       - results.md
       - streaming.md
       - tools.md
+      - mcp.md
       - handoffs.md
       - tracing.md
       - context.md
@@ -60,6 +61,8 @@ nav:
           - ref/models/interface.md
           - ref/models/openai_chatcompletions.md
           - ref/models/openai_responses.md
+          - ref/mcp/server.md
+          - ref/mcp/util.md
       - Tracing:
           - ref/tracing/index.md
           - ref/tracing/create.md
@@ -107,6 +110,8 @@ plugins:
             show_signature_annotations: true
             # Makes the font sizes nicer
             heading_level: 3
+            # Show inherited members
+            inherited_members: true
 
 extra:
   # Remove material generation message in footer

src/agents/mcp/mcp_util.py

@@ -175,10 +175,10 @@ def __init__(self, params: MCPServerStdioParams, cache_tools_list: bool = False)
         """Create a new MCP server based on the stdio transport.
 
         Args:
-            params: The params that configure the server. This includes:
-                - The command (e.g. `python` or `node`) that starts the server.
-                - The args to pass to the server command (e.g. `foo.py` or `server.js`).
-                - The environment variables to set for the server.
+            params: The params that configure the server. This includes the command to run to
+                start the server, the args to pass to the command, the environment variables to
+                set for the server, the working directory to use when spawning the process, and
+                the text encoding used when sending/receiving messages to the server.
             cache_tools_list: Whether to cache the tools list. If `True`, the tools list will be
                 cached and only fetched from the server once. If `False`, the tools list will be
                 fetched from the server on each call to `list_tools()`. The cache can be
@@ -235,11 +235,9 @@ def __init__(self, params: MCPServerSseParams, cache_tools_list: bool = False):
         """Create a new MCP server based on the HTTP with SSE transport.
 
         Args:
-            params: The params that configure the server. This includes:
-            - The URL of the server.
-            - The headers to send to the server.
-            - The timeout for the HTTP request.
-            - The timeout for the SSE connection.
+            params: The params that configure the server. This includes the URL of the server,
+                the headers to send to the server, the timeout for the HTTP request, and the
+                timeout for the SSE connection.
 
             cache_tools_list: Whether to cache the tools list. If `True`, the tools list will be
                 cached and only fetched from the server once. If `False`, the tools list will be