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

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:

```bash 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)

```bash 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:

finder_agent.py

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

mcp_agent.config.yaml

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

Agent output

Why use mcp-agent?

There are too many AI frameworks out there already. But mcp-agent is the only one that is purpose-built for a shared protocol - MCP.mcp-agent pairs Anthropic’s Building Effective Agents patterns with a batteries-included MCP runtime so you can focus on behaviour, not boilerplate. Teams pick it because it is:

• Composable – every pattern ships as a reusable workflow you can mix and match.
• MCP-native – any MCP server (filesystem, fetch, Slack, Jira, FastMCP apps) connects without custom adapters.
• Production ready – Temporal-backed durability, structured logging, token accounting, and Cloud deploys are first-class.
• Pythonic – a handful of decorators and context managers wire everything together.

Docs: Welcome to mcp-agent • Effective patterns overview.

Core Components

Every project revolves around a single MCPApp runtime that loads configuration, registers agents and MCP servers, and exposes tools/workflows. The Core Components guide walks through these building blocks.

MCPApp

Initialises configuration, logging, tracing, and the execution engine so everything shares one context.

from mcp_agent.app import MCPApp

app = MCPApp(name="finder_app")

async def main():
    async with app.run() as running_app:
        logger = running_app.logger
        logger.info("App ready", data={"servers": list(running_app.context.server_registry.registry)})

Docs: MCPApp • Example: examples/basic/mcp_basic_agent.

Agents & AgentSpec

Agents c