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

This guide covers MCPAgent configuration options for customizing agent behavior and LLM integration. For client configuration, see the Client Configuration guide.

API Keys

Never hardcode API keys in your source code. Always use environment variables for security.

Since agents use LLM providers that require API keys, you need to configure them properly:

.env File (Recommended)
Environment Variables
System Configuration

Create a .env file in your project root:

.env

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

Load it in your application:

    from dotenv import load_dotenv
    load_dotenv()

This method keeps your keys organized and makes them available to your Python runtime.

Set environment variables directly in your terminal:

export OPENAI_API_KEY="your_api_key_here"
export ANTHROPIC_API_KEY="your_api_key_here"

Access them in your application:

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

Agent Parameters

When creating an MCPAgent, you can configure several parameters to customize its behavior:

from mcp_use import MCPAgent, MCPClient
from langchain_openai import ChatOpenAI

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

# Advanced configuration
agent = MCPAgent(
    llm=ChatOpenAI(model="gpt-5.5", 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)
use_server_manager: Enable dynamic server selection (default: False)

Sending Files with HumanMessage

Pass files directly inside a HumanMessage instead of using a separate parameter. The agent accepts either a plain string or a HumanMessage, so you can include both text and file content together:

import asyncio
import base64
from pathlib import Path

from langchain_core.messages import HumanMessage
from langchain_openai import ChatOpenAI

from mcp_use import MCPAgent, MCPClient


async def main():
    client = MCPClient(config = {})
    agent = MCPAgent(
        llm=ChatOpenAI(model="gpt-5.5", temperature=0),
        client=client,
    )

    image_bytes = base64.b64encode(
        Path("static/logo-gh.jpg").read_bytes()
    ).decode("utf-8")
    human_message = HumanMessage(
        content=[
            {"type": "text", "text": "What is in this image?"},
            {
                "type": "image",
                "base64": image_bytes,
                "mime_type": "image/jpeg",
            },
        ]
    )

    async for step in agent.stream(human_message, max_steps=10):
        print(step)


if __name__ == "__main__":
    asyncio.run(main())

Remote agents currently accept text-only HumanMessage content. Use a local agent when you need to pass files.

Tool Access Control

You can restrict which tools are available to the agent for security or to limit its capabilities. Here’s a complete example showing how to set up an agent with restricted tool access:

import asyncio
import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from mcp_use import MCPAgent, MCPClient

async def main():
    # Load environment variables
    load_dotenv()

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

    # Create MCPClient from configuration dictionary
    client = MCPClient(config)

    # Create LLM
    llm = ChatOpenAI(model="gpt-5.5")

    # Create agent with restricted tools
    agent = MCPAgent(
        llm=llm,
        client=client,
        max_steps=30,
        disallowed_tools=["file_system", "network"]  # Restrict potentially dangerous tools
    )

    # Run the query
    result = await agent.run(
        "Find the best restaurant in San Francisco USING GOOGLE SEARCH",
    )
    print(f"\nResult: {result}")

if __name__ == "__main__":
    asyncio.run(main())

You can also manage tool restrictions dynamically:

# 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

Working with Adapters Directly

If you want more control over how tools are created, you can work with the adapters directly. The BaseAdapter class provides a unified interface for converting MCP tools to various framework formats, with LangChainAdapter being the most commonly used implementation.

import asyncio
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model

from mcp_use.client import MCPClient
from mcp_use.adapters import LangChainAdapter

async def main():
    # Initialize client
    client = MCPClient.from_config_file("browser_mcp.json")

    # Create an adapter instance
    adapter = LangChainAdapter()

    # Get tools directly from the client
    tools = await adapter.create_tools(client)

    # Use the tools with any LangChain agent
    model = init_chat_model("gpt-5.5", temperature=0.5)

    agent = create_agent(
        model=model,
        tools=tools,
        system_prompt="You are a helpful assistant with access to powerful tools.",
    )

    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "Search for information about climate change"}]}
    )
    print(result)

if __name__ == "__main__":
    asyncio.run(main())

The adapter pattern makes it easy to:

Create tools directly from an MCPClient
Filter or customize which tools are available
Integrate with different agent frameworks

Benefits of Direct Adapter Usage:

Flexibility: More control over tool creation and management
Custom Integration: Easier to integrate with existing LangChain workflows
Advanced Filtering: Apply custom logic to tool selection and configuration
Framework Agnostic: Potential for future adapters to other frameworks

Server Manager

The Server Manager is an agent-level feature that enables dynamic server selection for improved performance with multi-server setups.

Enabling Server Manager

To improve efficiency and potentially reduce agent confusion when many tools are available, you can enable the Server Manager by setting use_server_manager=True when creating the MCPAgent.

# Enable server manager for automatic server selection
agent = MCPAgent(
    llm=llm,
    client=client,
    use_server_manager=True  # Enable dynamic server selection
)

How It Works

When enabled, the agent will automatically select the appropriate server based on the tool chosen by the LLM for each step. This avoids connecting to unnecessary servers and can improve performance with large numbers of available servers.

# Multi-server setup with server manager
client = MCPClient.from_config_file("multi_server_config.json")
agent = MCPAgent(
    llm=llm,
    client=client,
    use_server_manager=True
)

# The agent automatically selects servers based on tool usage
result = await agent.run(
    "Search for a place in Barcelona on Airbnb, then Google nearby restaurants."
)

Benefits

Performance: Only connects to servers when their tools are actually needed
Reduced Confusion: Agents work better with focused tool sets rather than many tools at once
Resource Efficiency: Saves memory and connection overhead
Automatic Selection: No need to manually specify server_name for most use cases
Scalability: Better performance with large numbers of servers

When to Use

Multi-server environments: Essential for setups with 3+ servers
Resource-constrained environments: When memory or connection limits are a concern
Complex workflows: When agents need to dynamically choose between different tool categories
Production deployments: For better resource management and performance

For more details on server manager implementation, see the Server Manager guide.

Memory Configuration

MCPAgent supports conversation memory to maintain context across interactions:

# Enable memory (default)
agent = MCPAgent(
    llm=llm,
    client=client,
    memory_enabled=True
)

# Disable memory for stateless interactions
agent = MCPAgent(
    llm=llm,
    client=client,
    memory_enabled=False
)

System Prompt Customization

You can customize the agent’s behavior through system prompts:

Custom System Prompt

custom_prompt = """
You are a helpful assistant specialized in data analysis.
Always provide detailed explanations for your reasoning.
When working with data, prioritize accuracy over speed.
"""

agent = MCPAgent(
    llm=llm,
    client=client,
    system_prompt=custom_prompt
)

Additional Instructions

Add task-specific instructions without replacing the base system prompt:

agent = MCPAgent(
    llm=llm,
    client=client,
    additional_instructions="Focus on finding recent information from the last 6 months."
)

System Prompt Templates

For more advanced customization, you can provide a custom system prompt template:

from langchain_core.prompts import ChatPromptTemplate

custom_template = ChatPromptTemplate.from_messages([
    ("system", "You are an expert {domain} assistant. {instructions}"),
    ("human", "{input}"),
    # ... other message templates
])

agent = MCPAgent(
    llm=llm,
    client=client,
    system_prompt_template=custom_template
)

Performance Configuration

Configure agent performance characteristics:

# Limit execution steps
agent = MCPAgent(
    llm=llm,
    client=client,
    max_steps=10  # Prevent runaway execution
)

# Enable server manager for better performance with multiple servers
agent = MCPAgent(
    llm=llm,
    client=client,
    use_server_manager=True  # Only connects servers when needed
)

# Limit concurrent servers (if not using server manager)
agent = MCPAgent(
    llm=llm,
    client=client,
    max_concurrent_servers=3
)

Debugging Configuration

Enable debugging features during development:

# Enable verbose logging
agent = MCPAgent(
    llm=llm,
    client=client,
    verbose=True,
    debug=True
)

# Set debug level programmatically
import mcp_use
mcp_use.set_debug(2)  # Full verbose logging

Agent Initialization

Control when and how the agent initializes:

# Auto-initialize on creation
agent = MCPAgent(
    llm=llm,
    client=client,
    auto_initialize=True
)

# Manual initialization for more control
agent = MCPAgent(
    llm=llm,
    client=client,
    auto_initialize=False
)

# Initialize manually when ready
await agent.initialize()

Error Handling

Configure how the agent handles errors:

# Set timeout for agent operations
agent = MCPAgent(
    llm=llm,
    client=client,
    timeout=60  # 60 seconds timeout
)

# Configure retry behavior (if supported by LLM)
llm = ChatOpenAI(
    model="gpt-5.5",
    max_retries=3,
    retry_delay=2
)

agent = MCPAgent(llm=llm, client=client)

Automatic Error Retry

The agent includes automatic error handling that catches tool failures and allows the LLM to retry with corrected input. This is controlled by the retry_on_error parameter (default: True).

# Default: Error handling enabled
agent = MCPAgent(
    llm=llm,
    client=client,
    retry_on_error=True  # Default
)

# Disable automatic error handling (errors will halt execution)
agent = MCPAgent(
    llm=llm,
    client=client,
    retry_on_error=False
)

How it works: When retry_on_error=True, the agent uses middleware to intercept tool errors:

Catches all tool errors including validation errors, connection errors, and execution errors
Formats the error into a clear, actionable message
Returns error to LLM as a tool result (not an exception)
LLM reads the error and can retry with corrected input
Execution continues based on the LLM’s decision

Example Flow:

# First attempt - missing required field
# Tool call: create_board_column(board_id="123", body={"name": "Assignee"})
# Error returned: "Tool input validation failed. Please fix the following errors and retry:
#   - body.metaData: Field required (type: missing)"

# Second attempt - LLM automatically retries with correction
# Tool call: create_board_column(board_id="123", body={"name": "Assignee", "metaData": {}})
# Success: Column created

The automatic retry mechanism works for all error types and is handled by the middleware, ensuring errors are caught at the right level - including Pydantic validation errors that occur before tool execution.

Error Message Formatting: Different error types receive different formatting:

Validation Errors: Field-by-field breakdown showing exactly what’s wrong

Tool input validation failed. Please fix the following errors and retry:
  - body.metaData: Field required (type: missing)
  - timeout: Input should be a valid integer (type: int_type)

Other Errors: Error type and description

ConnectionError: Failed to connect to MCP server

When to disable retry_on_error: Set retry_on_error=False when:

Debugging tool issues and you want immediate failure
You want strict validation without retry attempts
Running in environments where retries could cause issues

Best Practices

LLM Selection: Use models with tool calling capabilities
Step Limits: Set reasonable max_steps to prevent runaway execution
Tool Restrictions: Use disallowed_tools for security
Memory Management: Disable memory for stateless use cases
Server Manager: Enable for multi-server setups
System Prompts: Customize for domain-specific tasks
Error Handling: Implement proper timeout and retry logic
Testing: Test agent configurations in development environments

Common Issues

No Tools Available: Check client configuration and server connections
Tool Execution Failures: Enable verbose logging and check tool arguments
Memory Issues: Disable memory or limit concurrent servers
Timeout Errors: Increase max_steps or agent timeout values

For detailed troubleshooting, see the Security guide.

Get Started

MCP Server

MCP Client

MCP Agents

Development

Agent Configuration

API Keys

Agent Parameters

Available Parameters

Sending Files with HumanMessage

Tool Access Control

Working with Adapters Directly

Server Manager

Enabling Server Manager

How It Works

Benefits

When to Use

Memory Configuration

System Prompt Customization

Custom System Prompt

Additional Instructions

System Prompt Templates

Performance Configuration

Debugging Configuration

Agent Initialization

Error Handling

Automatic Error Retry

Best Practices

Common Issues

​API Keys

​Agent Parameters

​Available Parameters

​Sending Files with HumanMessage

​Tool Access Control

​Working with Adapters Directly

​Server Manager

​Enabling Server Manager

​How It Works

​Benefits

​When to Use

​Memory Configuration

​System Prompt Customization

​Custom System Prompt

​Additional Instructions

​System Prompt Templates

​Performance Configuration

​Debugging Configuration

​Agent Initialization

​Error Handling

​Automatic Error Retry

​Best Practices

​Common Issues

API Keys

Agent Parameters

Available Parameters

Sending Files with HumanMessage

Tool Access Control

Working with Adapters Directly

Server Manager

Enabling Server Manager

How It Works

Benefits

When to Use

Memory Configuration

System Prompt Customization

Custom System Prompt

Additional Instructions

System Prompt Templates

Performance Configuration

Debugging Configuration

Agent Initialization

Error Handling

Automatic Error Retry

Best Practices

Common Issues