mcp-use - The fullstack MCP framework to develop MCP Apps for ChatGPT / Claude and MCP Servers for AI Agents.

Quick Start

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.

MCPClient Constructor Parameters

str | dict | None

default:"None"

Path to a JSON configuration file or a configuration dictionary containing server definitions

list[str] | None

default:"None"

Restrict which servers from the config to use. When set, only the specified servers will be available

bool | None

default:"True"

SSL certificate verification for HTTP/HTTPS servers. Set to False for self-signed certificates or internal servers

bool

default:"False"

Run MCP servers in an isolated E2B sandbox environment. See Sandbox for configuration

SandboxOptions | None

default:"None"

E2B sandbox configuration including api_key and sandbox_template_id. Required when sandbox=True. See Sandbox

bool

default:"False"

Enable Python code execution mode for interacting with MCP tools programmatically. See Code Mode

list[Middleware] | None

default:"None"

Custom middleware for intercepting and processing tool calls. See Middleware

list[Root] | None

default:"None"

Directories or files to advertise to servers. Roots inform servers about accessible filesystem locations. See Roots

ListRootsFnT | None

default:"None"

Custom callback to handle roots/list requests from servers. Overrides the static roots parameter with dynamic responses

SamplingFnT | None

default:"None"

Handle server-initiated sampling requests (LLM completions). Required for servers that use sampling. See Sampling

ElicitationFnT | None

default:"None"

Handle server requests for user input or decisions. See Elicitation

MessageHandlerFnT | None

default:"None"

Handle server notifications and messages. See Notifications

LoggingFnT | None

default:"None"

Handle server log messages. See Logging

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:

{
  "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:

{
  "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)

WebSocket Servers

Servers accessible via WebSocket:

{
  "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:

{
  "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_..."}
    }
  }
}

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 for details.

Alternative Constructors

from_dict

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

from_config_file

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

Get Started

MCP Server

MCP Client

MCP Agents

Development

Client Configuration

Quick Start

MCPClient Parameters

MCPClient Constructor Parameters

Server Configuration

STDIO Servers (Local)

HTTP Servers (Remote)

WebSocket Servers

Multiple Servers

Alternative Constructors

from_dict

from_config_file

Common Issues

​Quick Start

​MCPClient Parameters

MCPClient Constructor Parameters

​Server Configuration

​STDIO Servers (Local)

​HTTP Servers (Remote)

​WebSocket Servers

​Multiple Servers

​Alternative Constructors

​from_dict

​from_config_file

​Common Issues

Quick Start

MCPClient Parameters

Server Configuration

STDIO Servers (Local)

HTTP Servers (Remote)

WebSocket Servers

Multiple Servers

Alternative Constructors

from_dict

from_config_file

Common Issues