​

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, or WebSocket). For details on these connection types and how to configure them, see the Connection Types guide.

​

Configuration Options

• server_name: A unique identifier for your MCP server
• command: The command to start the MCP server
• args: Array of arguments to pass to the command
• env: Environment variables to set for the server

​

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.

​

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

​

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)

​

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