This guide covers the most common issues users encounter when working with mcp_use and their solutions.

​
Installation Issues

​
ImportError: No module named ‘mcp_use’

Problem: Cannot import mcp_use after installation.

Solutions:

  1. Verify installation in correct environment:

    pip list | grep mcp-use

  2. Check Python path:

    import sys
print(sys.path)

  3. Reinstall in correct environment:

    pip uninstall mcp-use
pip install mcp-use

​
LangChain Provider Not Found

Problem: Error importing LangChain providers like langchain_openai.

Solution: Install the specific LangChain provider:

pip install langchain-openai  # for OpenAI
pip install langchain-anthropic  # for Anthropic
pip install langchain-groq  # for Groq

​
Configuration Issues

​
API Key Not Found

Problem: APIKeyNotFoundError or similar authentication errors.

Solutions:

  1. Check environment variables:

    echo $OPENAI_API_KEY

  2. Verify .env file location and contents:

    cat .env

  3. Ensure load_dotenv() is called:

    from dotenv import load_dotenv
load_dotenv()  # Add this before using API keys

​
Invalid Configuration File

Problem: JSON parsing errors when loading configuration.

Solutions:

  1. Validate JSON syntax:

    import json
with open('config.json', 'r') as f:
    config = json.load(f)  # Will show syntax errors

  2. Check file encoding (should be UTF-8):

    file -i config.json

  3. Verify all required fields are present:

    {
  "mcpServers": {
    "server_name": {
      "command": "command_here",
      "args": ["arg1", "arg2"]
    }
  }
}

​
MCP Server Issues

​
Server Not Found

Problem: FileNotFoundError when trying to start MCP server.

Solutions:

  1. Check if server is installed:

    which npx  # for Node.js servers
which python  # for Python servers

  2. Test server manually:

    npx @playwright/mcp@latest --version

  3. Use full path in configuration:

    {
  "mcpServers": {
    "playwright": {
      "command": "/usr/local/bin/npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

​
Server Connection Timeout

Problem: Server takes too long to start or respond.

Solutions:

  1. Increase timeout in agent configuration:

    agent = MCPAgent(
    llm=llm,
    client=client,
    timeout=60  # Increase from default 30 seconds
)

  2. Check server logs for issues:

    import logging
logging.basicConfig(level=logging.DEBUG)

  3. Test server independently:

    timeout 30 npx @playwright/mcp@latest

​
Permission Denied

Problem: Server cannot access files or directories.

Solutions:

  1. Check file permissions:

    ls -la /path/to/directory

  2. Update server configuration with accessible paths:

    {
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["/home/user/workspace"]  # Use accessible directory
    }
  }
}

  3. Run with appropriate user permissions:

    sudo chown -R $USER:$USER /path/to/directory

​
Agent Runtime Issues

​
No Tools Available

Problem: Agent reports no tools are available.

Solutions:

  1. Verify server connection:

    client = MCPClient.from_config_file("config.json")
await client.create_all_sessions()
session = client.get_session("server_name")  # Replace with actual server name
tools = await session.list_tools()
print(f"Available tools: {len(tools)}")

  2. Check for server startup errors:

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

  3. Verify server compatibility:

    npx @playwright/mcp@latest --help

​
Tool Execution Failures

Problem: Tools fail during execution with unclear errors.

Solutions:

  1. Enable verbose logging:

    import logging
logging.basicConfig(level=logging.DEBUG)

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

  2. Test tools individually:

    from mcp_use.adapters import LangChainAdapter

adapter = LangChainAdapter()
tools = await adapter.create_tools(client)

# Test specific tool
result = await tools[0].ainvoke({"input": "test"})

  3. Check tool arguments:

    for tool in tools:
    print(f"Tool: {tool.name}")
    print(f"Description: {tool.description}")
    print(f"Args: {tool.args}")

​
Memory/Performance Issues

Problem: Agent uses too much memory or runs slowly.

Solutions:

  1. Enable server manager:

    agent = MCPAgent(
    llm=llm,
    client=client,
    use_server_manager=True  # Only connects servers when needed
)

  2. Limit concurrent servers:

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

  3. Restrict available tools:

    agent = MCPAgent(
    llm=llm,
    client=client,
    allowed_tools=["file_read", "file_write"],  # Limit tool set
    max_steps=10  # Limit execution steps
)

​
LLM-Specific Issues

​
Model Not Supporting Tools

Problem: LLM doesn’t support function calling.

Solution: Use a tool-calling capable model:

# ✅ Good - supports tool calling
llm = ChatOpenAI(model="gpt-4")
llm = ChatAnthropic(model="claude-3-sonnet-20240229")

# ❌ Bad - doesn't support tool calling
llm = OpenAI(model="gpt-3.5-turbo-instruct")  # Completion model

​
Rate Limiting

Problem: API rate limits being exceeded.

Solutions:

  1. Add delays between requests:

    agent = MCPAgent(
    llm=llm,
    client=client,
    delay_between_steps=1.0  # 1 second delay
)

  2. Use different model tier:

    llm = ChatOpenAI(
    model="gpt-3.5-turbo",  # Lower rate limits
    max_retries=3,
    retry_delay=2
)

​
Model Compatibility Issues

Problem: Some models don’t support tools or don’t work well with MCP servers.

Solution: Many models either don’t support tool calling or have poor compatibility with MCP servers. If you encounter a model that doesn’t behave well, please open a pull request with proof of the issue and add it to the list of incompatible models below.

Known Incompatible Models:

  • List will be updated as issues are reported

When reporting model compatibility issues, please include:

  • Model name and version
  • Specific error messages
  • Test case demonstrating the issue
  • Expected vs actual behavior

​
Environment-Specific Issues

​
Docker/Container Issues

Problem: MCP servers not working in containerized environments.

Solutions:

  1. Install Node.js in container:

    RUN apt-get update && apt-get install -y nodejs npm

  2. Mount necessary directories:

    docker run -v /host/workspace:/container/workspace myapp

  3. Set proper environment variables:

    docker run -e DISPLAY=:0 -e NODE_PATH=/usr/local/lib/node_modules myapp

​
Windows-Specific Issues

Problem: Path or command issues on Windows.

Solutions:

  1. Use Windows-style paths:

    {
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["C:\\Users\\YourName\\workspace"]
    }
  }
}

  2. Use cmd for Node.js commands:

    {
  "mcpServers": {
    "playwright": {
      "command": "cmd",
      "args": ["/c", "npx", "@playwright/mcp@latest"]
    }
  }
}

​
Getting Help

If you continue experiencing issues:

  1. Check logs: Enable debug logging and review error messages
  2. Search issues: Look through GitHub issues
  3. Create issue: Report bugs with:
    • Complete error messages
    • Configuration files (remove API keys)
    • Environment details (OS, Python version, etc.)
    • Steps to reproduce

Most issues are related to configuration, environment setup, or missing dependencies. Double-check these basics before diving into complex debugging.