> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-agent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Agent SDK Overview

> Understanding the core components and patterns of mcp-agent

## What is mcp-agent?

mcp-agent is a Python framework for building AI agents using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction). It provides a simple, composable way to build effective agents by combining standardized MCP servers with proven workflow patterns.

## Anatomy of an MCP Agent

The quickest way to internalise the stack is to walk through the [basic finder agent](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/mcp_basic_agent). Each step maps directly to a core SDK concept:

### 1. Configure servers and models

```yaml mcp_agent.config.yaml theme={null}
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
```

This defines the transports the agent can call and the model preferences it should use.

### 2. Bootstrap the application

```python title="main.py" theme={null}
from mcp_agent.app import MCPApp

app = MCPApp(name="finder_app")
```

`MCPApp` loads the config/secrets, prepares logging and tracing, and manages server connections.

### 3. Describe the agent

```python title="finder_agent.py" theme={null}
from mcp_agent.agents.agent import Agent

finder = Agent(
    name="finder",
    instruction="Fetch web pages or read files to answer questions.",
    server_names=["fetch", "filesystem"],
)
```

The agent couples instructions with the set of MCP servers it is allowed to use. When `async with finder:` runs, the agent initialises those connections via the app’s server registry.

### 4. Attach an augmented LLM

```python theme={null}
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

async with finder:
    llm = await finder.attach_llm(OpenAIAugmentedLLM)
    response = await llm.generate_str("Summarise README.md")
```

The augmented LLM automatically surfaces the agent’s tools (`fetch`, `read_text_file`, etc.) during generation.

### 5. Run inside the app context

```python theme={null}
async def main():
    async with app.run():
        async with finder:
            llm = await finder.attach_llm(OpenAIAugmentedLLM)
            result = await llm.generate_str("List key files in this repo")
            print(result)
```

You gain uniform logging, token accounting, and graceful shutdown by executing inside `app.run()`. From here, layer in more sophisticated patterns:

* Need persistent connections? Check out the [mcp\_server\_aggregator example](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/mcp_server_aggregator).
* Want OAuth-protected servers? Follow the [OAuth basic agent walkthrough](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/oauth_basic_agent).
* Ready for orchestration? Browse the [workflow gallery](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows) and the [Temporal projects](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal).

With these building blocks you can mix and match—swap models, add workflow decorators, run inside Temporal, or expose the whole app as an MCP server.

## Core Architecture

mcp-agent consists of four main layers:

<CardGroup cols={2}>
  <Card title="MCP Integration" icon="plug">
    Connect to any MCP server and automatically discover tools, resources, and prompts
  </Card>

  <Card title="Agent Layer" icon="robot">
    Agents that combine instructions with MCP server capabilities
  </Card>

  <Card title="LLM Integration" icon="brain">
    Augmented LLMs that can use tools and maintain conversation context
  </Card>

  <Card title="Workflow Patterns" icon="diagram-project">
    Composable patterns for orchestrating agents and tasks
  </Card>
</CardGroup>

## Key Components

### MCPApp

The `MCPApp` is the central application context that manages configuration, logging, and server connections:

```python theme={null}
from mcp_agent.app import MCPApp

app = MCPApp(name="my_agent_app")

# Use as context manager
async with app.run() as mcp_agent_app:
    logger = mcp_agent_app.logger
    # Your agent code here
```

[Learn more about MCPApp →](/mcp-agent-sdk/core-components/mcpapp)

### Agents

Agents are entities with specific instructions and access to MCP servers:

```python theme={null}
from mcp_agent.agents.agent import Agent

agent = Agent(
    name="researcher",
    instruction="Research topics using web and filesystem access",
    server_names=["fetch", "filesystem"]
)

async with agent:
    # Agent automatically connects to servers and discovers tools
    tools = await agent.list_tools()
```

[Learn more about Agents →](/mcp-agent-sdk/core-components/agents)

### AugmentedLLM

AugmentedLLMs are LLMs enhanced with tools from MCP servers:

```python theme={null}
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

async with agent:
    llm = await agent.attach_llm(OpenAIAugmentedLLM)

    # LLM can now use tools from connected MCP servers
    result = await llm.generate_str("Research quantum computing")
```

[Learn more about AugmentedLLM →](/mcp-agent-sdk/core-components/augmented-llm)

### MCP Servers

MCP servers provide tools, resources, and other capabilities to agents:

```yaml mcp_agent.config.yaml theme={null}
mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
```

[Learn more about MCP Servers →](/mcp-agent-sdk/core-components/mcp-servers)

### Workflows

Workflows are composable patterns for orchestrating agents:

```python theme={null}
from mcp_agent.workflows.parallel.parallel_llm import ParallelLLM

# Fan out to multiple agents in parallel
parallel = ParallelLLM(
    fan_in_agent=grader,
    fan_out_agents=[proofreader, fact_checker, style_enforcer],
    llm_factory=OpenAIAugmentedLLM,
)

result = await parallel.generate_str("Review this essay...")
```

[Learn more about Workflows →](/mcp-agent-sdk/core-components/workflows)

### Execution Engines

Execution engines determine how workflows run:

* **asyncio**: In-memory execution for development
* **Temporal**: Durable execution with pause/resume capabilities

```yaml mcp_agent.config.yaml theme={null}
execution_engine: temporal  # or asyncio
```

[Learn more about Execution Engines →](/mcp-agent-sdk/core-components/execution-engine)

## Workflow Patterns

mcp-agent implements all patterns from Anthropic's [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents):

<CardGroup cols={2}>
  <Card title="Parallel" icon="arrows-split-up-and-left" href="/mcp-agent-sdk/effective-patterns/parallel">
    Fan-out tasks to multiple agents
  </Card>

  <Card title="Router" icon="route" href="/mcp-agent-sdk/effective-patterns/router">
    Intelligent request routing
  </Card>

  <Card title="Intent Classifier" icon="brain" href="/mcp-agent-sdk/effective-patterns/intent-classifier">
    Understand user intent
  </Card>

  <Card title="Planner" icon="list-check" href="/mcp-agent-sdk/effective-patterns/planner">
    Plan and execute complex tasks
  </Card>

  <Card title="Deep Research" icon="magnifying-glass" href="/mcp-agent-sdk/effective-patterns/deep-research">
    Adaptive planning with knowledge extraction
  </Card>

  <Card title="Evaluator-Optimizer" icon="arrows-rotate" href="/mcp-agent-sdk/effective-patterns/evaluator-optimizer">
    Iterative improvement with LLM-as-judge
  </Card>

  <Card title="Swarm" icon="circle-nodes" href="/mcp-agent-sdk/effective-patterns/swarm">
    Multi-agent collaboration
  </Card>
</CardGroup>

## Model Context Protocol

mcp-agent provides full support for MCP capabilities:

<CardGroup cols={2}>
  <Card title="Tools" icon="wrench">
    Execute functions and produce side effects
  </Card>

  <Card title="Resources" icon="database">
    Access data and load context
  </Card>

  <Card title="Prompts" icon="message-code">
    Reusable templates for interactions
  </Card>

  <Card title="Sampling" icon="wand-magic-sparkles">
    Request LLM completions from clients
  </Card>
</CardGroup>

[Learn more about MCP Support →](/mcp-agent-sdk/mcp/overview)

## Next Steps

<CardGroup cols={2}>
  <Card title="Core Components" icon="cubes" href="/mcp-agent-sdk/core-components/configuring-your-application">
    Learn about the building blocks
  </Card>

  <Card title="Effective Patterns" icon="diagram-project" href="/mcp-agent-sdk/effective-patterns/overview">
    Explore agent workflow patterns
  </Card>

  <Card title="MCP Protocol" icon="plug" href="/mcp-agent-sdk/mcp/overview">
    Understand MCP capabilities
  </Card>

  <Card title="Advanced Topics" icon="rocket" href="/mcp-agent-sdk/advanced/durable-agents">
    Durable agents, observability, and more
  </Card>
</CardGroup>