Client Configuration
Configure MCPClient for connecting to MCP servers
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:
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, inagent.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 thecommand
(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:
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.):
For a complete example of using multiple servers, see the multi-server example in our repository.
Working with Multiple Servers
The MCPClient
can be configured with multiple MCP servers, allowing your agent to access tools from different sources. This capability enables complex workflows spanning various domains (e.g., web browsing and API interaction).
When an MCPClient
with multiple servers is passed to an MCPAgent
, the agent gains access to tools from all configured servers. By default, you might need to guide the agent or explicitly specify which server to use for a given task using the server_name
parameter in the agent.run()
method.
Sandboxed Execution
mcp_use supports running MCP servers in a sandboxed cloud environment using E2B. This is useful when you want to run MCP servers without having to install their dependencies locally.
Installation
To use sandboxed execution, you need to install the E2B dependency:
You’ll also need an E2B API key. You can sign up at e2b.dev to get your API key.
Configuration Example
To enable sandboxed execution, use the sandbox parameter when creating the MCPClient:
Available Sandbox Options
The SandboxOptions
type provides the following configuration options:
Option | Description | Default |
---|---|---|
api_key | E2B API key. Required - can be provided directly or via E2B_API_KEY environment variable | None |
sandbox_template_id | Template ID for the sandbox environment | ”base” |
supergateway_command | Command to run supergateway | ”npx -y supergateway” |
E2B API Key
To use sandboxed execution, you need an E2B API key. You can provide it in two ways:
-
Directly in the sandbox options:
-
Through the environment variable:
For more details on connection types and sandbox configuration, see the Connection Types guide.
Client Creation Methods
There are several ways to create an MCPClient:
From Configuration File
Load configuration from a JSON file:
From Dictionary
Create configuration programmatically:
With Sandbox Options
Enable sandboxed execution:
Best Practices
- API Keys: Always use environment variables for sensitive information
- Configuration Files: Keep configuration files in version control (without sensitive data)
- Server Naming: Use descriptive names for your MCP servers
- Environment Variables: Set appropriate environment variables for each server
- Testing: Test server connections independently before using with agents
- Monitoring: Enable logging to monitor server connection health
Error Handling
Common client configuration errors and solutions:
- Server Not Found: Check if the server command is installed and accessible
- Connection Timeout: Verify server is running and network connectivity
- Permission Denied: Ensure proper file permissions and environment setup
- Invalid Configuration: Validate JSON syntax and required fields
For detailed troubleshooting, see the Connection Errors guide.