mcp-agent — Build AI Agents with MCP Patterns

What it is

mcp-agent is a Python framework for building AI agents that leverage the Model Context Protocol (MCP). It implements composable workflow patterns including orchestrator, map-reduce, evaluator-optimizer, and router patterns. Each pattern is a reusable building block for constructing complex agent systems.

This framework targets developers building multi-step AI agents who want structured patterns rather than ad-hoc chains. If you need agents that fan out work, evaluate results, and iteratively improve, mcp-agent provides the scaffolding.

How it saves time or tokens

Instead of implementing agent orchestration patterns from scratch, mcp-agent provides tested, reusable implementations. The workflow provides pip install commands and shows how to compose patterns. You define what each step does; the framework handles execution order, result aggregation, and error handling.

How to use

1. Install mcp-agent:

# With uv (recommended)
uv add 'mcp-agent[anthropic]'

# With pip
pip install 'mcp-agent[anthropic]'

# Multiple providers
uv add 'mcp-agent[openai,anthropic,google]'

1. Define an agent with workflow patterns:

from mcp_agent import Agent, OrchestratorWorkflow

agent = Agent(
    name='research-agent',
    model='claude-sonnet-4-20250514',
    tools=['web-search', 'file-reader']
)

workflow = OrchestratorWorkflow(
    agents=[agent],
    objective='Research and summarize the topic'
)

result = await workflow.run('Latest developments in quantum computing')

1. Compose patterns for complex workflows:

from mcp_agent import MapReduceWorkflow, EvaluatorWorkflow

# Fan out research, then synthesize
research = MapReduceWorkflow(
    map_agent=researcher,
    reduce_agent=synthesizer,
    inputs=['topic1', 'topic2', 'topic3']
)

Example

from mcp_agent import Agent, RouterWorkflow

# Route tasks to specialized agents
coder = Agent(name='coder', model='claude-sonnet-4-20250514', tools=['filesystem'])
writer = Agent(name='writer', model='claude-sonnet-4-20250514', tools=['web-search'])

router = RouterWorkflow(
    agents=[coder, writer],
    routing_strategy='llm',  # LLM decides which agent handles each task
)

result = await router.run('Write a Python script that scrapes news headlines')

Related on TokRepo

• Multi-agent frameworks -- Compare multi-agent orchestration tools
• AI tools for agents -- Agent building frameworks and tools

Common pitfalls

• MCP server connections must be configured before running agents. Ensure your .mcp.json or environment variables point to running MCP servers.
• Map-reduce workflows multiply API costs by the number of map operations. Monitor token usage when fanning out to many parallel agents.
• The evaluator-optimizer pattern can loop indefinitely if the evaluation criteria are too strict. Set a max_iterations limit.