mcp-agent

Overview

mcp-agent is a Python framework for building applications where MCP is the primary tool and context layer. It manages MCP server lifecycles, lets agents attach LLM providers, implements composable agent workflow patterns, and can scale from simple local agents to durable Temporal-backed workflows.

Use it when a project needs code-first agent orchestration around MCP servers rather than a single hard-coded tool call. It is especially relevant for teams that want explicit Python application code for routing, orchestration, evaluation, optimization, parallel work, human input, durable execution, and agent-as-MCP-server deployment.

Core Capabilities

Quick Start

Add the package to a Python project:

uv add "mcp-agent[openai]"

Or scaffold a starter project with the CLI:

uvx mcp-agent init

A minimal agent defines the app, chooses MCP servers, and attaches an LLM:

import asyncio

from mcp_agent.app import MCPApp
from mcp_agent.agents.agent import Agent
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

app = MCPApp(name="hello_world")

async def main():
    async with app.run():
        agent = Agent(
            name="finder",
            instruction="Use filesystem and fetch to answer questions.",
            server_names=["filesystem", "fetch"],
        )
        async with agent:
            llm = await agent.attach_llm(OpenAIAugmentedLLM)
            answer = await llm.generate_str("Summarize README.md in two sentences.")
            print(answer)

if __name__ == "__main__":
    asyncio.run(main())

MCP Fit

mcp-agent is useful when MCP servers are the primary capability surface for an agent. Instead of manually starting and wiring each server, the framework manages the connection lifecycle and makes those tools available to agent workflow code. The same application can start with local filesystem or fetch servers, then grow into SaaS, internal API, database, browser, or custom MCP server integrations.

For production-style workflows, durable execution lets agent work continue across process restarts when backed by Temporal. Agent-as-MCP-server patterns let teams expose a composed agent behind MCP so another client can call it like any other MCP server.

Use Cases

• Build Python agents that use existing MCP servers instead of custom adapters.
• Compose router, orchestrator, evaluator-optimizer, parallel, or map-reduce workflows around MCP tools.
• Wrap a specialized agent as an MCP server for Claude, Cursor, VS Code, or another MCP client.
• Add durable execution to long-running agent workflows with Temporal.
• Prototype MCP-native app patterns before committing to a larger agent platform.

Source Review

Verified on 2026-06-18:

• The upstream README describes mcp-agent as a composable framework for building effective agents with Model Context Protocol.
• The README lists full MCP support, effective agent patterns, durable Temporal agents, agent-as-MCP-server support, and cloud deployment paths.
• pyproject.toml lists the mcp-agent package, Python 3.10+ requirement, Apache-2.0 license file, mcp-agent CLI, and optional provider extras.
• PyPI reports the current mcp-agent package metadata.
• The docs cover getting started and effective-agent workflow patterns.

Safety and Privacy

Every MCP server attached to an agent is a trust boundary. Review the server's tool descriptions, credentials, network access, filesystem scope, account permissions, and logging before including it in an agent workflow.

For production agents, make retries, cancellation, idempotency, approval gates, rate limits, and rollback behavior explicit. Durable workflow state, traces, logs, prompts, tool results, and provider responses may persist after a process ends, especially with Temporal or observability integrations enabled.

Duplicate Check

Checked current content/mcp/, content/tools/, content/skills/, open pull requests, and repository-wide content for lastmile-ai/mcp-agent, mcp-agent, MCP agent framework, Python MCP agent framework, durable MCP agents, Temporal AI agents, agent-as-MCP-server, and MCP workflow patterns. Existing entries cover other agent frameworks such as VoltAgent and LiveKit Agents, but no dedicated mcp-agent entry, exact source URL duplicate, target file, or open duplicate PR was found.