​
Quickstart Guide

This guide will help you get started with mcp_use quickly. We’ll cover installation, basic configuration, and running your first agent.

​
Installation

You can install mcp_use using pip:

pip install mcp-use

Or install from source:

git clone https://github.com/pietrozullo/mcp-use.git
cd mcp-use
pip install -e .

​
Installing LangChain Providers

mcp_use works with various LLM providers through LangChain. You’ll need to install the appropriate LangChain provider package for your chosen LLM. For example:

# For OpenAI
pip install langchain-openai

# For Anthropic
pip install langchain-anthropic

# For other providers, check the [LangChain chat models documentation](https://python.langchain.com/docs/integrations/chat/)

Important: Only models with tool calling capabilities can be used with mcp_use. Make sure your chosen model supports function calling or tool use.

​
Environment Setup

Set up your environment variables in a .env file:

OPENAI_API_KEY=your_api_key_here
ANTHROPIC_API_KEY=your_api_key_here

​
Your First Agent

Here’s a simple example to get you started:

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.from_dict(config)

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

    # Create agent with the client
    agent = MCPAgent(llm=llm, client=client, max_steps=30)

    # 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())

​
Configuration Options

You can also add the servers configuration from a config file:

client = MCPClient.from_config_file(
    os.path.join("browser_mcp.json")
)

Example configuration file (browser_mcp.json):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "DISPLAY": ":1"
      }
    }
  }
}

​
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_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder

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
    llm = ChatOpenAI(model="gpt-4o")
    prompt = ChatPromptTemplate.from_messages([
        ("system", "You are a helpful assistant with access to powerful tools."),
        MessagesPlaceholder(variable_name="chat_history"),
        ("human", "{input}"),
        MessagesPlaceholder(variable_name="agent_scratchpad"),
    ])

    agent = create_tool_calling_agent(llm=llm, tools=tools, prompt=prompt)
    agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

    result = await agent_executor.ainvoke({"input": "Search for information about climate change"})
    print(result["output"])

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

The adapter pattern makes it easy to:

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

​
Using 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).

Configuration:

Define multiple servers in your configuration file (multi_server_config.json):

{
  "mcpServers": {
    "airbnb": {
      "command": "npx",
      "args": ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"]
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "DISPLAY": ":1"
      }
    }
  }
}

Usage:

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.

# Assuming MCPClient is initialized with the multi_server_config.json
client = MCPClient.from_config_file("multi_server_config.json")
agent = MCPAgent(llm=llm, client=client) # Server manager not enabled by default

# Manually specify the server if needed
result = await agent.run(
    "Search for Airbnb listings in Barcelona",
    server_name="airbnb"
)

​
Enabling Dynamic Server Selection (Server Manager)

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

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.

# Assuming MCPClient is initialized with the multi_server_config.json
client = MCPClient.from_config_file("multi_server_config.json")
agent = MCPAgent(llm=llm, client=client, use_server_manager=True) # Enable server manager

# The agent can now use tools from both airbnb and playwright servers
result = await agent.run(
    "Search for a place in Barcelona on Airbnb, then Google nearby restaurants."
)

​
Restricting Tool Access

You can control which tools are available to the agent:

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.from_dict(config)

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

    # 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())

​
Available MCP Servers

mcp_use supports any MCP server, allowing you to connect to a wide range of server implementations. For a comprehensive list of available servers, check out the awesome-mcp-servers repository.

Each server requires its own configuration. Check the Configuration Guide for details.

​
HTTP Connection

mcp_use now supports HTTP connections, allowing you to connect to MCP servers running on specific HTTP ports. This feature is particularly useful for integrating with web-based MCP servers.

Here’s a simple example to get you started with HTTP connections:

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": {
        "http": {
          "url": "http://localhost:8931/sse"
        }
      }
    }

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

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

    # Create agent with the client
    agent = MCPAgent(llm=llm, client=client, max_steps=30)

    # 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())

This example demonstrates how to connect to an MCP server running on a specific HTTP port. Make sure to start your MCP server before running this example.

​
Streaming Agent Output

You can stream the agent’s output as it is generated using the astream method:

async for chunk in agent.astream("Find the best restaurant in San Francisco"):
    print(chunk["messages"], end="", flush=True)

Each chunk contains incremental results, tool actions, and intermediate steps.

​
Next Steps