Quick Start with MCP-Use 🚀

Welcome to the MCP-Use universe – the easiest way to plug any LLM into powerful, real-world tools! In this short guide you'll go from zero to a running agent in under five minutes.

This tutorial is the perfect place to start if you've just installed MCP-Use or if you want a refresher on the basics. When you're done, jump to the other tutorials in this folder for deeper dives.

0. Why MCP before MCP-Use?

Before diving into code let's understand the playing field.

MCP (Model-Context Protocol) is an open standard that lets an AI model call external tools in a safe, typed way – similar to how your smartphone apps request permissions. A tool can be anything:

• open a web page and click a button
• run a shell command
• query a SQL database
• generate a Blender mesh

MCP defines a common language so the model (host) says "I want to call browser.search with query=best ramen berlin" and an MCP server executes it, returning JSON results.

👉 In short: MCP turns any black-box LLM into a programmable agent that can actually get stuff done.

Real-world Stories

1. Enter MCP-Use 🛠️

MCP-Use is the Python glue that makes all of the above dead-simple:

• Spin up or connect to many MCP servers ✔️
• Wrap them in an ergonomic async client ✔️
• Feed tool schemas to your favourite LangChain LLM ✔️
• Provide guard-rails like max_steps, allowed tools, automatic server routing ✔️

If MCP is the protocol, MCP-Use is the power socket adapter.

1. Prerequisites

2. Installation

# 1. Core library
pip install mcp-use

# 2. Pick an LLM provider – here we use OpenAI
pip install langchain-openai

# 3. (Optional) Playwright browser MCP server
npm install -g @playwright/mcp   # or just use npx in the config later

Add your API keys to a .env file in your project root:

OPENAI_API_KEY="sk-…"

MCP-Use will automatically pick them up via python-dotenv.

3. Your First Agent – "Find me coffee ☕"

Create a new file called hello_mcp.py and paste the following code:

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

load_dotenv()  # 🔑 Load API keys

# 1️⃣ Describe which MCP servers you want.  Here we spin up Playwright in a headless browser.
CONFIG = {
    "mcpServers": {
        "playwright": {
            "command": "npx",
            "args": ["@playwright/mcp@latest"],
            "env": {"DISPLAY": ":1"}  # required if you run inside Xvfb / CI
        }
    }
}

async def main():
    client = MCPClient.from_dict(CONFIG)
    llm = ChatOpenAI(model="gpt-4o")

    # 2️⃣ Wire the LLM to the client
    agent = MCPAgent(llm=llm, client=client, max_steps=20)

    # 3️⃣ Ask something that requires real web browsing
    result = await agent.run("Find the best specialty coffee in Berlin using Google Search")
    print("\n🔥 Result:", result)

    # 4️⃣ Always clean up running MCP sessions
    await client.close_all_sessions()

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

Run it:

python hello_mcp.py

If everything is set up correctly you'll watch MCP-Use boot the Playwright server, let the LLM pick browser actions, and finally print a human-readable answer.

4. How it Works (TL;DR)

1. MCPClient starts the external server in a separate process.
2. The server exposes tools (e.g. browser.search, browser.click).
3. MCPAgent sends the available tools to your LLM.
4. The LLM decides which tool to call, returns a JSON tool invocation, and MCP-Use executes it.
5. Steps 3-4 repeat until the agent decides it's "done" or hits max_steps.

5. Next Steps ▶️

• Build your own agent – check out first-agent.md for a fully-commented walkthrough.
• Multiple servers – want to combine Airbnb + Browser + Filesystem? Hop over to multi-server.md.
• Debugging – learn pro tips for logging and tracing in debugging.md.

Happy hacking – and don't forget to ⭐ the project on GitHub if this saved you time!
(GitHub Repo)