# Mcp Agent > Build effective agents using Model Context Protocol and simple workflow patterns - **Type:** MCP server - **Install:** `agentstack add mcp-lastmile-ai-mcp-agent` - **Verified:** Yes β€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [lastmile-ai](https://agentstack.voostack.com/s/lastmile-ai) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [lastmile-ai](https://github.com/lastmile-ai) - **Source:** https://github.com/lastmile-ai/mcp-agent ## Install ```sh agentstack add mcp-lastmile-ai-mcp-agent ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Build effective agents with Model Context Protocol using simple, composable patterns. Examples | Building Effective Agents | MCP ## Overview **`mcp-agent`** is a simple, composable framework to build effective agents using [Model Context Protocol](https://modelcontextprotocol.io/introduction). > [!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](https://www.anthropic.com/engineering/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](https://temporal.io/) 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](/CONTRIBUTING.md), 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. Quick Start β†— | Docs β†— Create any kind of MCP Server Create MCP servers with a FastMCP-compatible API. You can even expose agents as MCP servers. MCP Agent Server β†— | 🎨 Build a ChatGPT App β†— | Examples β†— Full MCP Support Core: Tools βœ… Resources βœ… Prompts βœ… Notifications βœ… Advanced: OAuth βœ… Sampling βœ… Elicitation βœ… Roots βœ… Examples β†— | MCP Docs β†— Durable Execution (Temporal) Scales to production workloads using Temporal as the agent runtime backend without any API changes. Docs β†— | Examples β†— ☁️ Deploy to Cloud Beta: Deploy agents yourself, or use mcp-c for a managed agent runtime. All apps are deployed as MCP servers. Demo β†— | Cloud Quickstart β†— | Examples β†— ## Documentation & build with LLMs mcp-agent's complete documentation is available at **[docs.mcp-agent.com](https://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](https://docs.mcp-agent.com/mcp) ## Table of Contents - [Overview](#overview) - [Minimal example](#minimal-example) - [Quickstart](#get-started) - [Why mcp-agent](#why-use-mcp-agent) - [Core concepts](#core-components) - [MCPApp](#mcpapp) - [Agents & AgentSpec](#agents--agentspec) - [Augmented LLM](#augmented-llm) - [Workflows & decorators](#workflows--decorators) - [Configuration & secrets](#configuration--secrets) - [MCP integration](#mcp-integration) - [Workflow patterns](#workflow-patterns) - [CLI reference](#cli-reference) - [Authentication](#authentication) - [Advanced](#advanced) - [Observability & controls](#observability--controls) - [Composing workflows](#composing-workflows) - [Durable execution](#durable-execution) - [Agent servers](#agent-servers) - [Signals & human input](#signals--human-input) - [App configuration](#app-configuration) - [Icons](#icons) - [MCP server management](#mcp-server-management) - [Cloud deployment](#cloud-deployment) - [Examples](#examples) - [FAQs](#faqs) - [Community & contributions](#contributing) ## 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](https://docs.astral.sh/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](./examples/basic/mcp_basic_agent/): 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", "", ] openai: # Secrets (API keys, etc.) are stored in an mcp_agent.secrets.yaml file which can be gitignored default_model: gpt-4o ``` Agent output ## Why use `mcp-agent`? There 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://modelcontextprotocol.io/introduction).[mcp-agent](https://docs.mcp-agent.com/get-started/welcome) 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: - **Composable** – every pattern ships as a reusable workflow you can mix and match. - **MCP-native** – any MCP server (filesystem, fetch, Slack, Jira, FastMCP apps) connects without custom adapters. - **Production ready** – Temporal-backed durability, structured logging, token accounting, and Cloud deploys are first-class. - **Pythonic** – a handful of decorators and context managers wire everything together. Docs: [Welcome to mcp-agent](https://docs.mcp-agent.com/get-started/welcome) β€’ [Effective patterns overview](https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/overview). ## Core Components Every project revolves around a single `MCPApp` runtime that loads configuration, registers agents and MCP servers, and exposes tools/workflows. The [Core Components guide](https://docs.mcp-agent.com/mcp-agent-sdk/overview) walks through these building blocks. ### MCPApp Initialises configuration, logging, tracing, and the execution engine so everything shares one context. ```python from mcp_agent.app import MCPApp app = MCPApp(name="finder_app") async def main(): async with app.run() as running_app: logger = running_app.logger logger.info("App ready", data={"servers": list(running_app.context.server_registry.registry)}) ``` Docs: [MCPApp](https://docs.mcp-agent.com/mcp-agent-sdk/core-components/mcpapp) β€’ Example: [`examples/basic/mcp_basic_agent`](./examples/basic/mcp_basic_agent/). ### Agents & AgentSpec Agents 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. ```python from pathlib import Path from mcp_agent.agents.agent import Agent from mcp_agent.workflows.factory import load_agent_specs_from_file agent = Agent( name="researcher", instruction="Research topics using web and filesystem access", server_names=["fetch", "filesystem"], ) async with agent: tools = await agent.list_tools() async with app.run() as running_app: specs = load_agent_specs_from_file( str(Path("examples/basic/agent_factory/agents.yaml")), context=running_app.context, ) ``` Docs: [Agents](https://docs.mcp-agent.com/mcp-agent-sdk/core-components/agents) β€’ [Agent factory helpers](https://docs.mcp-agent.com/mcp-agent-sdk/core-components/agents#agentspec-and-factory-helpers) β€’ Examples: [`examples/basic/agent_factory`](./examples/basic/agent_factory/). ### Augmented LLM Augmented 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`. ```python from pydantic import BaseModel from mcp_agent.workflows.llm.augmented_llm import RequestParams from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM class Summary(BaseModel): title: str verdict: str async with agent: llm = await agent.attach_llm(OpenAIAugmentedLLM) report = await llm.generate_str( message="Draft a 3-sentence release note from CHANGELOG.md", request_params=RequestParams(maxTokens=400, temperature=0.2), ) structured = await llm.generate_structured( message="Return a JSON object with `title` and `verdict` summarising the README.", response_model=Summary, ) ``` Docs: [Augmented LLMs](https://docs.mcp-agent.com/mcp-agent-sdk/core-components/augmented-llm) β€’ Examples: [`examples/basic/mcp_basic_agent`](./examples/basic/mcp_basic_agent/) and the workflow projects listed in [gallery.md](gallery.md#workflow-patterns). ### Workflows & decorators `MCPApp` decorators convert coroutines into durable workflows and tools. The same annotations work for both `asyncio` and Temporal execution. ```python from datetime import timedelta from mcp_agent.executor.workflow import Workflow, WorkflowResult @app.workflow class PublishArticle(Workflow[WorkflowResult[str]]): @app.workflow_task(schedule_to_close_timeout=timedelta(minutes=5)) async def draft(self, topic: str) -> str: return f"- intro to {topic}\n- highlights\n- next steps" @app.workflow_run async def run(self, topic: str) -> WorkflowResult[str]: outline = await self.draft(topic) return WorkflowResult(value=outline) ``` Docs: [Decorator reference](https://docs.mcp-agent.com/reference/decorators) β€’ Examples: [`examples/workflows`](./examples/workflows/). ### Configuration & secrets Settings load from `mcp_agent.config.yaml`, `mcp_agent.secrets.yaml`, environment variables, and optional preload strings. Keep secrets out of source control. ```yaml # mcp_agent.config.yaml execution_engine: asyncio mcp: servers: fetch: command: "uvx" args: ["mcp-server-fetch"] filesystem: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem"] openai: default_model: gpt-4o-mini # mcp_agent.secrets.yaml (gitignored) openai: api_key: "${OPENAI_API_KEY}" ``` Docs: [Configuration reference](https://docs.mcp-agent.com/reference/configuration) β€’ [Specify secrets](https://docs.mcp-agent.com/mcp-agent-sdk/core-components/specify-secrets). ### MCP integration Connect to existing MCP servers programmatically or aggregate several into one faΓ§ade. ```python from mcp_agent.mcp.gen_client import gen_client async with app.run(): async with gen_client("filesystem", app.server_registry, context=app.context) as client: resources = await client.list_resources() app.logger.info("Filesystem resources", data={"uris": [r.uri for r in resources.resources]}) ``` Docs: [MCP integration overview](https://docs.mcp-agent.com/mcp/overview) β€’ Examples: [`examples/mcp`](./examples/mcp/). ## Workflow patterns Key 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). | Pattern | Helper | Summary | Docs … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source β€” we do not rehost the code. - **Author:** [lastmile-ai](https://github.com/lastmile-ai) - **Source:** [lastmile-ai/mcp-agent](https://github.com/lastmile-ai/mcp-agent) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** β€” Free ## Security capabilities Automated source analysis of v0.1.0 β€” what this tool can access: - **Network access:** no - **Filesystem access:** yes - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source β€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** β€” security scan: passed β€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-lastmile-ai-mcp-agent - Seller: https://agentstack.voostack.com/s/lastmile-ai - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack β€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.