MCP Agent SDK Overview

What is mcp-agent?

mcp-agent is a Python framework for building AI agents using the Model Context Protocol (MCP). 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. Each step maps directly to a core SDK concept:

1. Configure servers and models

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

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

2. Bootstrap the application

main.py

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

finder_agent.py

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

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

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.
Want OAuth-protected servers? Follow the OAuth basic agent walkthrough.
Ready for orchestration? Browse the workflow gallery and the Temporal projects.

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:

MCP Integration

Connect to any MCP server and automatically discover tools, resources, and prompts

Agent Layer

Agents that combine instructions with MCP server capabilities

LLM Integration

Augmented LLMs that can use tools and maintain conversation context

Workflow Patterns

Composable patterns for orchestrating agents and tasks

Key Components

MCPApp

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

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 →

Agents

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

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 →

AugmentedLLM

AugmentedLLMs are LLMs enhanced with tools from MCP servers:

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 Servers

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

mcp_agent.config.yaml

mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]

Learn more about MCP Servers →

Workflows

Workflows are composable patterns for orchestrating agents:

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 →

Execution Engines

Execution engines determine how workflows run:

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

mcp_agent.config.yaml

execution_engine: temporal  # or asyncio

Learn more about Execution Engines →

Workflow Patterns

mcp-agent implements all patterns from Anthropic’s Building Effective Agents:

Parallel

Fan-out tasks to multiple agents

Router

Intelligent request routing

Intent Classifier

Understand user intent

Planner

Plan and execute complex tasks

Deep Research

Adaptive planning with knowledge extraction

Evaluator-Optimizer

Iterative improvement with LLM-as-judge

Swarm

Multi-agent collaboration

Model Context Protocol

mcp-agent provides full support for MCP capabilities:

Tools

Execute functions and produce side effects

Resources

Access data and load context

Prompts

Reusable templates for interactions

Sampling

Request LLM completions from clients

Learn more about MCP Support →

Next Steps

Core Components

Learn about the building blocks

Effective Patterns

Explore agent workflow patterns

MCP Protocol

Understand MCP capabilities

Advanced Topics

Durable agents, observability, and more

​What is mcp-agent?

​Anatomy of an MCP Agent

​1. Configure servers and models

​2. Bootstrap the application

​3. Describe the agent

​4. Attach an augmented LLM

​5. Run inside the app context

​Core Architecture

MCP Integration

Agent Layer

LLM Integration

Workflow Patterns

​Key Components

​MCPApp

​Agents

​AugmentedLLM

​MCP Servers

​Workflows

​Execution Engines

​Workflow Patterns

Parallel

Router

Intent Classifier

Planner

Deep Research

Evaluator-Optimizer

Swarm

​Model Context Protocol

Tools

Resources

Prompts

Sampling

​Next Steps

Core Components

Effective Patterns

MCP Protocol

Advanced Topics

What is mcp-agent?

Anatomy of an MCP Agent

1. Configure servers and models

2. Bootstrap the application

3. Describe the agent

4. Attach an augmented LLM

5. Run inside the app context

Core Architecture

Key Components

MCPApp

Agents

AugmentedLLM

MCP Servers

Workflows

Execution Engines

Workflow Patterns

Model Context Protocol

Next Steps