Client

View the source code for this module on GitHub: https://github.com/mcp-use/mcp-use/blob/main/libraries/python/mcp_use/client/client.py

Client for managing MCP servers and sessions. This module provides a high-level client that manages MCP servers, connectors, and sessions from configuration.

MCPClient

from mcp_use.client.client import MCPClient

`method` init

Initialize a new MCP client.Parameters

str | dict[str, typing.Any] | None
default:"None"
Either a dict containing configuration or a path to a JSON config file.

list[str] | None
default:"None"
Server name or configuration

bool
default:"False"
Whether to use sandboxed execution mode for running MCP servers.

mcp_use.client.connectors.sandbox.SandboxOptions | None
default:"None"
Optional sandbox configuration options.

mcp.client.session.SamplingFnT | None
default:"None"
Optional sampling callback function.

mcp.client.session.ElicitationFnT | None
default:"None"
Callback function

mcp.client.session.MessageHandlerFnT | None
default:"None"
Parameter value

mcp.client.session.LoggingFnT | None
default:"None"
Callback function

list[mcp_use.client.middleware.middleware.Middleware] | None
default:"None"
Middleware instance

list[mcp.types.Root] | None
default:"None"
Optional list of Root objects to advertise to servers.

mcp.client.session.ListRootsFnT | None
default:"None"
Optional custom callback for roots/list requests.

bool
default:"False"
Whether to enable code execution mode for tools.

bool | None
default:"True"
Boolean flag

Signature

def __init__(config: str | dict[str, typing.Any] | None = None, allowed_servers: list[str] | None = None, sandbox: bool = False, sandbox_options: mcp_use.client.connectors.sandbox.SandboxOptions | None = None, sampling_callback: mcp.client.session.SamplingFnT | None = None, elicitation_callback: mcp.client.session.ElicitationFnT | None = None, message_handler: mcp.client.session.MessageHandlerFnT | None = None, logging_callback: mcp.client.session.LoggingFnT | None = None, middleware: list[mcp_use.client.middleware.middleware.Middleware] | None = None, roots: list[mcp.types.Root] | None = None, list_roots_callback: mcp.client.session.ListRootsFnT | None = None, code_mode: bool = False, verify: bool | None = True):

`method` add_middleware

Add a middleware.Parameters

mcp_use.client.middleware.middleware.Middleware
required
The middleware to add

Signature

def add_middleware(middleware: mcp_use.client.middleware.middleware.Middleware):

`method` add_server

Add a server configuration.Parameters

str
required
The name to identify this server.

dict[str, Any]
required
The server configuration.

Signature

def add_server(name: str, server_config: dict[str, Any]):

`method` close_all_sessions

Close all active sessions.This method ensures all sessions are closed even if some fail.Signature

def close_all_sessions():

`method` close_session

Close a session.Parameters

str
required
The name of the server to close the session for.

Signature

def close_session(server_name: str):

`method` create_all_sessions

Create sessions for all configured servers.Parameters

bool
default:"True"
Whether to automatically initialize the sessions.

Returns

dict[str, mcp_use.client.session.MCPSession]
Dictionary mapping server names to their MCPSession instances.

Signature

def create_all_sessions(auto_initialize: bool = True):

`method` create_session

Create a session for the specified server.Parameters

str
required
The name of the server to create a session for.

bool
default:"True"
Whether to automatically initialize the session.

Returns

mcp_use.client.session.MCPSession | None
The created MCPSession.

Signature

def create_session(server_name: str, auto_initialize: bool = True):

`method` execute_code

Execute Python code with access to MCP tools (code mode).This method allows agents to interact with MCP tools through Python code instead of direct tool calls, enabling more efficient context usage and data processing.Example:

client = MCPClient(config="config.json", code_mode=True)
await client.create_all_sessions()

result = await client.execute_code('''
tools = await search_tools("github")
print(f"Found \{len(tools)\} tools")

pr = await github.get_pull_request(
    owner="facebook",
    repo="react",
    number=12345
)
return \{"title": pr["title"]\}
''')

print(result['result'])  # \{'title': 'Fix bug in...'\}
print(result['logs'])    # ['Found 5 tools']

Parameters

str
required
Python code to execute with tool access.

float
default:"30.0"
Execution timeout in seconds.

Returns

dict[str, Any]

Signature

def execute_code(code: str, timeout: float = 30.0):

`method` get_all_active_sessions

Get all active sessions.Returns

dict[str, mcp_use.client.session.MCPSession]
Dictionary mapping server names to their MCPSession instances.

Signature

def get_all_active_sessions():

`method` get_server_names

Get the list of configured server names.Returns

list[str]
List of server names (excludes internal code mode server).

Signature

def get_server_names():

`method` get_session

Get an existing session.Parameters

str
required
The name of the server to get the session for.

Returns

mcp_use.client.session.MCPSession
The MCPSession for the specified server.

Signature

def get_session(server_name: str):

`method` remove_server

Remove a server configuration.Parameters

str
required
The name of the server to remove.

Signature

def remove_server(name: str):

`method` save_config

Save the current configuration to a file.Parameters

str
required
The path to save the configuration to.

Signature

def save_config(filepath: str):

`method` search_tools

Search available MCP tools across all active sessions.Example:

# Search for GitHub-related tools
result = await client.search_tools("github pull")
print(f"Found \{result['meta']['result_count']\} tools out of \{result['meta']['total_tools']\} total")
for tool in result['results']:
    print(f"\{tool['server']\}.\{tool['name']\}: \{tool['description']\}")

Parameters

str
default:""
Search query to filter tools by name or description.

str
default:"full"
Level of detail to return:

Returns

dict[str, Any]
Level of detail to return: - “names”: Only tool names and server - “descriptions”: Names, server, and descriptions - “full”: Complete tool information including schemas

Signature

def search_tools(query: str = "", detail_level: str = "full"):

Agents

Core

Errors

Server

Client

MCPClient

`method` init

`method` add_middleware

`method` add_server

`method` close_all_sessions

`method` close_session

`method` create_all_sessions

`method` create_session

`method` execute_code

`method` get_all_active_sessions

`method` get_server_names

`method` get_session

`method` remove_server

`method` save_config

`method` search_tools

​MCPClient

​method init

​method add_middleware

​method add_server

​method close_all_sessions

​method close_session

​method create_all_sessions

​method create_session

​method execute_code

​method get_all_active_sessions

​method get_server_names

​method get_session

​method remove_server

​method save_config

​method search_tools

MCPClient

`method` init

`method` add_middleware

`method` add_server

`method` close_all_sessions

`method` close_session

`method` create_all_sessions

`method` create_session

`method` execute_code

`method` get_all_active_sessions

`method` get_server_names

`method` get_session

`method` remove_server

`method` save_config

`method` search_tools