Client for managing MCP servers and sessions.
This class provides a unified interface for working with MCP servers,
handling configuration, connector creation, and session management.
```python theme={null}
from mcp_use.client.client import MCPClient
```
### `method` **init**
Initialize a new MCP client.
**Parameters**
> Either a dict containing configuration or a path to a JSON config file.
> Server name or configuration
> Whether to use sandboxed execution mode for running MCP servers.
> Optional sandbox configuration options.
> Optional sampling callback function.
> Callback function
> Parameter value
> Callback function
> Middleware instance
> Optional list of Root objects to advertise to servers.
> Optional custom callback for roots/list requests.
> Whether to enable code execution mode for tools.
> Boolean flag
**Signature**
```python wrap theme={null}
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**
> The middleware to add
**Signature**
```python wrap theme={null}
def add_middleware(middleware: mcp_use.client.middleware.middleware.Middleware):
```
### `method` add\_server
Add a server configuration.
**Parameters**
> The name to identify this server.
> The server configuration.
**Signature**
```python wrap theme={null}
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**
```python wrap theme={null}
def close_all_sessions():
```
### `method` close\_session
Close a session.
**Parameters**
> The name of the server to close the session for.
**Signature**
```python wrap theme={null}
def close_session(server_name: str):
```
### `method` create\_all\_sessions
Create sessions for all configured servers.
**Parameters**
> Whether to automatically initialize the sessions.
**Returns**
> Dictionary mapping server names to their MCPSession instances.
**Signature**
```python wrap theme={null}
def create_all_sessions(auto_initialize: bool = True):
```
### `method` create\_session
Create a session for the specified server.
**Parameters**
> The name of the server to create a session for.
> Whether to automatically initialize the session.
**Returns**
> The created MCPSession.
**Signature**
```python wrap theme={null}
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:
```python theme={null}
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**
> Python code to execute with tool access.
> Execution timeout in seconds.
**Returns**
>
**Signature**
```python wrap theme={null}
def execute_code(code: str, timeout: float = 30.0):
```
### `method` get\_all\_active\_sessions
Get all active sessions.
**Returns**
> Dictionary mapping server names to their MCPSession instances.
**Signature**
```python wrap theme={null}
def get_all_active_sessions():
```
### `method` get\_server\_names
Get the list of configured server names.
**Returns**
> List of server names (excludes internal code mode server).
**Signature**
```python wrap theme={null}
def get_server_names():
```
### `method` get\_session
Get an existing session.
**Parameters**
> The name of the server to get the session for.
**Returns**
> The MCPSession for the specified server.
**Signature**
```python wrap theme={null}
def get_session(server_name: str):
```
### `method` remove\_server
Remove a server configuration.
**Parameters**
> The name of the server to remove.
**Signature**
```python wrap theme={null}
def remove_server(name: str):
```
### `method` save\_config
Save the current configuration to a file.
**Parameters**
> The path to save the configuration to.
**Signature**
```python wrap theme={null}
def save_config(filepath: str):
```
### `method` search\_tools
Search available MCP tools across all active sessions.
Example:
```python theme={null}
# 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**
> Search query to filter tools by name or description.
> Level of detail to return:
**Returns**
> Level of detail to return: - "names": Only tool names and server - "descriptions": Names, server, and descriptions - "full": Complete tool information including schemas
**Signature**
```python wrap theme={null}
def search_tools(query: str = "", detail_level: str = "full"):
```