[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-71990":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":34,"readmeContent":35,"aiSummary":36,"trendingCount":16,"starSnapshotCount":16,"syncStatus":37,"lastSyncTime":38,"discoverSource":39},71990,"mcp-agent","lastmile-ai\u002Fmcp-agent","lastmile-ai","Build effective agents using Model Context Protocol and simple workflow patterns","",null,"Python",8365,854,49,86,0,14,18,51,42,39.8,"Apache License 2.0",false,"main",[26,27,28,29,30,31,32,33],"agents","ai","ai-agents","llm","llms","mcp","model-context-protocol","python","2026-06-12 02:02:57","\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fc8d059e5-bd56-4ea2-a72d-807fb4897bde\" alt=\"Logo\" width=\"300\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cem>Build effective agents with Model Context Protocol using simple, composable patterns.\u003C\u002Fem>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\" target=\"_blank\">\u003Cstrong>Examples\u003C\u002Fstrong>\u003C\u002Fa>\n  |\n  \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Foverview\" target=\"_blank\">\u003Cstrong>Building Effective Agents\u003C\u002Fstrong>\u003C\u002Fa>\n  |\n  \u003Ca href=\"https:\u002F\u002Fmodelcontextprotocol.io\u002Fintroduction\" target=\"_blank\">\u003Cstrong>MCP\u003C\u002Fstrong>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n\u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocs-8F?style=flat&link=https%3A%2F%2Fdocs.mcp-agent.com%2F\" \u002F>\u003Ca\u002F>\n\u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Fmcp-agent\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fmcp-agent?color=%2334D058&label=pypi\" \u002F>\u003C\u002Fa>\n\u003Cimg alt=\"Pepy Total Downloads\" src=\"https:\u002F\u002Fimg.shields.io\u002Fpepy\u002Fdt\u002Fmcp-agent?label=pypi%20%7C%20downloads\"\u002F>\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Fblob\u002Fmain\u002FLICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-Apache_2.0-blue.svg\"\u002F>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Flmai.link\u002Fdiscord\u002Fmcp-agent\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-%235865F2.svg?logo=discord&logoColor=white\" alt=\"discord\"\u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n\u003Ca href=\"https:\u002F\u002Ftrendshift.io\u002Frepositories\u002F13216\" target=\"_blank\">\u003Cimg src=\"https:\u002F\u002Ftrendshift.io\u002Fapi\u002Fbadge\u002Frepositories\u002F13216\" alt=\"lastmile-ai%2Fmcp-agent | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"\u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n## Overview\n\n**`mcp-agent`** is a simple, composable framework to build effective agents using [Model Context Protocol](https:\u002F\u002Fmodelcontextprotocol.io\u002Fintroduction).\n\n> [!Note]\n> 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_.\n\n`mcp-agent` gives you the following:\n\n1. **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.\n2. **Effective agent patterns**: It implements every pattern described in Anthropic's [Building Effective Agents](https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fbuilding-effective-agents) in a _composable_ way, allowing you to chain these patterns together.\n3. **Durable agents**: It works for simple agents and scales to sophisticated workflows built on [Temporal](https:\u002F\u002Ftemporal.io\u002F) so you can pause, resume, and recover without any API changes to your agent.\n\n\u003Cu>Altogether, this is the simplest and easiest way to build robust agent applications\u003C\u002Fu>.\n\nWe welcome all kinds of [contributions](\u002FCONTRIBUTING.md), feedback and your help in improving this project.\n\n\u003Ca id=\"minimal-example\">\u003C\u002Fa>\n**Minimal example**\n\n```python\nimport asyncio\n\nfrom mcp_agent.app import MCPApp\nfrom mcp_agent.agents.agent import Agent\nfrom mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM\n\napp = MCPApp(name=\"hello_world\")\n\nasync def main():\n    async with app.run():\n        agent = Agent(\n            name=\"finder\",\n            instruction=\"Use filesystem and fetch to answer questions.\",\n            server_names=[\"filesystem\", \"fetch\"],\n        )\n        async with agent:\n            llm = await agent.attach_llm(OpenAIAugmentedLLM)\n            answer = await llm.generate_str(\"Summarize README.md in two sentences.\")\n            print(answer)\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n\n# Add your LLM API key to `mcp_agent.secrets.yaml` or set it in env.\n# The [Getting Started guide](https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Foverview) walks through configuration and secrets in detail.\n\n```\n\n## At a glance\n\n\u003Ctable>\n  \u003Ctr>\n    \u003Ctd width=\"50%\" valign=\"top\">\n      \u003Ch3>Build an Agent\u003C\u002Fh3>\n      \u003Cp>Connect LLMs to MCP servers in simple, composable patterns like map-reduce, orchestrator, evaluator-optimizer, router & more.\u003C\u002Fp>\n      \u003Cp>\n        \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Foverview\">Quick Start ↗\u003C\u002Fa> | \n        \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Foverview\">Docs ↗\u003C\u002Fa>\n      \u003C\u002Fp>\n    \u003C\u002Ftd>\n    \u003Ctd width=\"50%\" valign=\"top\">\n      \u003Ch3>Create any kind of MCP Server\u003C\u002Fh3>\n      \u003Cp>Create MCP servers with a FastMCP-compatible API. You can even expose agents as MCP servers.\u003C\u002Fp>\n      \u003Cp>\n        \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fmcp\u002Fagent-as-mcp-server\">MCP Agent Server ↗\u003C\u002Fa> | \n        \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fcloud\u002Fuse-cases\u002Fdeploy-chatgpt-apps\">🎨 Build a ChatGPT App ↗\u003C\u002Fa> | \n        \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\u002Fmcp_agent_server\">Examples ↗\u003C\u002Fa>\n      \u003C\u002Fp>\n    \u003C\u002Ftd>\n  \u003C\u002Ftr>\n    \u003Ctr>\n    \u003Ctd width=\"50%\" valign=\"top\">\n      \u003Ch3>Full MCP Support\u003C\u002Fh3>\n      \u003Cp>\u003Cb>Core:\u003C\u002Fb> Tools ✅ Resources ✅ Prompts ✅ Notifications ✅\u003Cbr\u002F>\n      \u003Cb>Advanced\u003C\u002Fb>: OAuth ✅ Sampling ✅ Elicitation ✅ Roots ✅\u003C\u002Fp>\n      \u003Cp>\n        \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\u002Fmcp\">Examples ↗\u003C\u002Fa> | \n        \u003Ca href=\"https:\u002F\u002Fmodelcontextprotocol.io\u002Fdocs\u002Fgetting-started\u002Fintro\">MCP Docs ↗\u003C\u002Fa>\n      \u003C\u002Fp>\n    \u003C\u002Ftd>\n    \u003Ctd width=\"50%\" valign=\"top\">\n      \u003Ch3>Durable Execution (Temporal)\u003C\u002Fh3>\n      \u003Cp>Scales to production workloads using Temporal as the agent runtime backend \u003Ci>without any API changes\u003C\u002Fi>.\u003C\u002Fp>\n      \u003Cp>\n        \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fadvanced\u002Fdurable-agents\">Docs ↗\u003C\u002Fa> | \n        \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\u002Ftemporal\">Examples ↗\u003C\u002Fa>\n      \u003C\u002Fp>\n    \u003C\u002Ftd>\n  \u003C\u002Ftr>\n  \u003Ctr>\n    \u003Ctd width=\"50%\" valign=\"top\">\n      \u003Ch3>☁️ Deploy to Cloud\u003C\u002Fh3>\n      \u003Cp>\u003Cb>Beta:\u003C\u002Fb> Deploy agents yourself, or use \u003Cb>mcp-c\u003C\u002Fb> for a managed agent runtime. All apps are deployed as MCP servers.\u003C\u002Fp>\n      \u003Cp>\n        \u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=0C4VY-3IVNU\">Demo ↗\u003C\u002Fa> |\n        \u003Ca href=\"https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Fcloud\">Cloud Quickstart ↗\u003C\u002Fa> | \n        \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Ftree\u002Fmain\u002Fexamples\u002Fcloud\">Examples ↗\u003C\u002Fa>\n      \u003C\u002Fp>\n    \u003C\u002Ftd>\n  \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n## Documentation & build with LLMs\n\nmcp-agent's complete documentation is available at **[docs.mcp-agent.com](https:\u002F\u002Fdocs.mcp-agent.com)**, including full SDK guides, CLI reference, and advanced patterns. This readme gives a high-level overview to get you started.\n\n- [`llms-full.txt`](https:\u002F\u002Fdocs.mcp-agent.com\u002Fllms-full.txt): contains entire documentation.\n- [`llms.txt`](https:\u002F\u002Fdocs.mcp-agent.com\u002Fllms.txt): sitemap listing key pages in the docs.\n- [docs MCP server](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp)\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Minimal example](#minimal-example)\n- [Quickstart](#get-started)\n- [Why mcp-agent](#why-use-mcp-agent)\n- [Core concepts](#core-components)\n  - [MCPApp](#mcpapp)\n  - [Agents & AgentSpec](#agents--agentspec)\n  - [Augmented LLM](#augmented-llm)\n  - [Workflows & decorators](#workflows--decorators)\n  - [Configuration & secrets](#configuration--secrets)\n  - [MCP integration](#mcp-integration)\n- [Workflow patterns](#workflow-patterns)\n- [CLI reference](#cli-reference)\n- [Authentication](#authentication)\n- [Advanced](#advanced)\n  - [Observability & controls](#observability--controls)\n  - [Composing workflows](#composing-workflows)\n  - [Durable execution](#durable-execution)\n  - [Agent servers](#agent-servers)\n  - [Signals & human input](#signals--human-input)\n  - [App configuration](#app-configuration)\n  - [Icons](#icons)\n  - [MCP server management](#mcp-server-management)\n- [Cloud deployment](#cloud-deployment)\n- [Examples](#examples)\n- [FAQs](#faqs)\n- [Community & contributions](#contributing)\n\n## Get Started\n\n> [!TIP]\n> The CLI is available via `uvx mcp-agent`.\n> To get up and running,\n> scaffold a project with `uvx mcp-agent init` and deploy with `uvx mcp-agent deploy my-agent`.\n>\n> You can get up and running in 2 minutes by running these commands:\n>\n> ```bash\n> mkdir hello-mcp-agent && cd hello-mcp-agent\n> uvx mcp-agent init\n> uv init\n> uv add \"mcp-agent[openai]\"\n> # Add openai API key to `mcp_agent.secrets.yaml` or set `OPENAI_API_KEY`\n> uv run main.py\n> ```\n\n### Installation\n\nWe recommend using [uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F) to manage your Python projects (`uv init`).\n\n```bash\nuv add \"mcp-agent\"\n```\n\nAlternatively:\n\n```bash\npip install mcp-agent\n```\n\nAlso add optional packages for LLM providers (e.g. `uv add \"mcp-agent[openai, anthropic, google, azure, bedrock]\"`).\n\n### Quickstart\n\n> [!TIP]\n> The [`examples`](\u002Fexamples) directory has several example applications to get started with.\n> To run an example, clone this repo (or generate one with `uvx mcp-agent init --template basic --dir my-first-agent`)\n>\n> ```bash\n> cd examples\u002Fbasic\u002Fmcp_basic_agent # Or any other example\n> # Option A: secrets YAML\n> # cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml && edit mcp_agent.secrets.yaml\n> uv run main.py\n> ```\n\nHere 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](.\u002Fexamples\u002Fbasic\u002Fmcp_basic_agent\u002F):\n\n\u003Cdetails open>\n\u003Csummary>finder_agent.py\u003C\u002Fsummary>\n\n```python\nimport asyncio\nimport os\n\nfrom mcp_agent.app import MCPApp\nfrom mcp_agent.agents.agent import Agent\nfrom mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM\n\napp = MCPApp(name=\"hello_world_agent\")\n\nasync def example_usage():\n    async with app.run() as mcp_agent_app:\n        logger = mcp_agent_app.logger\n        # This agent can read the filesystem or fetch URLs\n        finder_agent = Agent(\n            name=\"finder\",\n            instruction=\"\"\"You can read local files or fetch URLs.\n                Return the requested information when asked.\"\"\",\n            server_names=[\"fetch\", \"filesystem\"], # MCP servers this Agent can use\n        )\n\n        async with finder_agent:\n            # Automatically initializes the MCP servers and adds their tools for LLM use\n            tools = await finder_agent.list_tools()\n            logger.info(f\"Tools available:\", data=tools)\n\n            # Attach an OpenAI LLM to the agent (defaults to GPT-4o)\n            llm = await finder_agent.attach_llm(OpenAIAugmentedLLM)\n\n            # This will perform a file lookup and read using the filesystem server\n            result = await llm.generate_str(\n                message=\"Show me what's in README.md verbatim\"\n            )\n            logger.info(f\"README.md contents: {result}\")\n\n            # Uses the fetch server to fetch the content from URL\n            result = await llm.generate_str(\n                message=\"Print the first two paragraphs from https:\u002F\u002Fwww.anthropic.com\u002Fresearch\u002Fbuilding-effective-agents\"\n            )\n            logger.info(f\"Blog intro: {result}\")\n\n            # Multi-turn interactions by default\n            result = await llm.generate_str(\"Summarize that in a 128-char tweet\")\n            logger.info(f\"Tweet: {result}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(example_usage())\n\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>mcp_agent.config.yaml\u003C\u002Fsummary>\n\n```yaml\nexecution_engine: asyncio\nlogger:\n  transports: [console] # You can use [file, console] for both\n  level: debug\n  path: \"logs\u002Fmcp-agent.jsonl\" # Used for file transport\n  # For dynamic log filenames:\n  # path_settings:\n  #   path_pattern: \"logs\u002Fmcp-agent-{unique_id}.jsonl\"\n  #   unique_id: \"timestamp\"  # Or \"session_id\"\n  #   timestamp_format: \"%Y%m%d_%H%M%S\"\n\nmcp:\n  servers:\n    fetch:\n      command: \"uvx\"\n      args: [\"mcp-server-fetch\"]\n    filesystem:\n      command: \"npx\"\n      args:\n        [\n          \"-y\",\n          \"@modelcontextprotocol\u002Fserver-filesystem\",\n          \"\u003Cadd_your_directories>\",\n        ]\n\nopenai:\n  # Secrets (API keys, etc.) are stored in an mcp_agent.secrets.yaml file which can be gitignored\n  default_model: gpt-4o\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>Agent output\u003C\u002Fsummary>\n\u003Cimg width=\"2398\" alt=\"Image\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Feaa60fdf-bcc6-460b-926e-6fa8534e9089\" \u002F>\n\u003C\u002Fdetails>\n\n## Why use `mcp-agent`?\n\nThere are too many AI frameworks out there already. But `mcp-agent` is the only one that is purpose-built for a shared protocol - [MCP](https:\u002F\u002Fmodelcontextprotocol.io\u002Fintroduction).[mcp-agent](https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Fwelcome) pairs Anthropic’s Building Effective Agents patterns with a batteries-included MCP runtime so you can focus on behaviour, not boilerplate. Teams pick it because it is:\n\n- **Composable** – every pattern ships as a reusable workflow you can mix and match.\n- **MCP-native** – any MCP server (filesystem, fetch, Slack, Jira, FastMCP apps) connects without custom adapters.\n- **Production ready** – Temporal-backed durability, structured logging, token accounting, and Cloud deploys are first-class.\n- **Pythonic** – a handful of decorators and context managers wire everything together.\n\nDocs: [Welcome to mcp-agent](https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Fwelcome) • [Effective patterns overview](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Foverview).\n\n## Core Components\n\nEvery project revolves around a single `MCPApp` runtime that loads configuration, registers agents and MCP servers, and exposes tools\u002Fworkflows. The [Core Components guide](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Foverview) walks through these building blocks.\n\n### MCPApp\n\nInitialises configuration, logging, tracing, and the execution engine so everything shares one context.\n\n```python\nfrom mcp_agent.app import MCPApp\n\napp = MCPApp(name=\"finder_app\")\n\nasync def main():\n    async with app.run() as running_app:\n        logger = running_app.logger\n        logger.info(\"App ready\", data={\"servers\": list(running_app.context.server_registry.registry)})\n```\n\nDocs: [MCPApp](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fmcpapp) • Example: [`examples\u002Fbasic\u002Fmcp_basic_agent`](.\u002Fexamples\u002Fbasic\u002Fmcp_basic_agent\u002F).\n\n### Agents & AgentSpec\n\nAgents couple instructions with the MCP servers (and optional functions) they may call. `AgentSpec` definitions can be loaded from disk and turned into agents or Augmented LLMs with the factory helpers.\n\n```python\nfrom pathlib import Path\nfrom mcp_agent.agents.agent import Agent\nfrom mcp_agent.workflows.factory import load_agent_specs_from_file\n\nagent = Agent(\n    name=\"researcher\",\n    instruction=\"Research topics using web and filesystem access\",\n    server_names=[\"fetch\", \"filesystem\"],\n)\n\nasync with agent:\n    tools = await agent.list_tools()\n\nasync with app.run() as running_app:\n    specs = load_agent_specs_from_file(\n        str(Path(\"examples\u002Fbasic\u002Fagent_factory\u002Fagents.yaml\")),\n        context=running_app.context,\n    )\n```\n\nDocs: [Agents](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fagents) • [Agent factory helpers](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fagents#agentspec-and-factory-helpers) • Examples: [`examples\u002Fbasic\u002Fagent_factory`](.\u002Fexamples\u002Fbasic\u002Fagent_factory\u002F).\n\n### Augmented LLM\n\nAugmented LLMs wrap provider SDKs with the agent’s tools, memory, and structured output helpers. Attach one to an agent to unlock `generate`, `generate_str`, and `generate_structured`.\n\n```python\nfrom pydantic import BaseModel\nfrom mcp_agent.workflows.llm.augmented_llm import RequestParams\nfrom mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM\n\nclass Summary(BaseModel):\n    title: str\n    verdict: str\n\nasync with agent:\n    llm = await agent.attach_llm(OpenAIAugmentedLLM)\n    report = await llm.generate_str(\n        message=\"Draft a 3-sentence release note from CHANGELOG.md\",\n        request_params=RequestParams(maxTokens=400, temperature=0.2),\n    )\n    structured = await llm.generate_structured(\n        message=\"Return a JSON object with `title` and `verdict` summarising the README.\",\n        response_model=Summary,\n    )\n```\n\nDocs: [Augmented LLMs](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Faugmented-llm) • Examples: [`examples\u002Fbasic\u002Fmcp_basic_agent`](.\u002Fexamples\u002Fbasic\u002Fmcp_basic_agent\u002F) and the workflow projects listed in [gallery.md](gallery.md#workflow-patterns).\n\n### Workflows & decorators\n\n`MCPApp` decorators convert coroutines into durable workflows and tools. The same annotations work for both `asyncio` and Temporal execution.\n\n```python\nfrom datetime import timedelta\nfrom mcp_agent.executor.workflow import Workflow, WorkflowResult\n\n@app.workflow\nclass PublishArticle(Workflow[WorkflowResult[str]]):\n    @app.workflow_task(schedule_to_close_timeout=timedelta(minutes=5))\n    async def draft(self, topic: str) -> str:\n        return f\"- intro to {topic}\\n- highlights\\n- next steps\"\n\n    @app.workflow_run\n    async def run(self, topic: str) -> WorkflowResult[str]:\n        outline = await self.draft(topic)\n        return WorkflowResult(value=outline)\n```\n\nDocs: [Decorator reference](https:\u002F\u002Fdocs.mcp-agent.com\u002Freference\u002Fdecorators) • Examples: [`examples\u002Fworkflows`](.\u002Fexamples\u002Fworkflows\u002F).\n\n### Configuration & secrets\n\nSettings load from `mcp_agent.config.yaml`, `mcp_agent.secrets.yaml`, environment variables, and optional preload strings. Keep secrets out of source control.\n\n```yaml\n# mcp_agent.config.yaml\nexecution_engine: asyncio\nmcp:\n  servers:\n    fetch:\n      command: \"uvx\"\n      args: [\"mcp-server-fetch\"]\n    filesystem:\n      command: \"npx\"\n      args: [\"-y\", \"@modelcontextprotocol\u002Fserver-filesystem\"]\nopenai:\n  default_model: gpt-4o-mini\n\n# mcp_agent.secrets.yaml (gitignored)\nopenai:\n  api_key: \"${OPENAI_API_KEY}\"\n```\n\nDocs: [Configuration reference](https:\u002F\u002Fdocs.mcp-agent.com\u002Freference\u002Fconfiguration) • [Specify secrets](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fspecify-secrets).\n\n### MCP integration\n\nConnect to existing MCP servers programmatically or aggregate several into one façade.\n\n```python\nfrom mcp_agent.mcp.gen_client import gen_client\n\nasync with app.run():\n    async with gen_client(\"filesystem\", app.server_registry, context=app.context) as client:\n        resources = await client.list_resources()\n        app.logger.info(\"Filesystem resources\", data={\"uris\": [r.uri for r in resources.resources]})\n```\n\nDocs: [MCP integration overview](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp\u002Foverview) • Examples: [`examples\u002Fmcp`](.\u002Fexamples\u002Fmcp\u002F).\n\n## Workflow patterns\n\nKey agent patterns are implemented as an `AugmentedLLM`. Use factory helpers to wire them up or inspect the runnable projects listed in [gallery.md](gallery.md#workflow-patterns).\n\n| Pattern               | Helper                                                                          | Summary                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Docs                                                                                                   |\n| --------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |\n| Parallel (Map-Reduce) | `create_parallel_llm(...)`                                                      | Fan-out specialists and fan-in aggregated reports.\u003Cbr>\u003Ca href=\"https:\u002F\u002Fwww.anthropic.com\u002F_next\u002Fimage?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F406bb032ca007fd1624f261af717d70e6ca86286-2401x1000.png&w=3840&q=75\">\u003Cimg src=\"https:\u002F\u002Fwww.anthropic.com\u002F_next\u002Fimage?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F406bb032ca007fd1624f261af717d70e6ca86286-2401x1000.png&w=3840&q=75\" width=\"260\"\u002F>\u003C\u002Fa>     | [Parallel](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fmap-reduce)                     |\n| Router                | `create_router_llm(...)` \u002F `create_router_embedding(...)`                       | Route requests to the best agent, server, or function.\u003Cbr>\u003Ca href=\"https:\u002F\u002Fwww.anthropic.com\u002F_next\u002Fimage?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F5c0c0e9fe4def0b584c04d37849941da55e5e71c-2401x1000.png&w=3840&q=75\">\u003Cimg src=\"https:\u002F\u002Fwww.anthropic.com\u002F_next\u002Fimage?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F5c0c0e9fe4def0b584c04d37849941da55e5e71c-2401x1000.png&w=3840&q=75\" width=\"260\"\u002F>\u003C\u002Fa> | [Router](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Frouter)                           |\n| Intent classifier     | `create_intent_classifier_llm(...)` \u002F `create_intent_classifier_embedding(...)` | Bucket user input into intents before automation.                                                                                                                                                                                                                                                                                                                                                                                                                  | [Intent classifier](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fintent-classifier)     |\n| Orchestrator-workers  | `create_orchestrator(...)`                                                      | Generate plans and coordinate worker agents.\u003Cbr>\u003Ca href=\"https:\u002F\u002Fwww.anthropic.com\u002F_next\u002Fimage?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F8985fc683fae4780fb34eab1365ab78c7e51bc8e-2401x1000.png&w=3840&q=75\">\u003Cimg src=\"https:\u002F\u002Fwww.anthropic.com\u002F_next\u002Fimage?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F8985fc683fae4780fb34eab1365ab78c7e51bc8e-2401x1000.png&w=3840&q=75\" width=\"260\"\u002F>\u003C\u002Fa>           | [Planner](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fplanner)                         |\n| Deep research         | `create_deep_orchestrator(...)`                                                 | Long-horizon research with knowledge extraction and policy checks.                                                                                                                                                                                                                                                                                                                                                                                                 | [Deep research](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fdeep-research)             |\n| Evaluator-optimizer   | `create_evaluator_optimizer_llm(...)`                                           | Iterate until an evaluator approves the result.\u003Cbr>\u003Ca href=\"https:\u002F\u002Fwww.anthropic.com\u002F_next\u002Fimage?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F14f51e6406ccb29e695da48b17017e899a6119c7-2401x1000.png&w=3840&q=75\">\u003Cimg src=\"https:\u002F\u002Fwww.anthropic.com\u002F_next\u002Fimage?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F14f51e6406ccb29e695da48b17017e899a6119c7-2401x1000.png&w=3840&q=75\" width=\"260\"\u002F>\u003C\u002Fa>        | [Evaluator-optimizer](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fevaluator-optimizer) |\n| Swarm                 | `create_swarm(...)`                                                             | Multi-agent handoffs compatible with OpenAI Swarm.\u003Cbr>\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fopenai\u002Fswarm\u002Fblob\u002Fmain\u002Fassets\u002Fswarm_diagram.png?raw=true\">\u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fopenai\u002Fswarm\u002Fblob\u002Fmain\u002Fassets\u002Fswarm_diagram.png?raw=true\" width=\"220\"\u002F>\u003C\u002Fa>                                                                                                                                                                                                               | [Swarm](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Feffective-patterns\u002Fswarm)                             |\n\n## Durable execution\n\nSwitch `execution_engine` to `temporal` for pause\u002Fresume, retries, human input, and durable history—without changing workflow code. Run a worker alongside your app to host activities.\n\n```python\nfrom mcp_agent.executor.temporal import create_temporal_worker_for_app\n\nasync with create_temporal_worker_for_app(app) as worker:\n    await worker.run()\n```\n\nDocs: [Durable agents](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fadvanced\u002Fdurable-agents) • [Temporal backend](https:\u002F\u002Fdocs.mcp-agent.com\u002Fadvanced\u002Ftemporal) • Examples: [`examples\u002Ftemporal`](.\u002Fexamples\u002Ftemporal\u002F).\n\n## Agent servers\n\nExpose an `MCPApp` as a standard MCP server so Claude Desktop, Cursor, or custom clients can call your tools and workflows.\n\n```python\nfrom mcp_agent.server import create_mcp_server_for_app\n\n@app.tool\ndef grade_story(story: str) -> str:\n    return \"Report...\"\n\nif __name__ == \"__main__\":\n    server = create_mcp_server_for_app(app)\n    server.run_stdio()\n```\n\nDocs: [Agent servers](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fmcp\u002Fagent-as-mcp-server) • Examples: [`examples\u002Fmcp_agent_server`](.\u002Fexamples\u002Fmcp_agent_server\u002F).\n\n## CLI reference\n\n`uvx mcp-agent` scaffolds projects, manages secrets, inspects workflows, and deploys to Cloud.\n\n```bash\nuvx mcp-agent init --template basic             # Scaffold a new project\nuvx mcp-agent deploy my-agent                   # Deploy to mcp-agent Cloud\n```\n\nDocs: [CLI reference](https:\u002F\u002Fdocs.mcp-agent.com\u002Freference\u002Fcli) • [Getting started guides](https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002Fquickstart).\n\n## Authentication\n\nLoad API keys from secrets files or use the built-in OAuth client to fetch and persist tokens for MCP servers.\n\n```yaml\n# mcp_agent.config.yaml excerpt\noauth:\n  providers:\n    github:\n      client_id: \"${GITHUB_CLIENT_ID}\"\n      client_secret: \"${GITHUB_CLIENT_SECRET}\"\n      scopes: [\"repo\", \"user\"]\n```\n\nDocs: [Advanced authentication](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fadvanced\u002Fauthentication) • [Server authentication](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fmcp\u002Fserver-authentication) • Examples: [`examples\u002Fbasic\u002Foauth_basic_agent`](.\u002Fexamples\u002Fbasic\u002Foauth_basic_agent\u002F).\n\n## Advanced\n\n### Observability & controls\n\nEnable structured logging and OpenTelemetry via configuration, and track token usage programmatically.\n\n```yaml\n# mcp_agent.config.yaml\nlogger:\n  transports: [console]\n  level: info\notel:\n  enabled: true\n  exporters:\n    - console\n```\n\n`TokenCounter` tracks token usage for agents, workflows, and LLM nodes. Attach watchers to stream updates or trigger alerts.\n\n```python\n# Inside `async with app.run() as running_app:`\n# token_counter lives on the running app context when tracing is enabled.\ntoken_counter = running_app.context.token_counter\n\nclass TokenMonitor:\n    async def on_token_update(self, node, usage):\n        print(f\"[{node.name}] total={usage.total_tokens}\")\n\nmonitor = TokenMonitor()\nwatch_id = await token_counter.watch(\n    callback=monitor.on_token_update,\n    node_type=\"llm\",\n    threshold=1_000,\n    include_subtree=True,\n)\n\nawait token_counter.unwatch(watch_id)\n```\n\nDocs: [Observability](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fadvanced\u002Fobservability) • Examples: [`examples\u002Ftracing`](.\u002Fexamples\u002Ftracing\u002F).\n\n### Composing workflows\n\nMix and match AgentSpecs to build higher-level workflows using the factory helpers—routers, parallel pipelines, orchestrators, and more.\n\n```python\nfrom mcp_agent.workflows.factory import create_router_llm\n\n# specs are loaded via load_agent_specs_from_file as shown above.\nasync with app.run() as running_app:\n    router = await create_router_llm(\n        agents=specs,\n        provider=\"openai\",\n        context=running_app.context,\n    )\n```\n\nDocs: [Workflow composition](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fadvanced\u002Fcomposition) • Examples: [`examples\u002Fbasic\u002Fagent_factory`](.\u002Fexamples\u002Fbasic\u002Fagent_factory\u002F).\n\n### Signals & human input\n\nPause workflows for approvals or extra data. Temporal stores state durably until an operator resumes the run.\n\n```python\nfrom mcp_agent.human_input.types import HumanInputRequest\n\nresponse = await self.context.request_human_input(\n    HumanInputRequest(\n        prompt=\"Approve the draft?\",\n        required=True,\n        metadata={\"workflow_id\": self.context.workflow_id},\n    )\n)\n```\n\nResume with `mcp-agent cloud workflows resume … --payload '{\"content\": \"approve\"}'`. Docs: [Deploy agents – human input](https:\u002F\u002Fdocs.mcp-agent.com\u002Fcloud\u002Fuse-cases\u002Fdeploy-agents#human-in-the-loop-patterns) • Examples: [`examples\u002Fhuman_input\u002Ftemporal`](.\u002Fexamples\u002Fhuman_input\u002Ftemporal\u002F).\n\n### App configuration\n\nBuild `Settings` objects programmatically when you need dynamic config (tests, multi-tenant hosts) instead of YAML files.\n\n```python\nfrom mcp_agent.config import Settings, MCPSettings, MCPServerSettings\n\nsettings = Settings(\n    execution_engine=\"asyncio\",\n    mcp=MCPSettings(\n        servers={\n            \"fetch\": MCPServerSettings(command=\"uvx\", args=[\"mcp-server-fetch\"]),\n        }\n    ),\n)\napp = MCPApp(name=\"configured_app\", settings=settings)\n```\n\nDocs: [Configuring your application](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fconfiguring-your-application).\n\n### Icons\n\nAdd icons to agents and tools so MCP clients that support imagery (Claude Desktop, Cursor) render richer UIs.\n\n```python\nfrom base64 import standard_b64encode\nfrom pathlib import Path\nfrom mcp_agent.icons import Icon\n\nicon_data = standard_b64encode(Path(\"my-icon.png\").read_bytes()).decode()\nicon = Icon(src=f\"data:image\u002Fpng;base64,{icon_data}\", mimeType=\"image\u002Fpng\", sizes=[\"64x64\"])\n\napp = MCPApp(name=\"my_app_with_icon\", icons=[icon])\n\n@app.tool(icons=[icon])\nasync def my_tool() -> str:\n    return \"Hello with style\"\n```\n\nDocs: [`MCPApp` icons](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fmcpapp#icons) • Examples: [`examples\u002Fmcp_agent_server\u002Fasyncio`](.\u002Fexamples\u002Fmcp_agent_server\u002Fasyncio\u002F).\n\n### MCP server management\n\nUse `MCPAggregator` or `gen_client` to manage MCP server connections and expose combined tool sets.\n\n```python\nfrom mcp_agent.mcp.mcp_aggregator import MCPAggregator\n\nasync with MCPAggregator.create(server_names=[\"fetch\", \"filesystem\"]) as aggregator:\n    tools = await aggregator.list_tools()\n```\n\nDocs: [Connecting to MCP servers](https:\u002F\u002Fdocs.mcp-agent.com\u002Fmcp-agent-sdk\u002Fcore-components\u002Fconnecting-to-mcp-servers) • Examples: [`examples\u002Fbasic\u002Fmcp_server_aggregator`](.\u002Fexamples\u002Fbasic\u002Fmcp_server_aggregator\u002F).\n\n## Cloud deployment\n\nDeploy to mcp-agent Cloud for managed Temporal execution, secrets, and HTTPS MCP endpoints.\n\n```bash\nuvx mcp-agent login\nuvx mcp-agent deploy my-agent\nuvx mcp-agent cloud apps list\n```\n\nDocs: [Cloud overview](https:\u002F\u002Fdocs.mcp-agent.com\u002Fcloud\u002Foverview) • [Deployment quickstart](https:\u002F\u002Fdocs.mcp-agent.com\u002Fcloud\u002Fdeployment-quickstart) • Examples: [`examples\u002Fcloud`](.\u002Fexamples\u002Fcloud\u002F).\n\n## Examples\n\nBrowse [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.\n\n## FAQs\n\n### What are the core benefits of using mcp-agent?\n\nmcp-agent provides a streamlined approach to building AI agents using capabilities exposed by **MCP** (Model Context Protocol) servers.\n\nMCP 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.\n\nCore benefits:\n\n- 🤝 **Interoperability**: ensures that any tool exposed by any number of MCP servers can seamlessly plug in to your agents.\n- ⛓️ **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.\n- 💻 **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.\n- 🖐️ **Human Input & Signals**: Supports pausing workflows for external signals, such as human input, which are exposed as tool calls an Agent can make.\n\n### Do you need an MCP client to use mcp-agent?\n\nNo, 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.\n\nHere's all the ways you can set up your mcp-agent application:\n\n#### MCP-Agent Server\n\nYou can expose mcp-agent applications as MCP servers themselves (see [example](.\u002Fexamples\u002Fmcp_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.\n\n#### MCP Client or Host\n\nYou can embed mcp-agent in an MCP client directly to manage the orchestration across multiple MCP servers.\n\n#### Standalone\n\nYou can use mcp-agent applications in a standalone fashion (i.e. they aren't part of an MCP client). The [`examples`](\u002Fexamples\u002F) are all standalone applications.\n\n### How do I deploy to Cloud?\n\nRun `uvx mcp-agent deploy \u003Capp-name>` after logging in with `uvx mcp-agent login`. The CLI packages your project, provisions secrets, and exposes an MCP endpoint backed by a durable Temporal runtime. See the [Cloud quickstart](https:\u002F\u002Fdocs.mcp-agent.com\u002Fget-started\u002F\ncloud) for step-by-step screenshots and CLI output.\n\n### Where is the API reference?\n\nEvery class, decorator, and CLI command is documented on [docs.mcp-agent.com](https:\u002F\u002Fdocs.mcp-agent.com). The [API reference](https:\u002F\u002Fdocs.mcp-agent.com\u002Freference) and the [`llms-full.txt`](https:\u002F\u002Fdocs.mcp-agent.com\u002Fllms-full.txt) are designed so LLMs (or you) can ingest the whole surface area easily.\n\n### Tell me a fun fact\n\nI debated naming this project _silsila_ (سلسلہ), which means chain of events in Urdu. mcp-agent is more matter-of-fact, but there's still an easter egg in the project paying homage to silsila.\n\n## Contributing\n\nWe welcome contributions of every size—bug fixes, new examples, docs, or feature requests. Start with [CONTRIBUTING.md](.\u002FCONTRIBUTING.md), open a discussion, or drop by [Discord](https:\u002F\u002Flmai.link\u002Fdiscord\u002Fmcp-agent).\n\nmcp-agent would not be possible without the tireless efforts of the many open source contributors. Thank you!\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Flastmile-ai\u002Fmcp-agent\u002Fgraphs\u002Fcontributors\">\n    \u003Cimg src=\"https:\u002F\u002Fcontrib.rocks\u002Fimage?repo=lastmile-ai\u002Fmcp-agent\" alt=\"Contributor faces\" \u002F>\n  \u003C\u002Fa>\n\u003C\u002Fp>\n","`mcp-agent` 是一个用于构建基于模型上下文协议（MCP）的有效代理的框架，采用简洁可组合的设计模式。该项目的核心功能包括全面支持MCP、实现高效代理模式以及提供持久化代理能力，允许开发者轻松构建从简单到复杂的代理应用，并且能够无缝处理暂停、恢复和故障恢复等场景。特别适合需要灵活扩展和维护高质量AI代理的应用开发场景，如客户服务自动化、虚拟助手等。项目使用Python编写，遵循Apache License 2.0许可协议，社区活跃度高，文档详尽，便于上手和贡献。",2,"2026-06-11 03:39:50","high_star"]