Mcp stdio server

mcp-stdio-server

Use MCPServerStdio to launch a local process and communicate over stdin/stdout using the MCP protocol. Add the server to Agent.mcp_servers.

When to apply

When you have an MCP server that runs as a local process (e.g., npx @modelcontextprotocol/server-filesystem). Best for development and trusted local environments.

Core snippet

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async def main():
    async with MCPServerStdio(
        name="Filesystem Server",
        params={
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
        },
        # Optional: cache list_tools() result
        cache_tools_list=True,
    ) as mcp_server:
        agent = Agent(
            name="File assistant",
            instructions="Use the tools to answer questions about files.",
            mcp_servers=[mcp_server],
        )
        result = await Runner.run(agent, "List the files in /tmp")
        print(result.final_output)

asyncio.run(main())

With tool filtering

async with MCPServerStdio(
    name="Git Server",
    params={"command": "uvx", "args": ["mcp-server-git", "--repository", "."]},
    # Only expose specific tools from the server
    tool_filter=["git_log", "git_diff"],
) as mcp_server:
    agent = Agent(name="Git assistant", mcp_servers=[mcp_server])

Key notes

• Use as an async context manager to manage the subprocess lifecycle
• cache_tools_list=True avoids repeated list_tools() calls per agent turn
• tool_filter accepts a list of tool names or a callable predicate
• MCP tool failures surface as tool error text by default; customize via mcp_config
• For remote servers, use MCPServerSse (HTTP+SSE) or MCPServerStreamableHttp