mcp-agent

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.