# mcp-agent

> Python framework for building AI agents on Model Context Protocol servers using composable workflow patterns.

mcp-agent is an open-source Python framework from the lastmile-ai organization for building agents that use Model Context Protocol (MCP) servers. It implements the patterns from Anthropic's Building Effective Agents as composable workflows and can run on asyncio or Temporal for durable execution. It is released under the Apache 2.0 license.

## What It Is

mcp-agent is an agent framework centered on a single `MCPApp` runtime that loads configuration, registers agents and MCP servers, and exposes tools and workflows. An `Agent` couples instructions with the names of MCP servers it may use, and an attached Augmented LLM (OpenAI, Anthropic, Google, Azure, Bedrock via optional extras) provides `generate`, `generate_str`, and `generate_structured`. The framework manages MCP server connection lifecycles, so developers write ordinary Python control flow instead of graphs.

## Workflow Patterns

The documented patterns include parallel (map-reduce), router, intent classifier, orchestrator-workers, deep research, evaluator-optimizer, and swarm. Each has a factory helper (for example `create_router_llm` or `create_orchestrator`) and patterns can be chained together. AgentSpec definitions can be loaded from YAML files and turned into agents or LLMs.

## Durable Execution and Servers

Switching `execution_engine` to `temporal` adds pause/resume, retries, human-input signals, and durable history without changing workflow code. An MCPApp can also be exposed as an MCP server so clients such as Claude Desktop or Cursor can call its tools and workflows. Full MCP support is listed, including tools, resources, prompts, notifications, OAuth, sampling, elicitation, and roots.

## Setup Path

Install with `uv add "mcp-agent"` or `pip install mcp-agent`, then scaffold a project with `uvx mcp-agent init`. Configuration lives in `mcp_agent.config.yaml` and secrets in `mcp_agent.secrets.yaml` or environment variables. The CLI can also deploy to mcp-agent Cloud, which the README labels beta, where apps run as MCP servers.

## Features
- Full MCP support (tools, resources, prompts, notifications, OAuth, sampling, elicitation, roots)
- Composable agent workflow patterns (parallel, router, orchestrator, evaluator-optimizer, swarm, deep research, intent classifier)
- Durable execution with Temporal
- Expose agents as MCP servers
- AgentSpec loading from YAML
- Structured output via Augmented LLMs
- OpenTelemetry tracing and token counting
- Human input and signals
- CLI for scaffolding and deployment
- Cloud deployment (beta)

## Integrations
Model Context Protocol, Temporal, OpenAI, Anthropic, Google, Azure, AWS Bedrock, Claude Desktop, Cursor, FastMCP, OpenTelemetry

## Platforms
WINDOWS, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v0.0.21

## Links
- Website: https://github.com/lastmile-ai/mcp-agent
- Documentation: https://docs.mcp-agent.com
- Repository: https://github.com/lastmile-ai/mcp-agent
- EveryDev.ai: https://www.everydev.ai/tools/mcp-agent