mcp-agent: Build Effective AI Agents with Model Context Protocol in Python

Summary

mcp-agent is a powerful Python framework designed to help developers build effective AI agents using the Model Context Protocol (MCP) and simple, composable workflow patterns. It fully implements MCP, providing robust support for agent lifecycle management and integrating patterns from Anthropic's 'Building Effective Agents'. This framework simplifies the creation of durable, production-ready agent applications.

Use at your own risk

OSRepos shares public repositories for knowledge and discovery only. Any installation, execution, configuration, or use of code from these repositories is the user's own responsibility. Always review the repository, source code, dependencies, licenses, and security implications before running or installing anything. OSRepos is not responsible for issues, damages, or losses resulting from third-party repositories.

Introduction

mcp-agent is a powerful and composable Python framework for building effective AI agents. It leverages the Model Context Protocol (MCP) to provide a streamlined approach, allowing developers to focus on agent behavior rather than boilerplate. This framework fully implements MCP, handling server connections and offering robust patterns for creating intelligent, durable agents that scale to production workloads.

Installation

To get started with mcp-agent, we recommend using uv for Python project management.

uv add "mcp-agent"

Alternatively, you can use pip:

pip install mcp-agent

Remember to add optional packages for specific LLM providers, for example:

uv add "mcp-agent[openai, anthropic, google, azure, bedrock]"

Examples

mcp-agent provides a simple and composable way to build agents. Here is a minimal example demonstrating how to create an agent that uses filesystem and fetch servers:

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

For a quick start, you can scaffold a new project using the CLI:

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

The project also includes a "finder" agent example that can read local files or fetch URLs, then summarize content into a tweet. More examples are available in the official documentation.

Why Use mcp-agent?

In a landscape of many AI frameworks, mcp-agent stands out as the only one purpose-built for the Model Context Protocol (MCP). It combines Anthropic’s "Building Effective Agents" patterns with a comprehensive MCP runtime, allowing you to concentrate on agent behavior. Key reasons to choose mcp-agent include:

Composable: Every pattern is a reusable workflow that can be mixed and matched.
MCP-native: Seamlessly connects to any MCP server, such as filesystem, fetch, Slack, Jira, or FastMCP apps, without custom adapters.
Production Ready: Features like Temporal-backed durability, structured logging, token accounting, and Cloud deployments are first-class.
Pythonic: Utilizes simple decorators and context managers for elegant integration.