mcp-use__mcp-use/docs/python/client/client-configuration.mdx

---
title: "Client Configuration"
description: "Configure MCPClient for connecting to MCP servers"
icon: "server"
---

## Quick Start

```python
from mcp_use import MCPClient

# From config file
client = MCPClient("config.json")

# From dictionary
client = MCPClient({
    "mcpServers": {
        "playwright": {
            "command": "npx",
            "args": ["@playwright/mcp@latest"]
        }
    }
})

# Create sessions and use
await client.create_all_sessions()
session = client.get_session("playwright")
tools = await session.list_tools()

# Clean up when done
await client.close_all_sessions()
```

## MCPClient Parameters

`MCPClient` is the main entry point for connecting to MCP servers. It provides flexible configuration for SSL, sandboxing, middleware, and server-initiated callbacks.

<Card title="MCPClient Constructor Parameters">

<ParamField body="config" type="str | dict | None" default="None">
  Path to a JSON configuration file or a configuration dictionary containing server definitions
</ParamField>

<ParamField body="allowed_servers" type="list[str] | None" default="None">
  Restrict which servers from the config to use. When set, only the specified servers will be available
</ParamField>

<ParamField body="verify" type="bool | None" default="True">
  SSL certificate verification for HTTP/HTTPS servers. Set to `False` for self-signed certificates or internal servers
</ParamField>

<ParamField body="sandbox" type="bool" default="False">
  Run MCP servers in an isolated E2B sandbox environment. See [Sandbox](/python/client/sandbox) for configuration
</ParamField>

<ParamField body="sandbox_options" type="SandboxOptions | None" default="None">
  E2B sandbox configuration including `api_key` and `sandbox_template_id`. Required when `sandbox=True`. See [Sandbox](/python/client/sandbox)
</ParamField>

<ParamField body="code_mode" type="bool" default="False">
  Enable Python code execution mode for interacting with MCP tools programmatically. See [Code Mode](/python/client/code-mode)
</ParamField>

<ParamField body="middleware" type="list[Middleware] | None" default="None">
  Custom middleware for intercepting and processing tool calls. See [Middleware](/python/client/middleware)
</ParamField>

<ParamField body="roots" type="list[Root] | None" default="None">
  Directories or files to advertise to servers. Roots inform servers about accessible filesystem locations. See [Roots](/python/client/roots)
</ParamField>

<ParamField body="list_roots_callback" type="ListRootsFnT | None" default="None">
  Custom callback to handle `roots/list` requests from servers. Overrides the static `roots` parameter with dynamic responses
</ParamField>

<ParamField body="sampling_callback" type="SamplingFnT | None" default="None">
  Handle server-initiated sampling requests (LLM completions). Required for servers that use sampling. See [Sampling](/python/client/sampling)
</ParamField>

<ParamField body="elicitation_callback" type="ElicitationFnT | None" default="None">
  Handle server requests for user input or decisions. See [Elicitation](/python/client/elicitation)
</ParamField>

<ParamField body="message_handler" type="MessageHandlerFnT | None" default="None">
  Handle server notifications and messages. See [Notifications](/python/client/notifications)
</ParamField>

<ParamField body="logging_callback" type="LoggingFnT | None" default="None">
  Handle server log messages. See [Logging](/python/client/logging)
</ParamField>

</Card>

---

## Server Configuration

MCP servers are configured in the `mcpServers` object. Each server has a unique name and connection settings.

### STDIO Servers (Local)

Servers that run as local processes:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {"DISPLAY": ":1"}
    }
  }
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `command` | Yes | Executable to run (`npx`, `python`, etc.) |
| `args` | No | Arguments to pass to the command |
| `env` | No | Environment variables for the process |

### HTTP Servers (Remote)

Servers accessible via HTTP/HTTPS:

```json
{
  "mcpServers": {
    "remote_server": {
      "url": "https://api.example.com/mcp",
      "headers": {"Authorization": "Bearer token123"}
    }
  }
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `url` | Yes | Server URL (supports SSE and Streamable HTTP) |
| `headers` | No | HTTP headers for authentication |
| `timeout` | No | Connection timeout in seconds (default: 5) |
| `sse_read_timeout` | No | SSE read timeout in seconds (default: 300) |
| `auth` | No | Authentication config (see [Authentication](/python/client/authentication)) |

### WebSocket Servers

Servers accessible via WebSocket:

```json
{
  "mcpServers": {
    "ws_server": {
      "ws_url": "wss://api.example.com/mcp",
      "headers": {"Authorization": "Bearer token123"}
    }
  }
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `ws_url` | Yes | WebSocket URL |
| `headers` | No | HTTP headers for the upgrade request |
| `auth` | No | Bearer token string |

---

## Multiple Servers

Configure multiple servers for different capabilities:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_TOKEN": "ghp_..."}
    }
  }
}
```

```python
client = MCPClient("config.json")
await client.create_all_sessions()

# Access specific server
playwright = client.get_session("playwright")
github = client.get_session("github")
```

See [Multi-Server Setup](/python/client/multi-server-setup) for details.

---

## Alternative Constructors

### from_dict

```python
client = MCPClient.from_dict(
    config={"mcpServers": {...}},
    verify=False,
    sandbox=True
)
```

### from_config_file

```python
client = MCPClient.from_config_file(
    filepath="config.json",
    verify=False,
    sandbox=True
)
```

Both accept the same parameters as `MCPClient()`.

---

## Common Issues

| Error | Cause | Solution |
|-------|-------|----------|
| `Server 'x' not found` | Server name not in config | Check spelling, verify config file |
| `SSL certificate error` | Self-signed cert or internal server | Set `verify=False` |
| `Connection timeout` | Server not running or unreachable | Check server URL/command, network |
| `Permission denied` | Missing permissions for command | Check file permissions, PATH |