Install a "universal socket" for your AI Agent? Talk about MCP in OpenAI Agents SDK

Hey, everyone, I’m Lao Ma Xiao Zhang.

I have been in the technology circle for a while. Compared with chasing all kinds of fancy new terms, I prefer to delve into the little tricks behind the technology and figure out how to use these technologies to solve some real problems. Recently, AI Agent has been very popular. OpenAI has also launched its own Agents SDK. I naturally took a look at it and found something called MCP in it. It is quite interesting. I want to talk to you about it today.

Think about it, the large language models (LLMs) we use now, such as GPT-4, are indeed smart, and can chat, write texts, and write code. But they are essentially locked in a "digital black box", isolated from our real world or specific software systems. You want it to help you check the local weather today? Or update the task status in your project management software? If you ask it directly, it will probably just throw up its hands and say "I can't do that."

Why? Because it has no "hands" and "feet"! It needs some tools or abilities to interact with the outside world.

How did we do this in the past? Usually, we wrote a bunch of specific functions in the application code, and then told the LLM through various prompt engineering or specific API calls: "Hey, when you need to check the weather, call this get_weather(city) Function; when you need to read a file, use this read_file(path) function."

This approach is not impossible, but there are several problems:

1. 1.  Too much customization : Each application has to write its own set of tool docking logic, which is a bit like equipping each electrical appliance with a dedicated plug, which may not work if it is moved to another place.
2. 2.  Not flexible enough : If someone has already made a great database query tool and you want to use it, you may have to repackage it yourself to adapt it to your Agent framework.
3. 3.  Lack of standards : Each company has its own way of doing things, and there is no unified “saying”, which makes communication and reuse very difficult.

This is where MCP comes into play.

MCP: The “USB-C Interface” for AI Applications

The full name of MCP is  Model Context Protocol . The official document makes a very vivid analogy: MCP is like a USB-C interface for AI applications .

Think about USB-C: a standard interface that can charge, transfer data, connect to a display, and connect to various peripherals. Whether you have an Apple, Android, or Windows computer, as long as it supports USB-C, many accessories can be used universally.

What MCP wants to do is to provide a standardized way for AI models (especially LLM) to connect different data sources and tools .

With this standard protocol, in theory:

• •  Tool developers can develop tool services that comply with the MCP specification (such as a service that specifically operates Notion, or a service that controls a smart home) without having to worry too much about which specific AI application or Agent framework will ultimately use the service.
• •  AI application developers (such as those of us who use the OpenAI Agents SDK) can easily access a variety of ready-made MCP tool services and “plug in” various capabilities to their own agents without having to write a bunch of customized docking code for each tool.

Does it sound a little exciting? It’s like equipping your AI Agent with a universal socket. If you want to add new features in the future, you just need to find an “electrical appliance” (tool service) that supports MCP and plug it in.

How to use MCP with OpenAI Agents SDK?

The good news is that OpenAI's Agents SDK has built-in support for MCP. This means we can "mount" the MCP service directly when creating an Agent.

So, what does an MCP service look like? Currently, the MCP specification defines two types of services, which differ mainly in the communication method:

1. 1.  stdio servers : This service is usually run as a subprocess inside your application, which can be understood as "running locally". The communication method is through standard input/output (stdin/stdout).
2. 2.  HTTP over SSE servers : This service runs remotely and you need to connect to it through a URL. The communication method is based on HTTP and Server-Sent Events (SSE).

OpenAI Agents SDK provides two corresponding classes to connect to these two servers:MCPServerStdio and MCPServerSse.

For example, suppose you want your Agent to be able to operate the local file system (read files, write files, list directories, etc.). As it happens, MCP officially provides a file system service based on stdio. You can run it and connect it to your Python code like this (here we use npx, usually a tool in the Node.js environment, which will help you download and run @modelcontextprotocol/server-filesystem this package):

import  os
from  openai_agents.mcp  import  MCPServerStdio
# Assume that there is a directory called samples_dir in your project
samples_dir =  "./my_agent_files"
# Make sure this directory exists
os.makedirs(samples_dir, exist_ok= True ) 

async def run_mcp_example ():
    # Configure and start the MCP file system service
    # command specifies npx
    # args tells npx to execute @modelcontextprotocol/server-filesystem,
    # and pass it samples_dir as the working directory
    # The -y parameter tells npx to automatically confirm the installation
    mcp_server_filesystem = MCPServerStdio(
        params={
            "command" :  "npx" ,
            "args" : [ "-y" ,  "@modelcontextprotocol/server-filesystem" , samples_dir],
        }
    )

    # Use async with to ensure that the service is properly closed when exiting
    async with  mcp_server_filesystem  as  server:
        print ( "MCP file system service started..." )
        
        # We can try to manually list the tools it provides
        tools =  await  server.list_tools()
        print ( "Tools provided by the file system service: " )
        for  tool  in  tools:
            print ( f"-  {tool.function.name} :  {tool.function.description} " )
            
        # This is just a demonstration of how to start and list the tools.
        # We will show you how to integrate it into the Agent later.

# If you are running in an asynchronous environment, you can directly await run_mcp_example()
# If you are in a synchronous environment, you can use asyncio.run(run_mcp_example())
import  asyncio
asyncio.run(run_mcp_example())

What does the above code do?

1. 1. Introduced MCPServerStdio.
2. 2. Define the command to run:npx -y @modelcontextprotocol/server-filesystem ./my_agent_filesThis command line will start a local MCP service, which is specifically used to operate ./my_agent_files Files in this directory.
3. 3. Use async with To manage the life cycle of this service and ensure that the service is shut down cleanly when the program exits.
4. 4. In with In the block, we called server.list_tools(), this method will ask the child process through stdio: "Hey, what can you do? Report all your tools (abilities)."
5. 5. Then we print out the tool list we got and take a look.

After running, you may see output similar to this:

MCP File System Service started...
Tools provided by the file system service:
- filesystem.readFile: Reads the content of a file.
- filesystem.writeFile: Writes content to a file.
- filesystem.listFiles: Lists files and directories in a given path.
... (and possibly other tools)

See, the file system service tells us that it can read files (readFile), write file (writeFile), column file (listFiles) wait.

Plug the MCP service into the Agent

It is not enough to just start the service. The key is how to use the Agent. In OpenAI Agents SDK, this is very simple. You only need to create Agent When you create an object, mcp_server_filesystem Instances (or other MCP service instances) are placed in mcp_servers Just put it in the list:

from  openai_agents.agents  import  Agent
# (Assuming mcp_server_filesystem has been defined previously)
# Assume there is another MCP service called mcp_server_other

# When creating an Agent, pass the MCP service list into it
my_agent = Agent(
    name= "File Assistant" ,
    instructions = "Please use the provided tools to complete the task." ,
    # Put all the MCP services you want this Agent to use in this list
    mcp_servers=[mcp_server_filesystem, 
                 # mcp_server_other # If there are other services, add them in as well
                ] 
)

# Next you can run this Agent
# result = await my_agent.run("Please help me read the contents of the welcome.txt file in the my_agent_files directory.")
# print(result.get_text()) 

when my_agent When running, the Agents SDK will automatically do several things:

1. 1.  Inquiry ability : It will find mcp_servers For each service in the list, call their list_tools() Method, collect all the available tools.
2. 2.  Inform LLM : When building the prompt for LLM, the SDK will tell LLM the tool information (name, description, parameters, etc.) collected from the MCP service.
3. 3.  Execute the call : If the LLM decides to use a tool from the MCP service after thinking about it (for example, it decides to call filesystem.readFile), the Agents SDK will capture this intent and call the corresponding MCP service call_tool() Method and pass the parameters specified by LLM.
4. 4.  Return results : After the MCP service executes the tool call, it returns the result to the SDK, which then feeds the result to the LLM, allowing it to continue thinking about the next step or generate a final response.

The whole process is relatively transparent to us developers. We only need to "register" the MCP service to the Agent, and the SDK will handle the underlying communication and calling details for you.

This diagram clearly shows the entire process from the user issuing an instruction to how the SDK coordinates the LLM and MCP services to finally complete the task.

Performance Tip: Tool List Caching

You may have noticed that each time you run the Agent, the SDK will call list_tools()If your MCP service is a remote service (HTTP over SSE type), or list_tools() It is time consuming in itself, which may cause a little delay.

If the list of tools provided by your MCP service is relatively fixed (such as the file system service, its capabilities will basically not change), you can create MCPServerStdio or MCPServerSse When adding an object cache_tools_list=True This parameter:

mcp_server_filesystem = MCPServerStdio(
    params={...},
    cache_tools_list= True # Enable tool list cache 
)

After this setting, the SDK will only call list_tools(), and then the cached results will be used directly, which can save a lot of time.

Of course, if you know that the tool list of an MCP service has changed (for example, the service has been updated and new tools have been added), you need to manually invalidate the cache by calling the service object's invalidate_tools_cache() method.

MCP vs. writing Python utility functions directly

You may ask, since OpenAI Agents SDK itself also supports directly defining Python functions as tools, why do we need MCP? What is the difference between them?

Just a simple comparison:

How to choose?

• • If the logic of your tool is relatively simple, is only used in the current Python application, or needs to access the internal state of the application, then it may be more direct and convenient to define a Python function directly.
• • If you need to access an existing functional service that is written in other languages ​​or requires independent deployment and maintenance, and hope that this service can be reused by multiple different AI applications (possibly using different Agent frameworks), then MCP is an ideal choice.
• • If you want to build a general tool platform so that others can easily access your capabilities, implementing the MCP protocol is a good direction.

Debugging and tracing

When you use the MCP service, if there is a problem with the Agent running, how to troubleshoot it? Don't worry, the tracing function of the OpenAI Agents SDK also takes MCP into consideration. It will automatically record MCP-related operations, such as:

• • Call list_tools() process.
• • When the LLM decides to call an MCP tool, the relevant function call information (which tool was called, what parameters were passed, and what results were returned).

These trace information can help you figure out what happened between the SDK, LLM, and MCP services, making it much easier to locate the problem.

Having said so much

Well, that’s all I have to say about MCP in OpenAI Agents SDK today.

Simply put, MCP is intended to be the "universal standard interface" for AI applications to connect to external tools and data sources, a bit like USB-C in our hardware world. The OpenAI Agents SDK's support for MCP makes it easier for us to integrate various "capability plug-ins" (MCP services) that meet the specifications into our Agents, whether they are running locally or called remotely. This opens a new door to building more powerful, flexible, and open AI Agents.

Of course, MCP is still a relatively new thing, and the ecosystem is still developing. But I think this direction is right, and we may see more and more tool services based on MCP emerge in the future.

If you are interested in this, you can check out the OpenAI Agents SDK documentation for more details about MCP, or go directly to examples/mcp The complete sample code provided by Paopao is in the directory. Try it yourself and you will feel more real!

I am Lao Ma Xiao Zhang, an ordinary technical person who likes to dig into technical details. I hope today's sharing will inspire you! Next time I have the opportunity to talk to you about other interesting technical topics. See you later!