OpenAI MCP Agents

This project is an SDK that integrates Model Context Protocol (MCP) into OpenAI Agents. It allows you to easily provide MCP server functionality as tools for OpenAI Agents to use.

Features

• Supports two connection types:
  • Stdio connection: Communicate with local processes via standard input/output
  • SSE connection: Communicate with remote servers via Server-Sent Events
• Supports two usage patterns:
  • Using async context manager (async with) for automatic connection management
  • Manual connection management via connect() and disconnect() methods
• Support for connecting to multiple MCP servers
• Full type hint support
• Detailed example code provided

Installation

Using uv (Recommended)

uv install git+https://github.com/madroidmaq/openai-mcp-agents.git

Using pip

pip install git+https://github.com/madroidmaq/openai-mcp-agents.git

Development Environment Setup

If you want to contribute to the project, you can set up your development environment as follows:

# Clone the repository
git clone https://github.com/madroidmaq/openai-mcp-agents.git
cd openai-mcp-agents

# Create a virtual environment and install dependencies using uv
uv venv
source .venv/bin/activate  # On Windows use .venv\Scripts\activate
uv pip install -e .

Usage Examples

Single Server Connection

from openai_mcp_agents.mcp_agent import McpAgent
from mcp import StdioServerParameters

# Configure MCP server
server_params = StdioServerParameters(
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
)

# Using async context manager
async with McpAgent(
    name="Filesystem Assistant",
    instructions="You are a filesystem assistant",
    mcp_server=server_params,
    model="gpt-4"
) as agent:
    result = await Runner.run(
        agent,
        input="Please list all files in the directory.",
        context={}
    )
    print(result.final_output)

Multiple Server Connection

from openai_mcp_agents.mcp_agent import MultiServerMCPClient

async with MultiServerMCPClient({
    "math": {
        "command": "python",
        "args": ["/path/to/math_server.py"],
        "transport": "stdio",
    },
    "weather": {
        "url": "http://localhost:8000/sse",
        "transport": "sse",
    }
}) as client:
    all_tools = client.get_tools()
    # Use the tools...

API Documentation

McpAgent

McpAgent class inherits from Agent class and is used to connect to a single MCP server.

class McpAgent(Agent):
    def __init__(self,
        mcp_server: Optional[Union[StdioServerParameters, StdioConnection, SSEConnection]] = None,
        **kwargs):
        ...

MultiServerMCPClient

MultiServerMCPClient class is used to connect to multiple MCP servers simultaneously.

class MultiServerMCPClient(Agent):
    def __init__(self,
        connections: Optional[Dict[str, Union[StdioConnection, SSEConnection]]] = None,
        name: str = "MultiServerMCPClient",
        **kwargs):
        ...

Contributing

Issues and Pull Requests are welcome!

Contribution Process

1. Fork this repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

This project uses Black for code formatting and mypy for type checking. Please ensure you run these tools before submitting your code.

black src tests examples
mypy src

License

Apache License 2.0

Support

If you encounter any issues while using this project, please get support through the following channels:

1. Check the documentation
2. Submit an Issue
3. Send an email to madroidmaq@gmail.com