mcp-agent

<p align="center"> <a href="https://docs.mcp-agent.com"><img src="https://github.com/user-attachments/assets/c8d059e5-bd56-4ea2-a72d-807fb4897bde" alt="Logo" width="300" /></a> </p> <p align="center"> <em>Build effective agents with Model Context Protocol using simple, composable patterns.</em> <p align="center"> <a href="https://github.com/lastmile-ai/mcp-agent/tree/main/examples" target="_blank"><strong>Examples</strong></a> | <a href="https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/overview" target="_blank"><strong>Building Effective Agents</strong></a> | <a href="https://modelcontextprotocol.io/introduction" target="_blank"><strong>MCP</strong></a> </p> <p align="center"> <a href="https://docs.mcp-agent.com"><img src="https://img.shields.io/badge/docs-8F?style=flat&link=https%3A%2F%2Fdocs.mcp-agent.com%2F" /><a/> <a href="https://pypi.org/project/mcp-agent/"><img src="https://img.shields.io/pypi/v/mcp-agent?color=%2334D058&label=pypi" /></a> <img alt="Pepy Total Downloads" src="https://img.shields.io/pepy/dt/mcp-agent?label=pypi%20%7C%20downloads"/> <a href="https://github.com/lastmile-ai/mcp-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg"/></a> <a href="https://lmai.link/discord/mcp-agent"><img src="https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white" alt="discord"/></a> </p> <p align="center"> <a href="https://trendshift.io/repositories/13216" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13216" alt="lastmile-ai%2Fmcp-agent | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a> </p>

Overview

mcp-agent is a simple, composable framework to build effective agents using Model Context Protocol.

[!Note] mcp-agent's vision is that MCP is all you need to build agents, and that simple patterns are more robust than complex architectures for shipping high-quality agents.

mcp-agent gives you the following:

1. Full MCP support: It fully implements MCP, and handles the pesky business of managing the lifecycle of MCP server connections so you don't have to.
2. Effective agent patterns: It implements every pattern described in Anthropic's Building Effective Agents in a composable way, allowing you to chain these patterns together.
3. Durable agents: It works for simple agents and scales to sophisticated workflows built on Temporal so you can pause, resume, and recover without any API changes to your agent.

<u>Altogether, this is the simplest and easiest way to build robust agent applications</u>.

We welcome all kinds of contributions, feedback and your help in improving this project.

<a id="minimal-example"></a> Minimal example

import asyncio

from mcp_agent.app import MCPApp
from mcp_agent.agents.agent import Agent
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

app = MCPApp(name="hello_world")

async def main():
    async with app.run():
        agent = Agent(
            name="finder",
            instruction="Use filesystem and fetch to answer questions.",
            server_names=["filesystem", "fetch"],
        )
        async with agent:
            llm = await agent.attach_llm(OpenAIAugmentedLLM)
            answer = await llm.generate_str("Summarize README.md in two sentences.")
            print(answer)


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

# Add your LLM API key to `mcp_agent.secrets.yaml` or set it in env.
# The [Getting Started guide](https://docs.mcp-agent.com/get-started/overview) walks through configuration and secrets in detail.

At a glance

<table> <tr> <td width="50%" valign="top"> <h3>Build an Agent</h3> <p>Connect LLMs to MCP servers in simple, composable patterns like map-reduce, orchestrator, evaluator-optimizer, router & more.</p> <p> <a href="https://docs.mcp-agent.com/get-started/overview">Quick Start ↗</a> | <a href="https://docs.mcp-agent.com/mcp-agent-sdk/overview">Docs ↗</a> </p> </td> <td width="50%" valign="top"> <h3>Create any kind of MCP Server</h3> <p>Create MCP servers with a FastMCP-compatible API. You can even expose agents as MCP servers.</p> <p> <a href="https://docs.mcp-agent.com/mcp-agent-sdk/mcp/agent-as-mcp-server">MCP Agent Server ↗</a> | <a href="https://docs.mcp-agent.com/cloud/use-cases/deploy-chatgpt-apps">🎨 Build a ChatGPT App ↗</a> | <a href="https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp_agent_server">Examples ↗</a> </p> </td> </tr> <tr> <td width="50%" valign="top"> <h3>Full MCP Support</h3> <p><b>Core:</b> Tools ✅ Resources ✅ Prompts ✅ Notifications ✅<br/> <b>Advanced</b>: OAuth ✅ Sampling ✅ Elicitation ✅ Roots ✅</p> <p> <a href="https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp">Examples ↗</a> | <a href="https://modelcontextprotocol.io/docs/getting-started/intro">MCP Docs ↗</a> </p> </td> <td width="50%" valign="top"> <h3>Durable Execution (Temporal)</h3> <p>Scales to production workloads using Temporal as the agent runtime backend <i>without any API changes</i>.</p> <p> <a href="https://docs.mcp-agent.com/mcp-agent-sdk/advanced/durable-agents">Docs ↗</a> | <a href="https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal">Examples ↗</a> </p> </td> </tr> <tr> <td width="50%" valign="top"> <h3>☁️ Deploy to Cloud</h3> <p><b>Beta:</b> Deploy agents yourself, or use <b>mcp-c</b> for a managed agent runtime. All apps are deployed as MCP servers.</p> <p> <a href="https://www.youtube.com/watch?v=0C4VY-3IVNU">Demo ↗</a> | <a href="https://docs.mcp-agent.com/get-started/cloud">Cloud Quickstart ↗</a> | <a href="https://github.com/lastmile-ai/mcp-agent/tree/main/examples/cloud">Examples ↗</a> </p> </td> </tr> </table>

Documentation & build with LLMs

mcp-agent's complete documentation is available at docs.mcp-agent.com, including full SDK guides, CLI reference, and advanced patterns. This readme gives a high-level overview to get you started.

• llms-full.txt: contains entire documentation.
• llms.txt: sitemap listing key pages in the docs.
• docs MCP server

Table of Contents

• Overview
• Minimal example
• Quickstart
• Why mcp-agent
• Core concepts
  • MCPApp
  • Agents & AgentSpec
  • Augmented LLM
  • Workflows & decorators
  • Configuration & secrets
  • MCP integration
• Workflow patterns
• CLI reference
• Authentication
• Advanced
  • Observability & controls
  • Composing workflows
  • Durable execution
  • Agent servers
  • Signals & human input
  • App configuration
  • Icons
  • MCP server management
• Cloud deployment
• Examples
• FAQs
• Community & contributions

Get Started

[!TIP] The CLI is available via uvx mcp-agent. To get up and running, scaffold a project with uvx mcp-agent init and deploy with uvx mcp-agent deploy my-agent.

You can get up and running in 2 minutes by running these commands:

mkdir hello-mcp-agent && cd hello-mcp-agent
uvx mcp-agent init
uv init
uv add "mcp-agent[openai]"
# Add openai API key to `mcp_agent.secrets.yaml` or set `OPENAI_API_KEY`
uv run main.py

Installation

We recommend using uv to manage your Python projects (uv init).

uv add "mcp-agent"

Alternatively:

pip install mcp-agent

Also add optional packages for LLM providers (e.g. uv add "mcp-agent[openai, anthropic, google, azure, bedrock]").

Quickstart

[!TIP] The examples directory has several example applications to get started with. To run an example, clone this repo (or generate one with uvx mcp-agent init --template basic --dir my-first-agent)

cd examples/basic/mcp_basic_agent # Or any other example
# Option A: secrets YAML
# cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml && edit mcp_agent.secrets.yaml
uv run main.py

Here is a basic "finder" agent that uses the fetch and filesystem servers to look up a file, read a blog and write a tweet. Example link:

<details open> <summary>finder_agent.py</summary>

import asyncio
import os

from mcp_agent.app import MCPApp
from mcp_agent.agents.agent import Agent
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

app = MCPApp(name="hello_world_agent")

async def example_usage():
    async with app.run() as mcp_agent_app:
        logger = mcp_agent_app.logger
        # This agent can read the filesystem or fetch URLs
        finder_agent = Agent(
            name="finder",
            instruction="""You can read local files or fetch URLs.
                Return the requested information when asked.""",
            server_names=["fetch", "filesystem"], # MCP servers this Agent can use
        )

        async with finder_agent:
            # Automatically initializes the MCP servers and adds their tools for LLM use
            tools = await finder_agent.list_tools()
            logger.info(f"Tools available:", data=tools)

            # Attach an OpenAI LLM to the agent (defaults to GPT-4o)
            llm = await finder_agent.attach_llm(OpenAIAugmentedLLM)

            # This will perform a file lookup and read using the filesystem server
            result = await llm.generate_str(
                message="Show me what's in README.md verbatim"
            )
            logger.info(f"README.md contents: {result}")

            # Uses the fetch server to fetch the content from URL
            result = await llm.generate_str(
                message="Print the first two paragraphs from https://www.anthropic.com/research/building-effective-agents"
            )
            logger.info(f"Blog intro: {result}")

            # Multi-turn interactions by default
            result = await llm.generate_str("Summarize that in a 128-char tweet")
            logger.info(f"Tweet: {result}")

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

</details> <details> <summary>mcp_agent.config.yaml</summary>

execution_engine: asyncio
logger:
  transports: [console] # You can use [file, console] for both
  level: debug
  path: "logs/mcp-agent.jsonl" # Used for file transport
  # For dynamic log filenames:
  # path_settings:
  #   path_pattern: "logs/mcp-agent-{unique_id}.jsonl"
  #   unique_id: "timestamp"  # Or "session_id"
  #   timestamp_format: "%Y%m%d_%H%M%S"

mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
    filesystem:
      command: "npx"
      args:
        [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "<add_your_directories>",
        ]

openai:
  # Secrets (API keys, etc.) are stored in an mcp_agent.secrets.yaml file which can be gitignored
  default_model: gpt-4o

</details> <details> <summary>Agent output</summary> <img width="2398" alt="Image" src="h