MCP Agent is a Python framework for building agents on the Model Context Protocol (MCP). It implements MCP and manages the lifecycle of MCP server connections, so an agent declares the servers it may use by name and the framework handles connecting, tool discovery, and teardown. Core and advanced MCP surfaces are covered: tools, resources, prompts, notifications, OAuth, sampling, elicitation, and roots.
The building blocks are an MCPApp that owns configuration and context, agents defined in code or as reusable AgentSpec files, and Augmented LLMs that wrap a provider SDK with the agent's tools, memory, and structured-output helpers. Attaching an Augmented LLM to an agent gives generate, generatestr, and generatestructured calls.
The agent patterns from Anthropic's Building Effective Agents are each implemented as an Augmented LLM, so they compose with one another: parallel map-reduce, router, intent classifier, orchestrator-workers, deep research, evaluator-optimizer, and a swarm pattern for multi-agent handoffs. Factory helpers such as createparallelllm, createrouterllm, createorchestrator, and createevaluatoroptimizerllm wire them up.
An MCPApp can also be published as an MCP server through a FastMCP-compatible API, which lets MCP clients such as Claude Desktop or Cursor call its tools and workflows, and agents themselves be exposed as servers. Setting the execution engine to Temporal turns workflows into durable ones with pause, resume, retries, human input, and durable history, without changing workflow code; a worker process runs alongside the app to host activities. A CLI scaffolds projects and deploys them, and a beta cloud runtime hosts deployed apps as MCP servers.
Configuration and secrets live in mcpagent.config.yaml and mcpagent.secrets.yaml. Structured logging and OpenTelemetry tracing are switched on through configuration, a TokenCounter tracks token usage per agent, workflow, and LLM node with watchers for streaming updates, and a built-in OAuth client fetches and persists tokens for MCP servers that require them.
Features
- MCP connection management: server lifecycle, tool discovery, and teardown handled for the agent, including outside MCP hosts
- Composable patterns: parallel map-reduce, router, intent classifier, orchestrator-workers, deep research, evaluator-optimizer, and swarm handoffs, each an Augmented LLM
- Augmented LLM: provider SDKs wrapped with the agent's tools, memory, and generate_structured output helpers
- Agent specs: AgentSpec definitions loaded from disk and turned into agents or Augmented LLMs by factory helpers
- Agent as MCP server: a FastMCP-compatible API exposes an app's tools and workflows to MCP clients
- Durable execution: a Temporal execution engine adds pause, resume, retries, and durable history without workflow code changes
- Signals and human input: workflows can wait on external signals or a person before continuing
- Observability: structured logging, OpenTelemetry exporters, and a TokenCounter with attachable watchers
- Authentication: secrets files plus an OAuth client that fetches and persists per-server tokens
- CLI and cloud: mcp-agent init scaffolds a project and mcp-agent deploy publishes it to the beta cloud runtime
