# https://github.com/lastmile-ai/mcp-agent Project Manual

Generated at: 2026-07-21 22:17:47 UTC

## Table of Contents

- [Introduction and System Architecture](#page-1)
- [Core Components: MCPApp, Agents, and Augmented LLMs](#page-2)
- [Workflow Patterns and MCP Server Integration](#page-3)
- [Production Features: Temporal, Cloud, OAuth, and Observability](#page-4)

<a id='page-1'></a>

## Introduction and System Architecture

### Related Pages

Related topics: [Core Components: MCPApp, Agents, and Augmented LLMs](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/lastmile-ai/mcp-agent/blob/main/README.md)
- [pyproject.toml](https://github.com/lastmile-ai/mcp-agent/blob/main/pyproject.toml)
- [src/mcp_agent/app.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/app.py)
- [src/mcp_agent/__init__.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/__init__.py)
- [src/mcp_agent/core/context.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/core/context.py)
- [src/mcp_agent/config.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/config.py)
</details>

# Introduction and System Architecture

## Purpose and Scope

`mcp-agent` is a Python framework for building effective agents using the **Model Context Protocol (MCP)**. It positions MCP servers as the primary integration surface for tools and context, and composes them with **Augmented LLMs** and **workflow primitives** to deliver production-ready agentic applications. Source: [README.md:1-30]()

The framework targets three audiences:

- Application developers who want a Pythonic, decorator-based API to author agents.
- Platform engineers who need durable, observable, and configurable execution (Temporal-backed durability and structured logging are highlighted by the community). Source: [#641](https://github.com/lastmile-ai/mcp-agent/issues/641)
- LLM integrators who require pluggable model providers — OpenAI, Anthropic, Azure, AWS Bedrock, Google Gemini, and Ollama are supported, with LMStudio requested by the community. Source: [v0.0.15](https://github.com/lastmile-ai/mcp-agent/releases/tag/v0.0.15), [#596](https://github.com/lastmile-ai/mcp-agent/issues/596)

The latest tracked release is **v0.0.21**, which keeps the project compatible with MCP package v1.8.0 and adds `OllamaAugmentedLLM`. Source: [v0.0.21](https://github.com/lastmile-ai/mcp-agent/releases/tag/v0.0.21)

## High-Level Architecture

The system is organized as layered modules under the `mcp_agent` package, exposed through `MCPApp` and `Context` as the two foundational handles a developer interacts with. Source: [src/mcp_agent/__init__.py:1-40]()

```
src/mcp_agent/
├── app.py              # MCPApp entry point and lifecycle
├── config.py           # Settings, server registry, execution config
├── core/
│   └── context.py      # Per-request Context (servers, LLM, logger)
├── agents/             # Agent definitions (basic, decorator, yaml)
├── workflows/          # parallel, sequential, orchestrator-workers, router
├── augmented_llm/      # Provider adapters (OpenAI, Anthropic, Bedrock, …)
└── mcp/                # MCP client/server wiring
```

The runtime model is:

1. An `MCPApp` is instantiated and configured via `mcp_agent.config` settings. Source: [src/mcp_agent/app.py:1-80]()
2. A `Context` is bound to the app, exposing MCP server connections, an `AugmentedLLM`, the logger, and the human input callback. Source: [src/mcp_agent/core/context.py:1-120]()
3. Agents request tools from connected MCP servers through the `Context`, while an `AugmentedLLM` consumes those tools to satisfy a user request. Source: [src/mcp_agent/core/context.py:80-160]()
4. Multi-agent workflows compose agents using explicit patterns declared in `workflows/`. Source: [README.md:60-120]()

## Core Components

### MCPApp and Lifecycle

`MCPApp` is the top-level container that owns configuration, session state, and the lifecycle of all attached resources. A `session_id` is propagated through the system so logs and Temporal workflows can be correlated. Source: [v0.0.10](https://github.com/lastmile-ai/mcp-agent/releases/tag/v0.0.10), [src/mcp_agent/app.py:40-120]()

### Context

`Context` is the per-execution handle. It carries references to:

- The connected MCP server registry and tool catalog.
- The active `AugmentedLLM` for the current request.
- The structured logger and event recorder.
- Hooks for human input and telemetry.

Because it is request-scoped, it is the unit passed into agents and workflows rather than shared mutable globals. Source: [src/mcp_agent/core/context.py:40-160]()

### Configuration

`mcp_agent.config` defines how MCP servers are discovered (stdio, SSE, WebSocket transports with configurable headers are supported since v0.0.16), which model providers are enabled, and which execution engine runs the workflow (local in-process by default, Temporal for durability). Source: [src/mcp_agent/config.py:1-200](), [v0.0.16](https://github.com/lastmile-ai/mcp-agent/releases/tag/v0.0.16)

### Augmented LLMs

`AugmentedLLM` adapters wrap each provider and expose a uniform `generate` / `structured` interface. They enumerate tools from MCP servers through the `Context` and bind them into the model call, so tool execution is mediated by MCP. The provider list is pluggable: OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Google Gemini, and Ollama. Source: [v0.0.15](https://github.com/lastmile-ai/mcp-agent/releases/tag/v0.0.15), [v0.0.21](https://github.com/lastmile-ai/mcp-agent/releases/tag/v0.0.21)

### Workflow Primitives

The workflow layer ships first-class patterns: `parallel`, `sequential`, `orchestrator-workers`, and `router`. Each pattern is a thin orchestration over agents with deterministic control flow. The community has flagged missing patterns — notably an **adversarial / debate** primitive where two agents argue opposing positions — and **trust verification** for MCP servers before orchestration, both of which are gaps in the current architecture. Source: [#668](https://github.com/lastmile-ai/mcp-agent/issues/668), [#693](https://github.com/lastmile-ai/mcp-agent/issues/693)

## Data and Control Flow

```mermaid
flowchart TD
    User --> App[MCPApp]
    App --> Ctx[Context]
    Ctx --> Srv[(MCP Servers<br/>stdio / SSE / WS)]
    Ctx --> LLM[AugmentedLLM<br/>OpenAI / Anthropic / Bedrock / Gemini / Ollama]
    Ctx --> WF[Workflow<br/>parallel / sequential / orchestrator-workers / router]
    WF --> Agents
    Agents --> Ctx
    LLM --> Ctx
    Ctx --> User
```

A user request enters `MCPApp`, which materializes a `Context`. The `Context` discovers tools from the configured MCP servers and exposes them to the `AugmentedLLM`. The active workflow drives one or more agents, each of which performs tool calls through the same `Context`. Results return to the user, while the structured logger records every step for observability and replay. Source: [src/mcp_agent/core/context.py:40-200](), [src/mcp_agent/app.py:40-160]()

## Reliability, Extensibility, and Community Notes

Reliability is a recurring theme: community members ask about idempotency, evaluator-optimizer stop conditions, and replay/recovery after partial failure — capabilities that align with the Temporal-backed execution engine. Source: [#640](https://github.com/lastmile-ai/mcp-agent/issues/640) Streaming support is on the roadmap but not yet shipped; questions distinguish between token-level streaming and workflow-progress streaming. Source: [#307](https://github.com/lastmile-ai/mcp-agent/issues/307) The project is also used as the agent core for downstream platforms such as ApeRAG, indicating the architecture supports embedding in larger systems. Source: [#426](https://github.com/lastmile-ai/mcp-agent/issues/426)

Extension points are intentionally narrow: add a new MCP server via `config.py`, add a new model by subclassing `AugmentedLLM`, and add a new composition by writing a workflow module. This bounded surface is what makes `mcp-agent` both approachable for new contributors and durable enough for production deployments.

---

<a id='page-2'></a>

## Core Components: MCPApp, Agents, and Augmented LLMs

### Related Pages

Related topics: [Introduction and System Architecture](#page-1), [Workflow Patterns and MCP Server Integration](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/mcp_agent/app.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/app.py)
- [src/mcp_agent/agents/agent.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/agents/agent.py)
- [src/mcp_agent/agents/agent_spec.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/agents/agent_spec.py)
- [src/mcp_agent/workflows/llm/augmented_llm.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/llm/augmented_llm.py)
- [src/mcp_agent/workflows/llm/augmented_llm_openai.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/llm/augmented_llm_openai.py)
- [src/mcp_agent/workflows/llm/augmented_llm_anthropic.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/llm/augmented_llm_anthropic.py)
- [src/mcp_agent/config.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/config.py)
</details>

# Core Components: MCPApp, Agents, and Augmented LLMs

This page documents the three foundational abstractions that every `mcp-agent` workflow builds on: `MCPApp`, `Agent`, and `AugmentedLLM`. Together they form the layered stack shown below.

```mermaid
flowchart TB
    User[User Code] --> App[MCPApp]
    App --> Cfg[Settings / Config]
    App --> Logger[Logger / Telemetry]
    App --> Agent[Agent]
    Agent --> MCPServers[Connected MCP Servers]
    Agent --> LLM[AugmentedLLM]
    LLM --> Provider[OpenAI / Anthropic / Bedrock / Azure / Gemini / Ollama]
    LLM --> Tools[Tool selection + execution loop]
```

## MCPApp — Application Lifecycle and Configuration Root

`MCPApp` is the top-level container that all user code instantiates. It owns the application-wide `Settings` object, the structured logger, the optional telemetry/exporter pipeline, and a registry of named MCP server configurations (`server_registry`). Every `Agent` is constructed against an `MCPApp`, which means configuration and observability are injected consistently across an entire program.

The class is defined in `src/mcp_agent/app.py` and is normally used either as a context manager or through the `@app.tool` / `@app.async_tool` decorators exposed by its submodules. Its responsibilities include:

- Loading YAML/JSON configuration via `get_settings()` and exposing it through `app.config`. Source: [src/mcp_agent/app.py:1-120]()
- Initializing the `logger` and any configured `exporter` for tracing. Source: [src/mcp_agent/app.py:120-260]()
- Tracking a `session_id` that is propagated to every child component (introduced in v0.0.10). Source: [src/mcp_agent/config.py:1-80]()
- Acting as the parent for `Agent` instances, so cleanup of MCP transports happens at app shutdown.

In practice, user code typically looks like:

```python
app = MCPApp(name="research_agent")

@app.tool
async def summarize(url: str) -> str:
    agent = Agent(name="summarizer", instruction="...", server_names=["fetch"])
    async with agent:
        llm = await agent.attach_llm(anthropic.AugmentedLLM)
        return await llm.generate_str(f"Summarize {url}")
```

## Agent — MCP-Bound Executor

An `Agent` is the bridge between MCP servers and an LLM. It owns the long-lived MCP `ClientSession`s, exposes server tools to the LLM layer, and tracks conversation memory through an attached `AugmentedLLM`.

The `Agent` class in `src/mcp_agent/agents/agent.py` exposes the key entry points:

- `attach_llm(llm_factory)` — creates and remembers a provider-specific `AugmentedLLM`, returning it so the caller can drive `generate_str`, `generate_structured`, or `generate` calls. Source: [src/mcp_agent/agents/agent.py:1-180]()
- `list_tools()` — enumerates the tool surface across all attached servers, including server-name prefixes used in tool calls (relevant to the server-name parsing fix from v0.0.10). Source: [src/mcp_agent/agents/agent.py:180-260]()
- Async context manager (`__aenter__` / `__aexit__`) that opens and closes the MCP transports deterministically.

An agent's static description lives in `AgentSpec` (`src/mcp_agent/agents/agent_spec.py`), which captures the agent's `name`, `instruction`, optional `description`, and the `server_names` it should connect to. This separation lets workflows serialize agent definitions (e.g. via YAML) without instantiating them.

## AugmentedLLM — LLM With Tool Calling and Memory

`AugmentedLLM` is the abstract base class in `src/mcp_agent/workflows/llm/augmented_llm.py` that turns a plain chat model into an MCP-aware one. It implements:

- A message-history list `self.history` that accumulates turns across `generate_str` / `generate_structured` calls.
- The `generate` and `generate_structured` methods, which loop: call the provider, parse tool-call requests, dispatch them through the agent's MCP servers, append tool results, and re-call the model until a final answer is produced. Source: [src/mcp_agent/workflows/llm/augmented_llm.py:1-200]()
- Provider-agnostic typed-output handling via `instructor`, returning either plain text or Pydantic models (introduced/expanded in v0.0.11 with the `instructor` 1.7.7 bump). Source: [src/mcp_agent/workflows/llm/augmented_llm.py:200-360]()

The `__call__` and `pre_call`/`post_call` hooks are how downstream workflows (Router, Orchestrator, Evaluator-Optimizer) intercept and steer behavior — relevant to the reliability and orchestration discussions in the community (e.g. #640 reliability patterns, #668 adversarial workflows).

### Provider Implementations

Each provider subclass implements provider-specific request/response shapes:

| Provider class | File | Highlights |
|---|---|---|
| `OpenAIAugmentedLLM` | `augmented_llm_openai.py` | Default chat-completions endpoint; supports custom `http_client` (v0.0.18) and `o4` reasoning models (v0.0.16). |
| `AnthropicAugmentedLLM` | `augmented_llm_anthropic.py` | Maps MCP tools to Anthropic's `tools` schema; supports streaming token output (roadmap item #307). |
| `BedrockAugmentedLLM`, `AzureAugmentedLLM`, `GeminiAugmentedLLM`, `OllamaAugmentedLLM` | sibling files | Added across v0.0.15 and v0.0.21 to address cloud/local vendor support (#40, #596). |

All providers share the same public surface (`generate_str`, `generate_structured`, `history`), which is what makes the higher-level workflow patterns composable.

## Putting It Together

The typical call chain for a single turn is:

1. `MCPApp` loads config and creates the logger / session id.
2. `Agent(server_names=...)` resolves the configured MCP servers and opens sessions.
3. `agent.attach_llm(OpenAIAugmentedLLM)` constructs the provider subclass, inheriting the agent's tool list.
4. `await llm.generate_str(prompt)` runs the tool-calling loop: provider → tool dispatch via agent → tool result → final answer.
5. On exit, the agent closes MCP sessions and the app flushes telemetry.

This same stack is what workflow primitives (Parallel, Sequential, Orchestrator, Router) reuse, and it is the layer that future features requested in the community — streaming token output (#307), adversarial patterns (#668), and pre-call MCP trust verification (#693) — would extend without changing the core abstractions.

---

<a id='page-3'></a>

## Workflow Patterns and MCP Server Integration

### Related Pages

Related topics: [Core Components: MCPApp, Agents, and Augmented LLMs](#page-2), [Production Features: Temporal, Cloud, OAuth, and Observability](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/mcp_agent/workflows/factory.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/factory.py)
- [src/mcp_agent/workflows/parallel/parallel_llm.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/parallel/parallel_llm.py)
- [src/mcp_agent/workflows/router/router_llm.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/router/router_llm.py)
- [src/mcp_agent/workflows/orchestrator/orchestrator.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/orchestrator/orchestrator.py)
- [src/mcp_agent/workflows/evaluator_optimizer/evaluator_optimizer.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/evaluator_optimizer/evaluator_optimizer.py)
- [src/mcp_agent/workflows/swarm/swarm.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/swarm/swarm.py)
</details>

# Workflow Patterns and MCP Server Integration

## Overview

mcp-agent exposes a small, composable set of multi-agent workflow patterns built on top of the Model Context Protocol (MCP). Each pattern is implemented as a `Workflow` subclass and registered through a central factory so that authors can declare them via Python decorators, YAML configuration, or the `MCPApp` API and obtain deterministic, inspectable execution across one or more MCP servers.

Source: [src/mcp_agent/workflows/factory.py:1-120]()

The factory is the single registration point that maps human-readable workflow names (e.g. `parallel`, `router`, `orchestrator`, `evaluator-optimizer`, `swarm`) to their concrete classes. This indirection is what allows the same workflow to be invoked identically whether the user authors it in code or in YAML, and it is the seam that production users attach logging, Temporal-backed durability, and structured tracing to.

Source: [src/mcp_agent/workflows/factory.py:30-90]()

## Core Workflow Patterns

### Parallel

`ParallelLLMWorkflow` fans a single prompt out to multiple agents concurrently and aggregates their results. It is the recommended pattern when independent perspectives, multiple tool sets, or several MCP servers need to operate on the same input without ordering constraints. Aggregation is delegated to an LLM that synthesizes the per-agent outputs into a final answer.

Source: [src/mcp_agent/workflows/parallel/parallel_llm.py:1-80]()

### Router

`RouterWorkflow` classifies the incoming request and dispatches it to one specialized agent. Each routing target typically owns its own MCP server configuration, which makes this pattern well suited for triaging among servers that expose distinct tool surfaces (e.g. filesystem vs. git vs. web fetch).

Source: [src/mcp_agent/workflows/router/router_llm.py:1-80]()

### Orchestrator-Workers

`OrchestratorWorkflow` lets a planner agent dynamically allocate subtasks to worker agents and synthesize their results. It is the canonical choice for long-horizon plans that mix several MCP tool sets and require intermediate state, such as the showcase GraphRAG platform discussed in community issue #426.

Source: [src/mcp_agent/workflows/orchestrator/orchestrator.py:1-80]()

### Evaluator-Optimizer

This pattern loops a producer and an evaluator until a quality threshold is reached or a maximum iteration count is hit. It directly addresses the stop-condition and reliability concerns raised in community issue #640 and is the standard way to layer idempotency-aware retries on top of any other workflow.

Source: [src/mcp_agent/workflows/evaluator_optimizer/evaluator_optimizer.py:1-80]()

### Swarm

`SwarmWorkflow` enables fluid peer-to-peer handoff between agents rather than a fixed topology. Each agent decides whether to answer, call a tool, or hand off, which suits exploratory or emergent cooperation scenarios where the right MCP server for the next step is data-dependent.

Source: [src/mcp_agent/workflows/swarm/swarm.py:1-80]()

## Pattern Selection

| Pattern | Topology | Best For | MCP Server Fan-out |
|---|---|---|---|
| Parallel | Many → Aggregate | Diverse viewpoints, ensemble answers | High |
| Router | 1 → 1 | Triage, specialization | Medium |
| Orchestrator | 1 → Many | Multi-step plans, stateful tasks | High |
| Evaluator-Optimizer | Producer ↔ Evaluator loop | Quality refinement, retries | Low–Medium |
| Swarm | Peer handoff | Emergent cooperation | Variable |

Most production deployments start with `Router` or `Parallel` and graduate to `Orchestrator` when subtasks become stateful or cross server boundaries. `Evaluator-Optimizer` is layered on top whenever the orchestrator's output must meet a measurable rubric, and `Swarm` is reserved for the cases where rigid topology becomes a bottleneck.

## Integration with MCP Servers

Workflows are MCP-server agnostic: every agent inside a workflow attaches to one or more MCP servers via the standard `MCPApp` lifecycle, so the same pattern can mix tools from filesystem, git, web-fetch, and custom servers such as the community-suggested `cowork-to-code-bridge` (issue #706, async escalation) or `TheCrawler` (issue #692, structured web extraction). Server names are propagated through tool calls so that downstream agents can disambiguate results regardless of which server produced them.

Community issue #693 has called for pre-call trust verification of MCP servers before orchestration. As of the latest release (v0.0.21) the integration layer relies on transport-level authentication and the orchestrator's own policy rather than a built-in attestation step, so users who need stronger guarantees currently compose a `Router` or custom evaluator agent in front of the workflow.

Cross-org delegation (issue #673) and adversarial/debate patterns (issue #668) are not yet first-class workflows; today they are typically composed manually by combining `RouterWorkflow` or `OrchestratorWorkflow` with custom evaluator agents that take opposing positions. Streaming token output (issue #307) is also on the roadmap and is expected to be exposed at the workflow boundary, not at the individual agent level.

---

<a id='page-4'></a>

## Production Features: Temporal, Cloud, OAuth, and Observability

### Related Pages

Related topics: [Workflow Patterns and MCP Server Integration](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/mcp_agent/app.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/app.py)
- [src/mcp_agent/executor/workflow.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/executor/workflow.py)
- [src/mcp_agent/executor/temporal/temporal_context.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/executor/temporal/temporal_context.py)
- [src/mcp_agent/cli/cloud/main.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/cli/cloud/main.py)
- [src/mcp_agent/cli/cloud/commands/deploy/main.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/cli/cloud/commands/deploy/main.py)
- [src/mcp_agent/oauth/flow.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/oauth/flow.py)
- [src/mcp_agent/oauth/manager.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/oauth/manager.py)
- [src/mcp_agent/logging/logger.py](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/logging/logger.py)
</details>

# Production Features: Temporal, Cloud, OAuth, and Observability

## Purpose and Scope

`mcp-agent` ships with a set of capabilities that move the framework beyond prototype use into deployable, durable, and observable production systems. These capabilities are organized around four concerns:

- **Durable execution** via a Temporal-backed workflow executor so long-running agent runs survive process restarts and partial failures.
- **Cloud deployment** through a dedicated CLI surface (`mcp-agent deploy ...`) for shipping agents to managed infrastructure.
- **OAuth integration** for MCP servers that require delegated authorization, handled through a local callback flow and a reusable manager.
- **Observability** via structured logging that propagates a `session_id` and correlates activity across MCP servers, LLM calls, and workflow steps.

Together these features let a single `@app.workflow` definition move from a local script to a resumable, authenticated, remotely observable service without rewriting orchestration logic. Source: [src/mcp_agent/app.py:1-120]().

## Temporal-Backed Durable Execution

The executor layer abstracts whether an agent runs in-process or under Temporal. A workflow definition written with the decorator-based API is compiled once and dispatched through `Workflow` instances whose execution context is selected at runtime. The local default uses an in-memory `Workflow`, while the Temporal variant is wired through `TemporalContext`, which constructs a Temporal client and reuses the same workflow classes as activities. Source: [src/mcp_agent/executor/workflow.py:1-80](), [src/mcp_agent/executor/temporal/temporal_context.py:1-120]().

This split matters because reliability patterns asked about in the community — idempotency, replay, and partial-failure recovery (issue #640) — depend on having a deterministic activity boundary. Each MCP tool call, augmented-LLM call, and workflow node becomes an idempotent activity whose state is persisted by the Temporal service. When a worker crashes mid-run, the next worker resumes from the last completed activity rather than restarting the agent from scratch. The `feature/temporal_prime` branch referenced in the v0.0.18 release notes is the active line of work for hardening this path. Source: [src/mcp_agent/executor/temporal/temporal_context.py:80-200]().

For users who do not need durability, the in-memory executor remains the default, so adding Temporal is an opt-in configuration change rather than a code rewrite.

## Cloud Deployment

Deployment is exposed as a first-class CLI command under `mcp-agent cloud`. The entry point wires Click subcommands and is structured so that future operations (logs, status, destroy) compose onto the same authenticated client. Source: [src/mcp_agent/cli/cloud/main.py:1-80]().

The `deploy` subcommand packages the local project, uploads workflows and MCP server definitions, and provisions them on the managed runtime. It validates that the `mcp_agent.config.yaml` resolves, that required secrets are present, and that the targeted workflow references real `@app.workflow` symbols before the upload. Source: [src/mcp_agent/cli/cloud/commands/deploy/main.py:1-160]().

Because orchestration, durable execution, and observability are already decoupled from transport, the same workflow definition that runs locally with the in-memory executor runs on the cloud runtime with the Temporal executor — no `if production` branches are needed in agent code.

## OAuth for MCP Servers

MCP servers that require delegated authorization are handled by an OAuth flow module that runs locally during MCP server startup. The flow issues the authorization URL, listens on a loopback port for the redirect, exchanges the callback code for a token, and stores credentials through a pluggable `TokenStorage` interface. Source: [src/mcp_agent/oauth/flow.py:1-200]().

A `OAuthManager` wraps the flow and is exposed on the application context so any MCP server connection can request credentials on demand. The manager handles token refresh, scopes the credentials per server, and prevents duplicate concurrent flows for the same server. This keeps the agent code free of OAuth boilerplate and lets the framework own the redirect-handling lifecycle. Source: [src/mcp_agent/oauth/manager.py:1-150]().

The same manager is reused by both the in-memory and Temporal executors, so a cloud-deployed workflow that touches an OAuth-protected MCP server performs the authorization handshake once and replays the cached token across activity retries.

## Observability and Structured Logging

Production runs need correlated logs across MCP servers, LLM calls, and workflow steps. `mcp-agent` provides a structured logger that assigns a `session_id` at `MCPApp` construction and propagates it through every logger, so a single grep yields the full trace of one user invocation. Source: [src/mcp_agent/logging/logger.py:1-180]().

The logger emits JSON-shaped records with consistent keys (event, server, tool, duration, status), which makes it straightforward to ship into any log aggregator. Because Temporal activities already emit start/end events, the same records can be joined by `session_id` to produce a per-workflow timeline even when activities replay on different workers. The community has also requested enhancements such as pre-call trust verification for MCP servers (issue #693) and agent identity for cross-org delegation (issue #673); both are designed to layer onto the existing logger and session context rather than introduce a parallel telemetry stack. Source: [src/mcp_agent/app.py:60-160]().

## How the Pieces Fit

| Concern | Mechanism | Where it lives |
|---|---|---|
| Durable execution | Temporal activity boundary | `executor/temporal/temporal_context.py` |
| Local execution | In-memory workflow executor | `executor/workflow.py` |
| Cloud runtime | `mcp-agent cloud deploy` CLI | `cli/cloud/commands/deploy/main.py` |
| Authorization | Loopback OAuth flow + token store | `oauth/flow.py`, `oauth/manager.py` |
| Observability | Structured JSON logger with `session_id` | `logging/logger.py` |

The shared `MCPApp` context is what binds these together: it owns the executor selection, exposes the OAuth manager, and seeds the logger's `session_id`, so a workflow declared once with `@app.workflow` runs identically across local, durable, and cloud modes.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: lastmile-ai/mcp-agent

Summary: Found 21 structured pitfall item(s), including 4 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.

## 1. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/673

## 2. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/668

## 3. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/721

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/713

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/692

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/655

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/658

## 8. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/693

## 9. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/670

## 10. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/671

## 11. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a capability evidence risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/640

## 12. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/lastmile-ai/mcp-agent

## 13. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/lastmile-ai/mcp-agent

## 14. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/lastmile-ai/mcp-agent

## 15. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/lastmile-ai/mcp-agent

## 16. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/706

## 17. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/669

## 18. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/641

## 19. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/lastmile-ai/mcp-agent/issues/667

## 20. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/lastmile-ai/mcp-agent

## 21. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/lastmile-ai/mcp-agent

<!-- canonical_name: lastmile-ai/mcp-agent; human_manual_source: deepwiki_human_wiki -->