The Getting Started guide walks through configuration and secrets in detail.

At a glance
<table>

  <tr>

    <td width="50%" valign="top">

      <h3>Build an Agent</h3>

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

      <p>

        <a href="https://docs.mcp-agent.com/get-started/overview">Quick Start ↗</a> | 

        <a href="https://docs.mcp-agent.com/mcp-agent-sdk/overview">Docs ↗</a>

      </p>

    </td>

    <td width="50%" valign="top">

      <h3>Create any kind of MCP Server</h3>

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

      <p>

        <a href="https://docs.mcp-agent.com/mcp-agent-sdk/mcp/agent-as-mcp-server">MCP Agent Server ↗</a> | 

        <a href="https://docs.mcp-agent.com/cloud/use-cases/deploy-chatgpt-apps">🎨 Build a ChatGPT App ↗</a> | 

        <a href="https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp_agent_server">Examples ↗</a>

      </p>

    </td>

  </tr>

    <tr>

    <td width="50%" valign="top">

      <h3>Full MCP Support</h3>

      <p><b>Core:</b> Tools ✅ Resources ✅ Prompts ✅ Notifications ✅<br/>

      <b>Advanced</b>: OAuth ✅ Sampling ✅ Elicitation ✅ Roots ✅</p>

      <p>

        <a href="https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp">Examples ↗</a> | 

        <a href="https://modelcontextprotocol.io/docs/getting-started/intro">MCP Docs ↗</a>

      </p>

    </td>

    <td width="50%" valign="top">

      <h3>Durable Execution (Temporal)</h3>

      <p>Scales to production workloads using Temporal as the agent runtime backend <i>without any API changes</i>.</p>

      <p>

        <a href="https://docs.mcp-agent.com/mcp-agent-sdk/advanced/durable-agents">Docs ↗</a> | 

        <a href="https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal">Examples ↗</a>

      </p>

    </td>

  </tr>

  <tr>

    <td width="50%" valign="top">

      <h3>☁️ Deploy to Cloud</h3>

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

      <p>

        <a href="https://www.youtube.com/watch?v=0C4VY-3IVNU">Demo ↗</a> |

        <a href="https://docs.mcp-agent.com/get-started/cloud">Cloud Quickstart ↗</a> | 

        <a href="https://github.com/lastmile-ai/mcp-agent/tree/main/examples/cloud">Examples ↗</a>

      </p>

    </td>

  </tr>

</table>
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: contains entire documentation.

- llms.txt: sitemap listing key pages in the docs.

- docs MCP server
Table of Contents
- Overview

- Minimal example

- Quickstart

- Why mcp-agent

- Core concepts

  - MCPApp

  - Agents & AgentSpec

  - Augmented LLM

  - Workflows & decorators

  - Configuration & secrets

  - MCP integration

- Workflow patterns

- CLI reference

- Authentication

- Advanced

  - Observability & controls

  - Composing workflows

  - Durable execution

  - Agent servers

  - Signals & human input

  - App configuration

  - Icons

  - MCP server management

- Cloud deployment

- Examples

- FAQs

- Community & contributions
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 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:

<details open>

<summary>finder_agent.py</summary>

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

</details>
<details>

<summary>mcp_agent.config.yaml</summary>

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",
"<add_your_directories>",
]

openai:
# Secrets (API keys, etc.) are stored in an mcp_agent.secrets.yaml file which can be gitignored
default_model: gpt-4o

</details>

<details>

<summary>Agent output</summary>



</details>
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.mcp-agent 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 • 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 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 • Example: 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 • Agent factory helpers • Examples: 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 • Examples: examples/basic/mcp_basic_agent and the workflow projects listed in gallery.md.

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 • Examples: 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