​

Configuration Guide

This guide covers all the configuration options available in mcp_use.

​

API Keys

Make sure to have the api key relative to the provider of your choice available in the environment you can either:

1 - Create .env file with your keys as:

# OpenAI
OPENAI_API_KEY=your_api_key_here
# Anthropic
ANTHROPIC_API_KEY=your_api_key_here
# Groq
GROQ_API_KEY=your_api_key_here

and load it in python using

from dotenv import load_dotenv
load_dotenv()

this will make all the keys defibned in .env available in yout python runtime, granted that you run from where the .env is located.

2 - Set it in your environment by running in your terminal the following command, e.g. for openai:

export OPENAI_API_KEY='..."

and then import it in your python code as:

import os
OPENAI_API_KEY = os.getenv(OPENAI_API_KEY,"")

or any other method you might prefer.

​

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.

​

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:

# Install mcp-use with E2B support
pip install "mcp-use[e2b]"

# Or install the dependency directly
pip install e2b-code-interpreter

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:

from mcp_use import MCPClient
from mcp_use.types.sandbox import SandboxOptions

# Define sandbox options
sandbox_options: SandboxOptions = {
    "api_key": "your_e2b_api_key",  # Or use E2B_API_KEY environment variable
    "sandbox_template_id": "code-interpreter-v1",
    "supergateway_command": "npx -y supergateway"  # Optional, this is the default
}

# Create client with sandboxed execution enabled
client = MCPClient.from_dict(
    {
        "mcpServers": {
            "command_line": {
                "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-everything"]
            }
        }
    },
    sandbox=True,
    sandbox_options=sandbox_options
)

​

Available Sandbox Options

The SandboxOptions type provides the following configuration options:

​

E2B API Key

To use sandboxed execution, you need an E2B API key. You can provide it in two ways:

1. Directly in the sandbox options:

   Copy

   Ask AI

   sandbox_options = {"api_key": "your_e2b_api_key"}
   

2. Through the environment variable:

   Copy

   Ask AI

   # In your .env file or environment
   E2B_API_KEY=your_e2b_api_key
   

For more details on connection types and sandbox configuration, see the Connection Types guide.

​

Agent Configuration

When creating an MCPAgent, you can configure several parameters:

from mcp_use import MCPAgent, MCPClient
from langchain_openai import ChatOpenAI

# Basic configuration
agent = MCPAgent(
    llm=ChatOpenAI(model="gpt-4o", temperature=0.7),
    client=MCPClient.from_config_file("config.json"),
    max_steps=30
)

# Advanced configuration
agent = MCPAgent(
    llm=ChatOpenAI(model="gpt-4o", temperature=0.7),
    client=MCPClient.from_config_file("config.json"),
    max_steps=30,
    server_name=None,
    auto_initialize=True,
    memory_enabled=True,
    system_prompt="Custom instructions for the agent",
    additional_instructions="Additional guidelines for specific tasks",
    disallowed_tools=["file_system", "network", "shell"]  # Restrict potentially dangerous tools
)

​

Available Parameters

• llm: Any LangChain-compatible language model (required)
• client: The MCPClient instance (optional if connectors are provided)
• connectors: List of connectors if not using client (optional)
• server_name: Name of the server to use (optional)
• max_steps: Maximum number of steps the agent can take (default: 5)
• auto_initialize: Whether to initialize automatically (default: False)
• memory_enabled: Whether to enable memory (default: True)
• system_prompt: Custom system prompt (optional)
• system_prompt_template: Custom system prompt template (optional)
• additional_instructions: Additional instructions for the agent (optional)
• disallowed_tools: List of tool names that should not be available to the agent (optional)

​

Tool Access Control

You can restrict which tools are available to the agent for security or to limit its capabilities:

# Create agent with restricted tools
agent = MCPAgent(
    llm=ChatOpenAI(model="gpt-4o"),
    client=client,
    disallowed_tools=["file_system", "network", "shell"]  # Restrict potentially dangerous tools
)

# Update restrictions after initialization
agent.set_disallowed_tools(["file_system", "network", "shell", "database"])
await agent.initialize()  # Reinitialize to apply changes

# Check current restrictions
restricted_tools = agent.get_disallowed_tools()
print(f"Restricted tools: {restricted_tools}")

This feature is useful for:

• Restricting access to sensitive operations
• Limiting agent capabilities for specific tasks
• Preventing the agent from using potentially dangerous tools
• Focusing the agent on specific functionality

​

Error Handling

mcp_use provides several ways to handle errors:

1. Connection Errors: Check your MCP server configuration and ensure the server is running
2. Authentication Errors: Verify your API keys are correctly set in the environment
3. Timeout Errors: Adjust the max_steps parameter if operations are timing out

​

Best Practices

1. Always use environment variables for sensitive information
2. Keep configuration files in version control (without sensitive data)
3. Use appropriate timeouts for different types of operations
4. Enable verbose logging during development
5. Test configurations in a development environment before production