mcp-agent
A Python framework for building MCP-connected agents with composable workflow patterns.
- Source repo
- lastmile-ai/mcp-agent
- Stars
- ★ 8.6k
- Last updated
- 9mo ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 53/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformClaude.ai · OpenAI API · Claude APIChatGPT (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A Python backend team needs a research assistant that reads approved local files through filesystem, fetches web content through fetch, and returns a concise summary.
- Not a fit if
- Teams unwilling to work in Python with uv and YAML configuration
- Teams wanting durable execution without operating an extra Temporal worker
- Source review
- 53/100 · Major gaps
What does this agent do, and when should you use it?
mcp-agent is a Python framework for building agents and workflows around the Model Context Protocol (MCP). Its MCPApp runtime loads configuration, initializes logging and the execution engine, and manages MCP server connection lifecycles. Agents pair instructions with named MCP servers, while Augmented LLMs add tools, memory, and structured-output helpers to provider SDK calls. The repository includes composable patterns for parallel work, routing, orchestrator-worker systems, evaluator-optimizer loops, and Swarm handoffs, with asyncio and Temporal execution options. Applications can run as standalone Python programs or be exposed as standard MCP servers with create_mcp_server_for_app; the README also documents a Cloud deployment path.
A developer creates an MCPApp, declares MCP servers such as fetch and filesystem in mcp_agent.config.yaml, and defines an Agent with server_names. Inside async with app.run() and async with agent, the framework initializes server connections; agent.attach_llm(OpenAIAugmentedLLM) provides generate, generate_str, and generate_structured so the model can call tools from those servers. Factory helpers including create_parallel_llm, create_router_llm, create_orchestrator, and create_evaluator_optimizer_llm assemble higher-level workflows. Setting execution_engine to temporal and running create_temporal_worker_for_app enables durable workflows, while create_mcp_server_for_app exposes @app.tool functions and workflows to MCP clients.
- A Python backend team needs a research assistant that reads approved local files through filesystem, fetches web content through fetch, and returns a concise summary.
- An application team needs to route incoming requests to the most suitable AgentSpec, MCP server, or function before automation begins.
- A developer needs to fan out specialist tasks in parallel and combine their outputs into a single report.
- An operations workflow needs to pause for a human approval or missing input, then resume through a Temporal-backed run.
- A team wants to expose existing Python tools and workflows as an MCP server for Claude Desktop, Cursor, or a custom MCP client.
How do you install or deploy this agent?
Install Python and uv, then create a project and run:
uvx mcp-agent init
uv init
uv add "mcp-agent[openai]"Alternatively:
pip install mcp-agentThe OpenAI example requires an API key in mcp_agent.secrets.yaml or the OPENAI_API_KEY environment variable. The README lists optional provider extras as "mcp-agent[openai, anthropic, google, azure, bedrock]".
How do you use this agent?
Create main.py using MCPApp, Agent, and OpenAIAugmentedLLM, and give the Agent server_names=["fetch", "filesystem"]. In mcp_agent.config.yaml, configure those servers: the example uses uvx mcp-server-fetch for fetch and npx -y @modelcontextprotocol/server-filesystem plus an allowed directory for filesystem. Then run:
uv run main.pyThe minimal call sequence is to create the Agent inside async with app.run(), attach the model with llm = await agent.attach_llm(OpenAIAugmentedLLM), then call await llm.generate_str("Summarize README.md in two sentences."). To scaffold a basic project, run uvx mcp-agent init --template basic --dir my-first-agent.
What are this agent's strengths and limitations?
- MCPApp and Agent handle MCP server connection lifecycles directly, avoiding application-level connection management.
- The same workflow annotations work with asyncio and Temporal; the Temporal path adds pause, resume, retries, and durable history.
- It ships named composition helpers for Map-Reduce, routing, intent classification, orchestrator-workers, evaluator-optimizer, and Swarm patterns.
- create_mcp_server_for_app can publish an MCPApp as a standard MCP server for MCP-capable clients.
- The documented workflow centers on asynchronous Python, uv, and YAML configuration; other languages or synchronous execution models require separate integration work.
- The minimal OpenAI example requires OPENAI_API_KEY or a secrets file; other providers require their optional package extras and configuration.
- Durable execution requires changing execution_engine to temporal and operating an additional Temporal worker.
- Cloud deployment is labeled Beta in the README, and the supplied material does not state its pricing, quotas, or managed-runtime details.
How does this agent compare with similar options?
Compared with using an MCP host such as Claude Desktop or Cursor alone, mcp-agent can also run as a standalone Python application and expose its own tools and workflows back to those MCP clients through create_mcp_server_for_app.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| mcp-agent This agent | 53 · Major gaps | FrameworkFree + model costs | ★ 8.6k | 9mo ago | Python | Claude.ai · OpenAI API · Claude API |
| LlamaAgents | 66 · Some gaps | Library / SDKFree + model costs | ★ 464 | today | Python | — |
| Agently AI Application Runtime | 63 · Some gaps | Library / SDKFree + model costs | ★ 1.7k | 24d ago | Python | OpenAI API · Claude API |
| Stripe AI | 50 · Major gaps | Library / SDKFree + model costs | ★ 2k | today | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: framework supports restricting tool access via server_names, provides human_input_callback mechanism, config separates secrets file, dependencies include security-related libraries (e.g., opentelemetry), SECURITY.md provides vulnerability reporting channel, but no automatic rollback mechanism found, publisher identity unverified. Deductions: lack of explicit documentation on least privilege, user confirmation only as optional callback, insufficient data flow transparency, limited sensitive data handling details, no vulnerability scanning evidence for dependencies, external effects not clearly stated, rollback mechanism missing, source attribution relies only on author info.
Evidence shows: codebase includes test files (e.g., test_agent.py) and CI workflow (checks.yml), dependency versions pinned, but failure message handling not fully demonstrated. Deductions: self-consistency supported by tests but not comprehensive, dependency availability has version pinning but not verified, failure messages only partially reflected.
Evidence shows: README provides multiple usage scenarios (e.g., MCP server, Temporal, Cloud), clearly lists supported patterns and features, flexible configuration, but boundaries not explicit. Deductions: audience and scenarios well described, capability boundaries explained but not detailed, trigger precision has examples but not systematic, environment fit has config examples but not comprehensive.
Evidence shows: README structure clear, installation instructions detailed, naming stable (e.g., mcp-agent), examples and FAQ provided, license Apache-2.0, version in pyproject.toml, SECURITY.md and contributing guide present. Deductions: known limitations not explicitly listed, version changelog not provided, maintenance responsibility has author info but not explicit.
Evidence shows: output format has examples (e.g., generate_str), multiple workflow patterns provided, cost-benefit described (e.g., production-ready). Deductions: output usability has examples but not comprehensive, marginal value described but not quantified, cost-benefit described but no specific data.
Evidence shows: claims in README have doc links, but no independent verification. Deductions: claim traceability limited, cross-source corroboration insufficient, fact-inference separation unclear.
- Publisher identity unverified; assess supply chain risk carefully.
- No automatic rollback mechanism found; implement your own for production.
- No vulnerability scanning evidence for dependencies; conduct security audit before use.
- Known limitations not explicitly listed; may affect deployment decisions.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Minor patch update to get mcp-agent compatible with latest MCP package v1.8.0 Changes - Upgrade MCP package dependency to v1.8.0 with corresponding hotfixes (8de63b4) - Add an OllamaAugmentedLLM and ensure it works well with complex workflows that require structured type generation ( - Fixing absolute path of server in basic/decorator/yaml @Deathn0t (#181) - Get rid of custom websocket and stdio clients in favor of default ones shipped in MCP package (9d92ef0)View on GitHub ↗ -
Release notes excerpt
Thank you to all the wonderful community contributions! We are gearing up for a significant update to mcp-agent shortly. You can follow the progress in feature/temporal_prime and feature/app_server branches. v0.0.18 has a few bug fixes, and the ability to specify a custom http client for OpenAI AugmentedLLM (thanks @blevz!) Changes - Add ability to configure the http_client for openai @blevz (#173) 🐛 Bug Fixes - fix: add system prompt handling to AzureAugmentedLLM @StreetLamb (#148) - fx: _reasoning flag used to set api params @Pythonista7 (#139) …View on GitHub ↗ -
Release notes excerpt
Minor release adding proper support for MCP servers using SSE and Websockets, with configurable headers, as well as OpenAI o4 model support. Huge thanks to @pmohan6 especially for adding WS support (with tests), as well as @aloktiagi for quickly adding o4 day-of-launch Changes - feature: support websocket connections and passing in HTTP headers to websockets and SSE connections @pmohan6 (#116) - add support for o4 reasoning models @aloktiagi (#142)View on GitHub ↗