Build effective agents with Model Context Protocol using simple, composable patterns.

Overview

**mcp-agent** is a simple, composable framework to build effective agents using Model Context Protocol.

[!Note]
mcp-agent's vision is that _MCP is all you need to build agents, and that simple patterns are more robust than complex architectures for shipping high-quality agents_.

mcp-agent gives you the following:

1. Full MCP support: It _fully_ implements MCP, and handles the pesky business of managing the lifecycle of MCP server connections so you don't have to.

2. Effective agent patterns: It implements every pattern described in Anthropic's Building Effective Agents in a _composable_ way, allowing you to chain these patterns together.

3. Durable agents: It works for simple agents and scales to sophisticated workflows built on Temporal so you can pause, resume, and recover without any API changes to your agent.

Altogether, this is the simplest and easiest way to build robust agent applications.

We welcome all kinds of contributions, feedback and your help in improving this project.

Minimal example

python

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())

# Add your LLM API key to `mcp_agent.secrets.yaml` or set it in env.
# The [Getting Started guide](https://docs.mcp-agent.com/get-started/overview) walks through configuration and secrets in detail.

At a glance

Build an Agent

Connect LLMs to MCP servers in simple, composable patterns like map-reduce, orchestrator, evaluator-optimizer, router & more.

Create any kind of MCP Server

Create MCP servers with a FastMCP-compatible API. You can even expose agents as MCP servers.

Full MCP Support

Core: Tools ✅ Resources ✅ Prompts ✅ Notifications ✅

Advanced: OAuth ✅ Sampling ✅ Elicitation ✅ Roots ✅

Durable Execution (Temporal)

Scales to production workloads using Temporal as the agent runtime backend without any API changes.

☁️ Deploy to Cloud

Beta: Deploy agents yourself, or use mcp-c for a managed agent runtime. All apps are deployed as MCP servers.

Documentation & build with LLMs

mcp-agent's complete documentation is available at **docs.mcp-agent.com**, including full SDK guides, CLI reference, and advanced patterns. This readme gives a high-level overview to get you started.

[llms-full.txt](https://docs.mcp-agent.com/llms-full.txt): contains entire documentation.
[llms.txt](https://docs.mcp-agent.com/llms.txt): sitemap listing key pages in the docs.
docs MCP server

Get Started

[!TIP]
The CLI is available via uvx mcp-agent.
To get up and running,
scaffold a project with uvx mcp-agent init and deploy with uvx mcp-agent deploy my-agent.
You can get up and running in 2 minutes by running these commands:
```bash
mkdir hello-mcp-agent && cd hello-mcp-agent
uvx mcp-agent init
uv init
uv add "mcp-agent[openai]"
# Add openai API key to mcp_agent.secrets.yaml or set OPENAI_API_KEY
uv run main.py
```

Installation

We recommend using uv to manage your Python projects (uv init).

bash

uv add "mcp-agent"

Alternatively:

bash

pip install mcp-agent

Also add optional packages for LLM providers (e.g. uv add "mcp-agent[openai, anthropic, google, azure, bedrock]").

Quickstart

[!TIP]
The [examples](/examples) directory has several example applications to get started with.
To run an example, clone this repo (or generate one with uvx mcp-agent init --template basic --dir my-first-agent)
```bash
cd examples/basic/mcp_basic_agent # Or any other example
# Option A: secrets YAML
# cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml && edit mcp_agent.secrets.yaml
uv run main.py
```

Here is a basic "finder" agent that uses the fetch and filesystem servers to look up a file, read a blog and write a tweet. Example link:

finder_agent.py

python

import asyncio
import os

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_agent")

async def example_usage():
    async with app.run() as mcp_agent_app:
        logger = mcp_agent_app.logger
        # This agent can read the filesystem or fetch URLs
        finder_agent = Agent(
            name="finder",
            instruction="""You can read local files or fetch URLs.
                Return the requested information when asked.""",
            server_names=["fetch", "filesystem"], # MCP servers this Agent can use
        )

        async with finder_agent:
            # Automatically initializes the MCP servers and adds their tools for LLM use
            tools = await finder_agent.list_tools()
            logger.info(f"Tools available:", data=tools)

            # Attach an OpenAI LLM to the agent (defaults to GPT-4o)
            llm = await finder_agent.attach_llm(OpenAIAugmentedLLM)

            # This will perform a file lookup and read using the filesystem server
            result = await llm.generate_str(
                message="Show me what's in README.md verbatim"
            )
            logger.info(f"README.md contents: {result}")

            # Uses the fetch server to fetch the content from URL
            result = await llm.generate_str(
                message="Print the first two paragraphs from https://www.anthropic.com/research/building-effective-agents"
            )
            logger.info(f"Blog intro: {result}")

            # Multi-turn interactions by default
            result = await llm.generate_str("Summarize that in a 128-char tweet")
            logger.info(f"Tweet: {result}")

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

mcp_agent.config.yaml

yaml

execution_engine: asyncio
logger:
  transports: [console] # You can use [file, console] for both
  level: debug
  path: "logs/mcp-agent.jsonl" # Used for file transport
  # For dynamic log filenames:
  # path_settings:
  #   path_pattern: "logs/mcp-agent-{unique_id}.jsonl"
  #   unique_id: "timestamp"  # Or "session_id"
  #   timestamp_format: "%Y%m%d_%H%M%S"

mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
    filesystem:
      command: "npx"
      args:
        [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "     | [Parallel](https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/map-reduce)                     |
| Router                | `create_router_llm(...)` / `create_router_embedding(...)`                       | Route requests to the best agent, server, or function. | [Router](https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/router)                           |
| Intent classifier     | `create_intent_classifier_llm(...)` / `create_intent_classifier_embedding(...)` | Bucket user input into intents before automation.                                                                                                                                                                                                                                                                                                                                                                                                                  | [Intent classifier](https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/intent-classifier)     |
| Orchestrator-workers  | `create_orchestrator(...)`                                                      | Generate plans and coordinate worker agents.           | [Planner](https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/planner)                         |
| Deep research         | `create_deep_orchestrator(...)`                                                 | Long-horizon research with knowledge extraction and policy checks.                                                                                                                                                                                                                                                                                                                                                                                                 | [Deep research](https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/deep-research)             |
| Evaluator-optimizer   | `create_evaluator_optimizer_llm(...)`                                           | Iterate until an evaluator approves the result.        | [Evaluator-optimizer](https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/evaluator-optimizer) |
| Swarm                 | `create_swarm(...)`                                                             | Multi-agent handoffs compatible with OpenAI Swarm.                                                                                                                                                                                                               | [Swarm](https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/swarm)                             |

## Durable execution

Switch `execution_engine` to `temporal` for pause/resume, retries, human input, and durable history—without changing workflow code. Run a worker alongside your app to host activities.

from mcp_agent.executor.temporal import create_temporal_worker_for_app

async with create_temporal_worker_for_app(app) as worker:

await worker.run()

code

Docs: [Durable agents](https://docs.mcp-agent.com/mcp-agent-sdk/advanced/durable-agents) • [Temporal backend](https://docs.mcp-agent.com/advanced/temporal) • Examples: [`examples/temporal`](./examples/temporal/).

## Agent servers

Expose an `MCPApp` as a standard MCP server so Claude Desktop, Cursor, or custom clients can call your tools and workflows.

from mcp_agent.server import create_mcp_server_for_app

@app.tool

def grade_story(story: str) -> str:

return "Report..."

if __name__ == "__main__":

server = create_mcp_server_for_app(app)

server.run_stdio()

code

Docs: [Agent servers](https://docs.mcp-agent.com/mcp-agent-sdk/mcp/agent-as-mcp-server) • Examples: [`examples/mcp_agent_server`](./examples/mcp_agent_server/).

## CLI reference

`uvx mcp-agent` scaffolds projects, manages secrets, inspects workflows, and deploys to Cloud.

uvx mcp-agent init --template basic # Scaffold a new project

uvx mcp-agent deploy my-agent # Deploy to mcp-agent Cloud

code

Docs: [CLI reference](https://docs.mcp-agent.com/reference/cli) • [Getting started guides](https://docs.mcp-agent.com/get-started/quickstart).

## Authentication

Load API keys from secrets files or use the built-in OAuth client to fetch and persist tokens for MCP servers.

mcp_agent.config.yaml excerpt

oauth:

providers:

github:

client_id: "${GITHUB_CLIENT_ID}"

client_secret: "${GITHUB_CLIENT_SECRET}"

scopes: ["repo", "user"]

code

Docs: [Advanced authentication](https://docs.mcp-agent.com/mcp-agent-sdk/advanced/authentication) • [Server authentication](https://docs.mcp-agent.com/mcp-agent-sdk/mcp/server-authentication) • Examples: [`examples/basic/oauth_basic_agent`](./examples/basic/oauth_basic_agent/).

## Advanced

### Observability & controls

Enable structured logging and OpenTelemetry via configuration, and track token usage programmatically.

mcp_agent.config.yaml

logger:

transports: [console]

level: info

otel:

enabled: true

exporters:

console

code

`TokenCounter` tracks token usage for agents, workflows, and LLM nodes. Attach watchers to stream updates or trigger alerts.

Inside `async with app.run() as running_app:`

token_counter lives on the running app context when tracing is enabled.

token_counter = running_app.context.token_counter

class TokenMonitor:

async def on_token_update(self, node, usage):

print(f"[{node.name}] total={usage.total_tokens}")

monitor = TokenMonitor()

watch_id = await token_counter.watch(

callback=monitor.on_token_update,

node_type="llm",

threshold=1_000,

include_subtree=True,

)

await token_counter.unwatch(watch_id)

code

Docs: [Observability](https://docs.mcp-agent.com/mcp-agent-sdk/advanced/observability) • Examples: [`examples/tracing`](./examples/tracing/).

### Composing workflows

Mix and match AgentSpecs to build higher-level workflows using the factory helpers—routers, parallel pipelines, orchestrators, and more.

from mcp_agent.workflows.factory import create_router_llm

specs are loaded via load_agent_specs_from_file as shown above.

async with app.run() as running_app:

router = await create_router_llm(

agents=specs,

provider="openai",

context=running_app.context,

)

code

Docs: [Workflow composition](https://docs.mcp-agent.com/mcp-agent-sdk/advanced/composition) • Examples: [`examples/basic/agent_factory`](./examples/basic/agent_factory/).

### Signals & human input

Pause workflows for approvals or extra data. Temporal stores state durably until an operator resumes the run.

from mcp_agent.human_input.types import HumanInputRequest

response = await self.context.request_human_input(

HumanInputRequest(

prompt="Approve the draft?",

required=True,

metadata={"workflow_id": self.context.workflow_id},

)

code

Resume with `mcp-agent cloud workflows resume … --payload '{"content": "approve"}'`. Docs: [Deploy agents – human input](https://docs.mcp-agent.com/cloud/use-cases/deploy-agents#human-in-the-loop-patterns) • Examples: [`examples/human_input/temporal`](./examples/human_input/temporal/).

### App configuration

Build `Settings` objects programmatically when you need dynamic config (tests, multi-tenant hosts) instead of YAML files.

from mcp_agent.config import Settings, MCPSettings, MCPServerSettings

settings = Settings(

execution_engine="asyncio",

mcp=MCPSettings(

servers={

"fetch": MCPServerSettings(command="uvx", args=["mcp-server-fetch"]),

}

)

app = MCPApp(name="configured_app", settings=settings)

code

Docs: [Configuring your application](https://docs.mcp-agent.com/mcp-agent-sdk/core-components/configuring-your-application).

### Icons

Add icons to agents and tools so MCP clients that support imagery (Claude Desktop, Cursor) render richer UIs.

from base64 import standard_b64encode

from pathlib import Path

from mcp_agent.icons import Icon

icon_data = standard_b64encode(Path("my-icon.png").read_bytes()).decode()

icon = Icon(src=f"data:image/png;base64,{icon_data}", mimeType="image/png", sizes=["64x64"])

app = MCPApp(name="my_app_with_icon", icons=[icon])

@app.tool(icons=[icon])

async def my_tool() -> str:

return "Hello with style"

code

Docs: [`MCPApp` icons](https://docs.mcp-agent.com/mcp-agent-sdk/core-components/mcpapp#icons) • Examples: [`examples/mcp_agent_server/asyncio`](./examples/mcp_agent_server/asyncio/).

### MCP server management

Use `MCPAggregator` or `gen_client` to manage MCP server connections and expose combined tool sets.

from mcp_agent.mcp.mcp_aggregator import MCPAggregator

async with MCPAggregator.create(server_names=["fetch", "filesystem"]) as aggregator:

tools = await aggregator.list_tools()

code

Docs: [Connecting to MCP servers](https://docs.mcp-agent.com/mcp-agent-sdk/core-components/connecting-to-mcp-servers) • Examples: [`examples/basic/mcp_server_aggregator`](./examples/basic/mcp_server_aggregator/).

## Cloud deployment

Deploy to mcp-agent Cloud for managed Temporal execution, secrets, and HTTPS MCP endpoints.

uvx mcp-agent login

uvx mcp-agent deploy my-agent

uvx mcp-agent cloud apps list

code

Docs: [Cloud overview](https://docs.mcp-agent.com/cloud/overview) • [Deployment quickstart](https://docs.mcp-agent.com/cloud/deployment-quickstart) • Examples: [`examples/cloud`](./examples/cloud/).

## Examples

Browse [gallery.md](gallery.md) for runnable examples, demo videos, and community projects grouped by concept. Every entry cites the docs page and command you need to run it locally.

## FAQs

### What are the core benefits of using mcp-agent?

mcp-agent provides a streamlined approach to building AI agents using capabilities exposed by **MCP** (Model Context Protocol) servers.

MCP is quite low-level, and this framework handles the mechanics of connecting to servers, working with LLMs, handling external signals (like human input) and supporting persistent state via durable execution. That lets you, the developer, focus on the core business logic of your AI application.

Core benefits:

- 🤝 **Interoperability**: ensures that any tool exposed by any number of MCP servers can seamlessly plug in to your agents.
- ⛓️ **Composability & Customizability**: Implements well-defined workflows, but in a composable way that enables compound workflows, and allows full customization across model provider, logging, orchestrator, etc.
- 💻 **Programmatic control flow**: Keeps things simple as developers just write code instead of thinking in graphs, nodes and edges. For branching logic, you write `if` statements. For cycles, use `while` loops.
- 🖐️ **Human Input & Signals**: Supports pausing workflows for external signals, such as human input, which are exposed as tool calls an Agent can make.

### Do you need an MCP client to use mcp-agent?

No, you can use mcp-agent anywhere, since it handles MCPClient creation for you. This allows you to leverage MCP servers outside of MCP hosts like Claude Desktop.

Here's all the ways you can set up your mcp-agent application:

#### MCP-Agent Server

You can expose mcp-agent applications as MCP servers themselves (see [example](./examples/mcp_agent_server)), allowing MCP clients to interface with sophisticated AI workflows using the standard tools API of MCP servers. This is effectively a server-of-servers.

#### MCP Client or Host

You can embed mcp-agent in an MCP client directly to manage the orchestration across multiple MCP servers.

#### Standalone

You can use mcp-agent applications in a standalone fashion (i.e. they aren't part of an MCP client). The [`examples`](/examples/) are all standalone applications.

### How do I deploy to Cloud?

Run `uvx mcp-agent deploy

Mcp Agent

Documentation

Overview

At a glance

Documentation & build with LLMs

Table of Contents

Get Started

Installation

Quickstart

mcp_agent.config.yaml excerpt

mcp_agent.config.yaml

Inside `async with app.run() as running_app:`

token_counter lives on the running app context when tracing is enabled.

specs are loaded via load_agent_specs_from_file as shown above.

Similar MCP

Biomcp

Fal Mcp Server

Anilist Mcp

Serena

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Similar MCP

Biomcp

Fal Mcp Server

Anilist Mcp

Serena

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Mcp Agent

Documentation

Overview

At a glance

Documentation & build with LLMs

Table of Contents

Get Started

Installation

Quickstart

mcp_agent.config.yaml excerpt

mcp_agent.config.yaml

Inside async with app.run() as running_app:

token_counter lives on the running app context when tracing is enabled.

specs are loaded via load_agent_specs_from_file as shown above.

Similar MCP

Biomcp

Fal Mcp Server

Anilist Mcp

Serena

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Biomcp

Fal Mcp Server

Anilist Mcp

Serena

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Inside `async with app.run() as running_app:`