​
Client Configuration

This guide covers MCPClient configuration options for connecting to MCP servers. For agent configuration, see the Agent Configuration guide.

​
MCP Server Configuration

mcp_use supports any MCP server through a flexible configuration system. (For a list of awesome servers you can visit https://github.com/punkpeye/awesome-mcp-servers or https://github.com/appcypher/awesome-mcp-servers which have an amazing collection of them) The configuration is defined in a JSON file with the following structure: 
{
  "mcpServers": {
    "server_name": {
      "command": "command_to_run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}
MCP servers can use different connection types (STDIO, HTTP). For details on these connection types and how to configure them, see the Connection Types guide. Each server entry in the mcpServers object has a server_name and then specific options depending on how mcp-use should connect to and/or manage the server.
  • server_name: (Required) A unique string identifier for this MCP server configuration. This name is used to select the server, for example, in agent.run(..., server_name="your_server_name").
For STDIO-based servers (local): These are servers that mcp-use will start and manage as local child processes, communicating via their standard input/output streams.
  • command: (Required) The executable command to start the server (e.g., "npx", "python").
  • args: (Optional) An array of string arguments to pass to the command (e.g., ["-y", "@playwright/mcp@latest"]).
  • env: (Optional) An object defining environment variables to set for the server’s process (e.g., {"DISPLAY": ":1"}).
For HTTP/HTTPS-based servers (SSE and Streamable HTTP) These are servers that are typically already running and accessible via an HTTP(S) endpoint. mcp-use acts as an HTTP client to communicate with them.
  • url: (Required) The full URL where the MCP server is listening (e.g., "http://localhost:7777/mcp", "https://api.example.com/mcp").
  • headers: (Optional) An object containing custom HTTP headers to be sent with every request to this server (e.g., for authentication: {"Authorization": "Bearer your_api_token"}).
Additional options might be available depending on the specific connection type or wrappers used. Always refer to the Connection Types documentation for the most detailed and up-to-date specifications for each type.

​
Example Configuration

Here’s a basic example of how to configure an MCP server: 
{
  "mcpServers": {
    "my_server": {
      "command": "npx",
      "args": ["@my-mcp/server"],
      "env": {
        "PORT": "3000"
      }
    }
  }
}

​
Multiple Server Configuration

You can configure multiple MCP servers in a single configuration file, allowing you to use different servers for different tasks or combine their capabilities (e.g.): 
{
  "mcpServers": {
    "airbnb": {
      "command": "npx",
      "args": ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"]
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": { "DISPLAY": ":1" }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/pietro/projects/mcp-use/"
      ]
    }
  }
}
For a complete example of using multiple servers, see the multi-server example in our repository.

​
Client Creation Methods

There are several ways to create an MCPClient:

​
From Dictionary

Create configuration programmatically: 
from mcp_use import MCPClient

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

client = MCPClient(config)

​
From Configuration File

Load configuration from a JSON file: 
from mcp_use import MCPClient

client = MCPClient.from_config_file("config.json")

​
With Sandbox Options

Enable sandboxed execution: 
from mcp_use import MCPClient
from mcp_use.types.sandbox import SandboxOptions

sandbox_options: SandboxOptions = {
    "api_key": "your_e2b_api_key",
    "sandbox_template_id": "code-interpreter-v1"
}

client = MCPClient.from_dict(
    config,
    sandbox=True,
    sandbox_options=sandbox_options
)

​
Best Practices

  1. API Keys: Always use environment variables for sensitive information
  2. Configuration Files: Keep configuration files in version control (without sensitive data)
  3. Server Naming: Use descriptive names for your MCP servers
  4. Environment Variables: Set appropriate environment variables for each server
  5. Testing: Test server connections independently before using with agents
  6. Monitoring: Enable logging to monitor server connection health

​
Error Handling

Common client configuration errors and solutions:
  1. Server Not Found: Check if the server command is installed and accessible
  2. Connection Timeout: Verify server is running and network connectivity
  3. Permission Denied: Ensure proper file permissions and environment setup
  4. Invalid Configuration: Validate JSON syntax and required fields
For detailed troubleshooting, see the Connection Errors guide.