Client

The Model Context Protocol (MCP) is an open protocol that defines a standardized way to provide context to large language models (LLMs). By using MCP, applications can seamlessly interact with LLMs in a structured and efficient manner, making it easier to exchange information, use external tools, and enhance the capabilities of language models in a consistent and reusable way.

This guide will walk you through how to create MCP clients that connect to MCP servers, enabling you to utilize external tools and processes efficiently.

Introduction to MCP#

MCP aims to standardize how applications provide contextual information to LLMs and how LLMs can access external tools. MCP servers expose specific tools that are accessible via different communication protocols, such as stdio (Standard Input/Output) and SSE (Server-Sent Events).

MCP clients are responsible for interacting with these servers, sending requests, and processing responses. By integrating MCP into your application, you can build systems where LLMs can utilize external computational tools in real-time.

In this guide, we will:

Set up an MCP server that exposes basic mathematical tools (add and multiply).
Connect the AG2 framework to this MCP server.
Communicate using two different transport protocols: stdio and SSE.

Installation#

To integrate MCP tools into the AG2 framework, install the required dependencies:

pip install -U ag2[openai,mcp]

Note: If you have been using autogen or pyautogen, all you need to do is upgrade it using:
pip install -U autogen[openai,mcp]
or
pip install -U pyautogen[openai,mcp]
as pyautogen, autogen, and ag2 are aliases for the same PyPI package.

Imports#

Before diving into the code, let’s go over the main imports used in this guide:

ClientSession: Manages the client session for connecting to the MCP server, allowing you to send requests and handle responses.
StdioServerParameters: Provides parameters to set up communication with an MCP server over stdio.
stdio_client: A utility that helps you connect to an MCP server using the standard input/output protocol.
sse_client: A utility to connect to an MCP server using the SSE (Server-Sent Events) protocol.
create_toolkit: A helper function that creates a toolkit, wrapping the tools exposed by the MCP server for easier access.

from pathlib import Path

from mcp import ClientSession, StdioServerParameters
from mcp.client.sse import sse_client
from mcp.client.stdio import stdio_client

from autogen import LLMConfig
from autogen.agentchat import AssistantAgent
from autogen.mcp import create_toolkit

# Only needed for Jupyter notebooks
import nest_asyncio

nest_asyncio.apply()

Setting Up an MCP Server#

We will create a simple MCP server that exposes two tools: add and multiply. The server listens for requests using either the stdio or SSE transport protocols, depending on the argument passed when starting the server.

For more details on creating MCP servers, visit the MCP Python SDK documentation.

Let's create a Python script (math_server.py) with the following content:

math_server_file_content = """# math_server.py
import argparse
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Math")

@mcp.tool()
def add(a: int, b: int) -> int:
    \"\"\"Add two numbers\"\"\"
    return a + b

@mcp.tool()
def multiply(a: int, b: int) -> int:
    \"\"\"Multiply two numbers\"\"\"
    return a * b

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Math Server")
    parser.add_argument("transport", choices=["stdio", "sse"], help="Transport mode (stdio or sse)")
    args = parser.parse_args()

    mcp.run(transport=args.transport)
"""

# Write content to a file
math_server_path = Path("math_server.py")
math_server_path.write_text(math_server_file_content)

Creating a Toolkit from MCP Tools#

To allow AG2 to interact with the MCP server, we need to establish a connection, create a toolkit from the tools exposed by the server, and then register this toolkit with an AG2 agent. The toolkit will provide the necessary functionality for AG2 to call the MCP tools, such as performing mathematical operations.

Steps to Create a Toolkit from MCP Tools

Wrap MCP tools into a toolkit: The tools exposed by the MCP server (like add and multiply) are wrapped into a toolkit for easy use by AG2.
Register the toolkit with an AG2 agent: This step allows AG2 to use the toolkit’s tools when processing requests.
Start a conversation: AG2 can now send a message to the MCP server requesting a task to be performed (e.g., adding two numbers) and receive the result.

async def create_toolkit_and_run(session: ClientSession) -> None:
    # Create a toolkit with available MCP tools
    toolkit = await create_toolkit(session=session)
    agent = AssistantAgent(name="assistant", llm_config=LLMConfig(model="gpt-4o-mini", api_type="openai"))
    # Register MCP tools with the agent
    toolkit.register_for_llm(agent)

    # Make a request using the MCP tool
    result = await agent.a_run(
        message="Add 123223 and 456789",
        tools=toolkit.tools,
        max_turns=2,
        user_input=False,
    )
    await result.process()

Setting Up the Client Session and Communicating with the MCP Server#

Once the toolkit is created, the next step is to connect AG2 to the MCP server and manage the communication between them. This involves setting up connection parameters and starting a client session, which will facilitate the entire interaction. After establishing the connection, AG2 can send requests and receive responses from the server.

Steps to Set Up the Client Session and Communicate with the MCP Server#

Set up connection parameters: Define how AG2 will communicate with the MCP server. This includes specifying the transport protocol (stdio or SSE) and other connection details.
Start a client session: This session facilitates communication between AG2 and the MCP server. The session is responsible for sending requests, receiving responses, and maintaining the connection state.

Using `stdio_client` for Communication#

Establish the connection in the client code by using the stdio_client requires:

Server Parameters: The connection is defined using the StdioServerParameters, where the command (python) runs the server (math_server.py) with stdio mode.
Connecting to the Server: The stdio_client establishes the connection to the server, and the ClientSession is used to facilitate communication.
Running the Task: Once the connection is established, create_toolkit_and_run(session) is called to wrap the MCP tools and perform the task asynchronously.

# Create server parameters for stdio connection
server_params = StdioServerParameters(
    command="python",  # The command to run the server
    args=[
        str(math_server_path),
        "stdio",
    ],  # Path to server script and transport mode
)

async with stdio_client(server_params) as (read, write), ClientSession(read, write) as session:
    # Initialize the connection
    await session.initialize()
    await create_toolkit_and_run(session)

Expected Output#

user (to assistant):

Add 123223 and 456789

--------------------------------------------------------------------------------
assistant (to user):

***** Suggested tool call (call_kO3xnTqJyOxTYaJCdyS1VOKw): add *****
Arguments:
{"a": 123223, "b": 456789}
********************************************************************

--------------------------------------------------------------------------------

>>>>>>>> EXECUTING FUNCTION add...
Call ID: call_kO3xnTqJyOxTYaJCdyS1VOKw
Input arguments: {'a': 123223, 'b': 456789}
user (to assistant):

***** Response from calling tool (call_kO3xnTqJyOxTYaJCdyS1VOKw) *****
('580012', None)
**********************************************************************

--------------------------------------------------------------------------------
assistant (to user):

The sum of 123223 and 456789 is 580012.

TERMINATE

Using `sse_client` for Communication#

To interact with the MCP server via SSE, follow these steps:

Open new terminal and start the server using the sse transport mode:
```
python math_server.py sse
```
- Once the server is running, rstablish the connection in the client code by using the sse_client:
Server URL: The sse_client connects to the SSE server running locally at http://127.0.0.1:8000/sse.
Connecting to the Server: The sse_client establishes an SSE connection, and the ClientSession is used to manage the communication with the server.
Running the Task: Once the session is initialized, create_toolkit_and_run(session) is called to create the toolkit from MCP tools and perform the task.

async with sse_client(url="http://127.0.0.1:8000/sse") as streams, ClientSession(*streams) as session:
    # Initialize the connection
    await session.initialize()
    await create_toolkit_and_run(session)

Expected Output#

user (to assistant):

Add 123223 and 456789

--------------------------------------------------------------------------------
assistant (to user):

***** Suggested tool call (call_kO3xnTqJyOxTYaJCdyS1VOKw): add *****
Arguments:
{"a": 123223, "b": 456789}
********************************************************************

--------------------------------------------------------------------------------

>>>>>>>> EXECUTING FUNCTION add...
Call ID: call_kO3xnTqJyOxTYaJCdyS1VOKw
Input arguments: {'a': 123223, 'b': 456789}
user (to assistant):

***** Response from calling tool (call_kO3xnTqJyOxTYaJCdyS1VOKw) *****
('580012', None)
**********************************************************************

--------------------------------------------------------------------------------
assistant (to user):

The sum of 123223 and 456789 is 580012.

TERMINATE

Client

Introduction to MCP#

Installation#

Imports#

Setting Up an MCP Server#

Creating a Toolkit from MCP Tools#

Setting Up the Client Session and Communicating with the MCP Server#

Steps to Set Up the Client Session and Communicate with the MCP Server#

Using stdio_client for Communication#

Expected Output#

Using sse_client for Communication#

Expected Output#

Using `stdio_client` for Communication#

Using `sse_client` for Communication#