MCP-Agent

Overview

MCP-Agent is a Python framework from lastmile-ai that builds production-grade AI agents natively on top of the Model Context Protocol (MCP).

The author — Saqadri, a former LSP engineer at Microsoft — created MCP-Agent after watching AI agent development drift into the same fragmentation LSP solved a decade earlier. Every framework has its own tool interface, every model provider has its own message format, every platform has its own streaming semantics. MCP-Agent's thesis: the LLM is now a commodity; the bottleneck is orchestration. Instead of another framework, MCP-Agent treats MCP servers as the primitive and gives developers composable patterns on top of them.

The project gained 80+ Hacker News upvotes on Show HN, spawned a Deep Research Agent tutorial (91 points), and has become the reference implementation for "Anthropic's Building Effective Agents" patterns when working with MCP.

Features

• MCP-native primitives: AugmentedLLM is an LLM wrapped with access to one or more MCP servers, with connection management handled for you
• Composable agent patterns: Every pattern from Anthropic's Building Effective Agents blog is implemented as a first-class composable block
• OpenAI Swarm support: Port of OpenAI's Swarm primitive with multi-agent handoff via MCP tools
• YAML-driven server registry: Servers declared in mcp_agent.config.yaml, resolved at runtime by mcp_server_registry.py
• Cross-transport MCP: Stdio, SSE, and streamable HTTP transports from the same API
• Streaming-first: All agent methods stream tokens as they arrive; no buffered responses by default
• Zero vendor lock-in: Works with OpenAI, Anthropic, Google Gemini, Groq, Mistral, Ollama, and DeepSeek out of the box

Installation

# Python 3.11+
pip install mcp-agent

# Or with uv
uv add mcp-agent

# With the Claude LLM provider
pip install "mcp-agent[claude]"

# With the OpenAI LLM provider
pip install "mcp-agent[openai]"

Configuration

Create an mcp_agent.config.yaml:

llm_provider:
  provider: openai
  model: gpt-4o
  max_retries: 3

tools:
  fetch:
    use: mcp_tools.FetchTool
  filesystem:
    use: mcp_tools.FilesystemTool
    config:
      base_directory: /tmp
  github:
    use: mcp_tools.GitHubTool
    config:
      github_personal_access_token: ${GITHUB_TOKEN}

Quick Start

from mcp_agent import AugmentedLLM

# An LLM with access to any number of MCP servers
agent = AugmentedLLM(
    model="gpt-4o",
    server_names=["fetch", "filesystem", "github"]
)

response = agent.run("Summarize the README of lastmile-ai/mcp-agent on GitHub.")
print(response)

Agent Patterns

MCP-Agent ships every pattern from Anthropic's Building Effective Agents:

Pattern	Class	Use case
Augmented LLM	AugmentedLLM	Single LLM with tool access
Prompt Chaining	AugmentedLLM.pipe(AugmentedLLM)	Sequential transformations
Routing	RouterAgent	Delegate to specialist agents
Parallelization	ParallelAgent	Run agents concurrently
Orchestrator-Workers	OrchestratorAgent	Dynamic task delegation
Evaluator-Optimizer	EvaluatorOptimizerAgent	Iterative refinement
Swarm	Swarm	Handoff-based multi-agent

Deep Research Example

from mcp_agent import AugmentedLLM, RouterAgent

researcher = AugmentedLLM(
    model="gpt-4o",
    system_prompt="You are a research specialist. Use the fetch and arxiv tools.",
    server_names=["fetch", "arxiv"]
)

reporter = AugmentedLLM(
    model="gpt-4o",
    system_prompt="You write research reports with citations.",
    server_names=["filesystem"]
)

router = RouterAgent(
    llm=AugmentedLLM(model="gpt-4o"),
    tools=[researcher, reporter]
)

report = router.run("Write a 500-word report on MCP adoption in 2026.")

MCP Server Management

MCP-Agent manages server lifecycle for you:

from mcp_agent import initialize_all_servers, cleanup_all_servers

# Explicit lifecycle (useful in tests and long-running services)
initialize_all_servers()
# ... use agents ...
cleanup_all_servers()

Or use it as an async context manager:

from mcp_agent.config import initialize_all_servers, cleanup_all_servers

async with async_context():
    # all MCP servers loaded
    response = await agent.run(query)
# all servers torn down

Advanced: Custom MCP Server as an Agent Tool

Wrap an existing MCP server as a callable tool inside an agent:

from mcp_agent import AugmentedLLM
from mcp_agent.config import initialize_all_servers

initialize_all_servers()

agent = AugmentedLLM(
    model="gpt-4o",
    tools={
        "search_github": github_server,   # direct tool reference
        "browse_web": fetch_server,
    },
    server_names=["filesystem"]            # for tool discovery
)

Pros

• ✅ True MCP-native: not a framework that happens to have MCP support — MCP is the abstraction
• ✅ Every Anthropic pattern implemented: AugmentedLLM, Router, Orchestrator-Workers, Evaluator-Optimizer, Swarm, all first-class
• ✅ Composability: every pattern is itself an AugmentedLLM, so they chain naturally
• ✅ Multi-transport: stdio, SSE, and streamable HTTP from the same interface
• ✅ Multi-provider LLM support: OpenAI, Anthropic, Gemini, Groq, Ollama, DeepSeek, Mistral
• ✅ YAML configuration: server registry is declarative, easy to share
• ✅ Streaming-first: all APIs stream by default
• ✅ LSP author pedigree: Saqadri worked on Microsoft LSP, applies the same "protocol first" philosophy

Cons

• ❌ Python-only: TypeScript port requested on HN but not yet shipped
• ❌ Async-heavy: async/await everywhere can be painful for sync callers
• ❌ Server names as strings: server references are opaque strings resolved at runtime — IDE autocomplete doesn't work
• ❌ Young ecosystem: ~1K GitHub stars, smaller community than LangGraph or CrewAI
• ❌ No built-in persistence: durable state, checkpoints, and resume semantics are left to the user
• ❌ No built-in evaluation: no Evaluator-backed scoring loops out of the box

When to Use

Use MCP-Agent when:

• You're building on top of MCP servers and want a framework that treats them as the primitive, not an afterthought
• You need Anthropic's Building Effective Agents patterns with a real implementation, not pseudocode
• You want multi-provider LLM support with a single agent API
• You're prototyping in Python and need fast iteration with declarative server config
• You're building Deep Research / Orchestrator / Swarm agents that coordinate multiple MCP tools

Prefer alternatives when:

• You need TypeScript — use VoltAgent or the LangGraph JS SDK
• You need durable execution with checkpoints — use LangGraph
• You need role-based crews — use CrewAI
• You want vendor-managed deployment — use RunAgent or Automcp

Resources

• GitHub Repository
• Documentation
• Building Effective Agents (Anthropic)
• Show HN discussion (80 points)
• Deep Research tutorial (91 points)