mcp-agent

Build effective agents with Model Context Protocol using simple, composable patterns.

Examples | Building Effective Agents | MCP

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.

Altogether, this is the simplest and easiest way to build robust agent applications.

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

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

  Build an Agent
  Connect LLMs to MCP servers in simple, composable patterns like map-reduce, orchestrator, evaluator-optimizer, router & more.
  
    Quick Start ↗ | 
    Docs ↗
  


  Create any kind of MCP Server
  Create MCP servers with a FastMCP-compatible API. You can even expose agents as MCP servers.
  
    MCP Agent Server ↗ | 
    🎨 Build a ChatGPT App ↗ | 
    Examples ↗
  




  Full MCP Support
  <b>Core:</b> Tools ✅ Resources ✅ Prompts ✅ Notifications ✅
  <b>Advanced</b>: OAuth ✅ Sampling ✅ Elicitation ✅ Roots ✅
  
    Examples ↗ | 
    MCP Docs ↗
  


  Durable Execution (Temporal)
  Scales to production workloads using Temporal as the agent runtime backend <i>without any API changes</i>.
  
    Docs ↗ | 
    Examples ↗
  




  ☁️ Deploy to Cloud
  <b>Beta:</b> Deploy agents yourself, or use <b>mcp-c</b> for a managed agent runtime. All apps are deployed as MCP servers.
  
    Demo ↗ |
    Cloud Quickstart ↗ | 
    Examples ↗
  

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