> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-use.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://mcp-use.com/docs/feedback

```json
{
  "path": "/python/client/client-configuration",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Client Configuration

> Configure MCPClient for connecting to MCP servers

## Quick Start

```python theme={null}
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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
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 theme={null}
client = MCPClient.from_dict(
    config={"mcpServers": {...}},
    verify=False,
    sandbox=True
)
```

### from\_config\_file

```python theme={null}
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       |