Overview

Title

mcp-agent: A Simple, Composable Framework for Building Agents with Model Context Protocol (MCP)

How to Use

1. Installation:

   • Use uv or pip to install:

     uv add "mcp-agent"  
     # OR  
     pip install mcp-agent  

   • Clone the repository and explore the examples directory for sample applications.

2. Quickstart:

   • Configure mcp_agent.config.yaml and mcp_agent.secrets.yaml.
   • Run a basic agent that interacts with MCP servers (e.g., fetch URLs, read files).

3. Run an Example:

   cd examples/mcp_basic_agent  
   cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml  # Update API keys  
   uv run main.py  

Key Features

• MCP Integration: Manages MCP server connections seamlessly.
• Composable Patterns: Implements all agent patterns from Anthropic’s Building Effective Agents.
• Multi-Agent Orchestration: Supports OpenAI’s Swarm pattern in a model-agnostic way.
• Lightweight & Extensible: Simple framework focused on composability and ease of use.
• Production-Ready: Designed for robust, scalable agent applications.

Use Cases

1. Basic Agents: Fetch data, read files, and perform multi-turn interactions.
2. Multi-Agent Systems: Orchestrate agents for complex workflows (e.g., Swarm pattern).
3. AI Applications:
   • Claude Desktop: Interactive desktop assistants.
   • Streamlit Apps: Gmail agents, RAG chatbots.
   • Marimo Notebooks: Data analysis and automation.
   • CLI Tools: Multi-agent collaboration via command line.
4. Advanced Workflows:
   • Parallel task execution, intent classification, evaluator-optimizer loops.
   • Human-in-the-loop signaling for controlled agent behavior.

Example Applications

• Gmail Agent: Automate email processing.
• RAG Chatbot: Build a retrieval-augmented chatbot.
• Swarm CLI: Multi-agent coordination via command line.

For more details, explore the Core Concepts and Workflow Patterns.

---

Get Started Today: Build, compose, and deploy AI agents effortlessly with mcp-agent! 🚀