# Deployment Auth
Source: https://docs.mcp-agent.com/cloud/authentication/deployment-auth

Configure authentication for deployed MCP servers

Every deployment needs an explicit stance on who can call its tools. This page covers the options supported today and what’s coming next.

## 1. Bearer token authentication (default)

* Each user runs `mcp-agent login` to obtain an API key (`lm_mcp_api_*`).
* Keys are stored locally (`~/.config/mcp-agent/credentials.json`) and can also be provided via the `MCP_API_KEY` environment variable (CI, containers).
* Clients include the key in the `Authorization: Bearer <token>` header.
* Deployments validate the token before executing requests.

### Share instructions with users

```
1. Install mcp-agent (uv tool install mcp-agent)
2. Run mcp-agent login and follow the browser prompts
3. Configure the client (mcp-agent install ... --client claude_desktop)
```

### Rotate or revoke

* Re-run `mcp-agent login` to issue a new key (old keys will stop working).
* Delete the key file to force re-authentication.
* Per-user revocation UI is on the roadmap; in the interim contact support if a key is compromised.

### CLI recap

```bash  theme={null}
mcp-agent login                # browser flow
mcp-agent cloud auth whoami    # confirm identity
mcp-agent install <url> --client cursor  # writes config with Authorization header
```

## 2. Unauthenticated access (`--no-auth`)

Use this mode for public servers, demos, or ChatGPT Apps (which cannot provide custom headers).

```bash  theme={null}
mcp-agent deploy blog-tools --no-auth
```

* Anyone with the server URL can call it.
* Logs still capture caller metadata (IP, user agent) for monitoring.
* You can re-enable auth later:

  ```bash  theme={null}
  mcp-agent deploy blog-tools --auth
  ```

  (`--auth` toggles `unauthenticatedAccess` back to false.)

> For apps deployed without auth, consider rate limiting or requiring custom user-provided secrets to avoid abuse.

## 3. OAuth 2.1 (coming soon, preview)

The upcoming release implements the MCP OAuth specification across three surfaces:

1. **Authorization server** (control plane)
   * Metadata endpoint: `/.well-known/oauth-authorization-server`
   * Supports Google + GitHub providers initially
   * Issues access & refresh tokens
2. **Resource server** (your deployment)
   * Implements `/.well-known/oauth-protected-resource` (RFC 9728)
   * Validates JWTs or proxies to token introspection
   * Allows per-scope access control (e.g., `read`, `write`, `admin`)
3. **Client tooling**
   * `mcp-agent install` and `mcp-agent cloud configure` will drive the auth flow for supported clients (browser-based loopback or device code).

Keep an eye on release notes for timelines. The migration will be additive—existing bearer-token flows continue to work.

## 4. Combining with secrets management

* Store long-lived service credentials in `mcp_agent.secrets.yaml` as deployment secrets; the runtime injects them securely.
* Ask end-users for their own credentials via `mcp-agent cloud configure` (user secrets). You can enforce domain restrictions or other policies in code when processing those secrets.

## 5. Security best practices

<AccordionGroup>
  <Accordion title="Least privilege">
    Only expose tools/resources that need to be public. For internal deployments, keep `--auth` enabled and share API keys via secure channels.
  </Accordion>

  <Accordion title="Audit logs">
    The platform records every API call (user, timestamp, tool, outcome). A user-facing audit surface is planned—ask the team if you need access before it ships.
  </Accordion>

  <Accordion title="Secret rotation">
    Rotate provider API keys regularly. Redeploy with updated secrets; the CLI invalidates old handles automatically.
  </Accordion>

  <Accordion title="Client distribution">
    Provide install scripts (`mcp-agent install`) rather than asking users to edit config files manually. This reduces the risk of misconfigured auth headers.
  </Accordion>
</AccordionGroup>

## References

* [Authentication overview →](/cloud/authentication/overview)
* [External MCP server auth (downstream credentials) →](/cloud/authentication/external-mcp-auth)
* [Secrets management →](/cloud/mcp-agent-cloud/manage-secrets)


# External MCP Auth
Source: https://docs.mcp-agent.com/cloud/authentication/external-mcp-auth

Configure your agent to authenticate when calling downstream MCP servers

Many agents call other MCP servers (e.g., Linear, GitHub, Slack). Each downstream server may require API keys or OAuth credentials. Use `mcp_agent.config.yaml` to specify how your agent should authenticate when acting as an MCP client.

## API key (static) authentication

```yaml mcp_agent.config.yaml theme={null}
mcp:
  servers:
    github:
      command: "uvx"
      args: ["mcp-server-github"]
      auth:
        api_key: "${GITHUB_TOKEN}"    # injected from secrets
```

* Store the actual token in `mcp_agent.secrets.yaml` (deployment secret) or `mcp_agent.configured.secrets.yaml` (user secret).
* At runtime, `ServerRegistry` injects the `Authorization` header when connecting to the MCP server.
* Supports any header name via `auth.headers` if the server expects a custom format.

## OAuth client credentials / authorization code

For MCP servers that implement OAuth (Linear, Notion, custom internal IdPs), configure the `oauth` block:

```yaml  theme={null}
mcp:
  servers:
    notion:
      command: "uvx"
      args: ["mcp-server-notion"]
      auth:
        oauth:
          enabled: true
          authorization_server: "https://auth.notion.com"
          client_id: "${NOTION_CLIENT_ID}"
          client_secret: "${NOTION_CLIENT_SECRET}"
          scopes: ["documents.read", "documents.write"]
          resource: "https://mcp.notion.com"
          redirect_uri_options:
            - "http://127.0.0.1:33418/callback"
            - "https://<app_id>.deployments.mcp-agent.com/oauth/callback"
```

How it works:

1. When the agent first needs the server, the OAuth manager checks the token store.
2. If no token exists, it launches an authorization flow (internal callback inside the deployment or local loopback while running locally).
3. Access + refresh tokens are stored in the configured token store (memory or Redis).
4. Tokens are refreshed automatically before expiry (`refresh_leeway_seconds`).

### Token store configuration

```yaml  theme={null}
oauth:
  token_store:
    backend: "redis"
    redis_url: "${REDIS_URL}"
    redis_prefix: "mcp_agent:oauth_tokens"
```

* `memory` (default) – in-memory, process-scoped. Great for development but not shared across workers.
* `redis` – recommended for cloud deployments if your app uses multiple processes or needs persistence across restarts.

## Seeding tokens manually

If you already have an access token:

```yaml  theme={null}
mcp:
  servers:
    linear:
      auth:
        oauth:
          enabled: true
          access_token: "${LINEAR_ACCESS_TOKEN}"
          refresh_token: "${LINEAR_REFRESH_TOKEN}"
          expires_at: 1740694445
```

This bypasses the interactive flow; the token manager will refresh using the provided refresh token when needed.

## Request-time headers

For bespoke auth schemes, you can specify arbitrary headers or environment variables:

```yaml  theme={null}
mcp:
  servers:
    internal_search:
      command: "./bin/internal-search"
      env:
        SEARCH_API_KEY: "${SEARCH_API_KEY}"
      auth:
        headers:
          X-Org: "lastmile"
          Authorization: "Bearer ${SEARCH_API_KEY}"
```

## Best practices

<AccordionGroup>
  <Accordion title="Keep secrets out of code">
    Always reference `${ENV_VAR}` placeholders in config and store the actual values in secrets files. Never hardcode tokens in Python modules.
  </Accordion>

  <Accordion title="Differentiate developer vs user secrets">
    If every user needs their own credential (e.g., personal GitHub PAT), mark it as `!user_secret` so `mcp-agent cloud configure` collects it when they onboard the app.
  </Accordion>

  <Accordion title="Token sharing">
    For OAuth-protected upstream servers you probably want a shared token cache (Redis) to avoid re-authorizing for every workflow run.
  </Accordion>

  <Accordion title="Handle scope failures">
    Downstream servers may reject requests if scopes are missing. Log the response body and expose a clear error so users know to re-run the configure flow.
  </Accordion>
</AccordionGroup>

## Related docs

* [Secrets management →](/cloud/mcp-agent-cloud/manage-secrets)
* [Authentication overview →](/cloud/authentication/overview)
* [MCP server configuration reference →](/reference/configuration#mcp-servers)


# Authentication Overview
Source: https://docs.mcp-agent.com/cloud/authentication/overview

Authentication architecture for mcp-agent cloud deployments

mcp-agent cloud supports multiple authentication modes so you can choose the right balance between security and accessibility. This page introduces the architecture and flows; the detailed configuration lives in the sub-pages.

## Components

| Component                             | Role                                                                                                                               |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Authorization server**              | Issues API keys today; OAuth 2.1 support (authorization code flow) is in development. Hosted in LastMile’s control plane.          |
| **Resource server (your deployment)** | Exposes MCP endpoints (`call_tool`, `read_resource`, etc.) and validates tokens. Powered by FastMCP + `MCPApp`.                    |
| **Clients**                           | MCP clients (Claude Desktop, Cursor, ChatGPT Apps), custom code (Python, cURL), or other MCP servers calling downstream resources. |
| **Secrets service**                   | Stores deployment/user secrets, eliminating the need to embed credentials in clients.                                              |

<img src="https://github.com/user-attachments/assets/80d63b71-d9ba-46a0-b2a6-8ccf1bfb6296" alt="Agents exposed as MCP servers, sitting between MCP clients and downstream MCP servers" width="593" height="406" />

## Modes at a glance

| Mode                       | Use case                                                   | How                                                                                                    | Docs                                                           |
| -------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| **Bearer token** (default) | Internal deployments, quick sharing within a team          | `mcp-agent login` → provides `MCP_API_KEY`. Clients send `Authorization: Bearer`.                      | [Deployment auth →](/cloud/authentication/deployment-auth)     |
| **Unauthenticated**        | Public endpoints, ChatGPT Apps                             | Deploy with `mcp-agent deploy ... --no-auth`.                                                          | [Deployment auth →](/cloud/authentication/deployment-auth)     |
| **OAuth 2.1 (Upcoming)**   | Enterprise SSO, fine-grained scopes                        | Follows MCP OAuth spec (RFC 9728 + RFC 8414).                                                          | (Coming soon)                                                  |
| **External MCP auth**      | Your agent needs to authenticate to downstream MCP servers | Configure `mcp_agent.config.yaml -> mcp.servers.<name>.auth` for API keys or OAuth client credentials. | [External MCP auth →](/cloud/authentication/external-mcp-auth) |

## Current flow (Bearer tokens)

1. Developer or user runs `mcp-agent login`.
2. Browser-based auth returns an API key (`lm_mcp_api_*`), stored locally.
3. CLI and MCP clients use the key in the `Authorization: Bearer` header.
4. Deployment validates the token before executing tools/workflows.

## Upcoming OAuth architecture

The forthcoming OAuth implementation follows the MCP Authorization specification:

* `/.well-known/oauth-authorization-server` metadata endpoint (RFC 8414).
* Authorization endpoint (`/oauth2/authorize`) supporting Google, GitHub, and custom IdPs.
* Token endpoint (`/oauth2/token`) returning access + refresh tokens.
* Resource server metadata (`/.well-known/oauth-protected-resource`) for deployments advertising supported methods (`bearer_methods_supported`, scopes).
* Token introspection and JWKS endpoints for JWT validation.

We aim to make the default configuration zero-touch for mcp-agent cloud deployments while still allowing you to point at other OAuth providers if you self-host.

## Choosing an authentication mode

* **Internal tools or staging** → keep bearer tokens (fastest path).
* **Publishing to ChatGPT Apps** → deploy with `--no-auth`, optionally combine with rate limiting in code.
* **Customer-facing apps** → use bearer tokens initially, migrate to OAuth when available to integrate with existing identity providers.
* **Agents calling other MCP servers** → configure outbound auth in `mcp_agent.config.yaml`. This is independent of how end-users authenticate to your deployment.

## Related guides

* [Configure deployment auth (bearer, unauthenticated, OAuth preview) →](/cloud/authentication/deployment-auth)
* [Authenticate to external MCP servers →](/cloud/authentication/external-mcp-auth)
* [Manage secrets →](/cloud/mcp-agent-cloud/manage-secrets)


# Cloud Quickstart
Source: https://docs.mcp-agent.com/cloud/deployment-quickstart

Deploy an MCP application to mcp-c in a couple of commands

<Info>
  **mcp-c** is in open beta. Share feedback via [GitHub](https://github.com/lastmile-ai/mcp-agent/issues) or [Discord](https://lmai.link/discord/mcp-agent).
</Info>

## TL;DR

```bash  theme={null}
uvx mcp-agent login
uvx mcp-agent deploy my-agent
uvx mcp-agent cloud servers describe my-agent
```

That is enough to put any MCP application—`mcp-agent` workflow, FastMCP server, or ChatGPT App backend—online. Deployments automatically run on the managed Temporal cluster; you do **not** need to configure Temporal hosts or queues yourself.

The sections below add a little context and point to deeper guides when you are ready.

## 1. Authenticate (one time)

```bash  theme={null}
uvx mcp-agent login
```

The CLI opens a browser window so you can sign in with GitHub or Google and generate an API key. Credentials are cached under `~/.mcp-agent/credentials.json`. In CI, set the `MCP_API_KEY` environment variable instead.

## 2. Confirm your project layout

Minimal structure:

```
my-agent/
├── main.py
├── mcp_agent.config.yaml
└── (optional) mcp_agent.secrets.yaml
```

`mcp_agent.config.yaml` just needs to describe your app. You can keep `execution_engine: temporal` if you already use it locally, but the cloud service will always launch your code on Temporal automatically.

Example:

```yaml mcp_agent.config.yaml theme={null}
name: web_summarizer
logger:
  transports: [console]

mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]

openai:
  default_model: gpt-4o
```

If your app needs API keys, place them in `mcp_agent.secrets.yaml` (details in [Manage secrets](/cloud/mcp-agent-cloud/manage-secrets)).

## 3. Deploy

```bash  theme={null}
uvx mcp-agent deploy web-summarizer
```

The CLI bundles the current directory, prompts you to classify secrets (deployment vs. user), uploads the bundle, and provisions the runtime. On success you will see something like:

```
✓ Deployed app ID: app_abc123xyz
   Server URL: https://app_abc123xyz.deployments.mcp-agent.com
   Status: ONLINE
```

Redeploy with the same name to ship updates. Useful flags:

* `--config-dir <path>` – deploy from another directory.
* `--non-interactive` – reuse stored secrets (CI/CD).
* `--dry-run` – validate without uploading.

## 4. Check status & logs

```bash  theme={null}
uvx mcp-agent cloud servers describe app_abc123xyz
uvx mcp-agent cloud logger tail app_abc123xyz --follow
```

`describe` prints the endpoint, auth mode, and worker status. `logger tail` streams application logs; add `--since 30m` or `--grep "ERROR"` as needed. All other operational commands are listed on the [cloud overview](/cloud/mcp-agent-cloud/overview).

## 5. Configure clients

Most deployments need per-user credentials. Prompt users (or your CI job) with:

```bash  theme={null}
uvx mcp-agent cloud configure --id https://app_abc123xyz.deployments.mcp-agent.com
```

Then install the server into your favourite MCP client:

* **Claude Desktop / Cursor / VS Code / ChatGPT** – `uvx mcp-agent install --client <client> https://app_abc123xyz.deployments.mcp-agent.com/sse`
* **ChatGPT Apps** – deploy with `--no-auth` and register the SSE endpoint in the Apps dashboard.
* **Python** – add the server endpoint to your MCP client config ([see guide](/cloud/mcp-agent-cloud/use-deployed-server)).

## Going further

* [Cloud overview](/cloud/mcp-agent-cloud/overview) – architecture, auth, observability.
* [Long-running tools](/cloud/mcp-agent-cloud/long-running-tools) – design durable workflows.
* [Manage secrets](/cloud/mcp-agent-cloud/manage-secrets) – developer vs. user secrets.
* [Use a deployed server](/cloud/mcp-agent-cloud/use-deployed-server) – client setup recipes.


# Architecture Overview
Source: https://docs.mcp-agent.com/cloud/mcp-agent-cloud/architecture-overview

How mcp-c stitches MCP apps, Temporal, and container orchestration together

This page expands on the managed architecture that powers `mcp-c`, our MCP cloud platform. Use it to understand deployment flows, security boundaries, and the runtime environment your code executes inside.

## High-level layout

<img src="https://github.com/user-attachments/assets/bb232060-a3cd-4ac1-a6f3-2d228f134d07" alt="Infrastructure diagram showing Temporal cluster, edge tier, and user container instances" width="721" height="758" />

The environment is split into three planes:

| Plane                   | Responsibilities                                                                                                                                         |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Control plane**       | CLI/API ingress, bundle processing, secrets management, permission checks, deployment orchestration.                                                     |
| **Runtime (userspace)** | Dedicated container instance per deployment hosting the MCPApp and any declared stdio MCP servers. Connects to Temporal and logging/metrics pipelines.   |
| **Temporal plane**      | Multi-role Temporal cluster (frontend, history, matching) backed by RDS for durability. Handles workflow scheduling, state persistence, and task queues. |

### Control plane

* **Deployment service** – receives bundles from `mcp-agent deploy`, validates manifests, resolves dependencies, and produces container images.
* **Secrets service** – encrypts deployment secrets and stores handles returned to your app via `mcp_agent.deployed.secrets.yaml`. `mcp-agent cloud configure` interacts with the same service to capture user-provided secrets.
* **Auth service** – issues API keys (`mcp-agent login`) and will host the OAuth 2.1 authorization server described in the [Authentication design](https://github.com/lastmile-ai/lm/docs-revamp/blob/main/mcp-agent9/docs/cloud/authentication/overview.mdx) (Beta).
* **Artifact store** – versioned bundles and metadata (git commit, description, ignore patterns). The same bundle can be replayed to recreate deployments.

### Runtime plane

* **MCP application container** – runs your `main.py` and exposes the MCP transport (SSE + HTTP). The container boots the `MCPApp`, loads secrets, and registers workflows/tool definitions with FastMCP.
* **Stdio MCP server containers** – every entry in `mcp_agent.config.yaml -> mcp.servers` becomes a sidecar container. We currently support Python (`uvx`), Node (`npx`), and any binary accessible via command/args.
* **Envoy router** – mediates outbound requests to Temporal, logging services, and other managed APIs. This allows features like environment-wide header injection and future policy enforcement.
* **Temporal worker** – the MCPApp process hosts the Temporal worker; it polls the shared task queue defined in `mcp_agent.config.yaml` (`temporal.task_queue`) and executes workflows.
* **Observability agents** – Fluent Bit forwards structured logs; OTEL collectors batch traces. You can override endpoints via `mcp-agent cloud logger configure`.

### Temporal plane

* **Multi-role cluster** – uses ECS (or Kubernetes) to run Temporal frontend, history, matching, and worker services with service discovery.
* **RDS** – stores workflow state, task queues, and visibility history. Backups and retention policies are managed centrally.
* **Internal auth** – the Temporal frontend is behind an auth proxy. Runtime containers use short-lived credentials issued by the control plane when deployments start.
* **Notifications** – Temporal emits events for workflow state changes; these feed into future dashboard features and CLI improvements.

## Request flow (MCP client → deployed app)

1. An MCP client (Claude Desktop, Cursor, ChatGPT Apps, custom SSE) connects to `https://<app>.deployments.mcp-agent.com/<transport>` with the configured auth mode.
2. Edge services terminate TLS, validate bearer tokens or OAuth claims, and route traffic to the user runtime.
3. FastMCP inside your container invokes the requested tool or workflow. `@app.tool` handlers return immediately; `@app.async_tool` handlers start a Temporal workflow.
4. The runtime interacts with stdio MCP servers or external APIs as defined in your config. Secrets are available via environment variables or the config object.
5. Results stream back to the client through SSE or HTTP responses. Long-running workflows return `run_id`s which clients poll via `workflows-get_status`.

## Deployment flow (CLI → control plane)

```mermaid  theme={null}
sequenceDiagram
    participant Dev as Developer CLI
    participant Control as Control Plane
    participant Secrets as Secrets Service
    participant Build as Build & Deploy
    participant Runtime as Runtime Plane

    Dev->>Control: mcp-agent deploy (bundle + metadata)
    Control->>Secrets: Transform secrets (handle generation)
    Secrets-->>Control: Handles + user secret prompts
    Control->>Build: Dispatch build job (images + manifests)
    Build-->>Runtime: Provision containers, inject secrets
    Runtime-->>Temporal: Register workers & workflows
    Runtime-->>Control: Health/ready signal
    Control-->>Dev: App ID, server URL, status ONLINE
```

### Bundling specifics

* Uses git metadata when available (`branch`, `commit`, optional `--git-tag`).
* Honors `.mcpacignore` (gitignore syntax). Precedence: `--ignore-file`, then `<config-dir>/.mcpacignore`, then `cwd/.mcpacignore`.
* Embeds `mcp_agent.deployed.secrets.yaml` instead of the raw secrets file.
* Includes `pyproject.toml`, `requirements.txt`, and any other files referenced at runtime (static assets, prompts, etc.).

## Security considerations

* **Network isolation** – runtime containers run in per-tenant subnets; inter-deployment access is blocked by default.
* **Secrets at rest** – encrypted using envelope encryption; only decrypted inside the runtime at startup.
* **Auditability** – all CLI and API calls are logged (coming soon to the user-facing console).
* **Future OAuth** – the upcoming OAuth implementation follows the MCP Authorization spec (RFC 9728) with dynamic client registration and token introspection (`/.well-known/oauth-authorization-server`, `/oauth2/authorize`, `/token`).

## Roadmap highlights

* Web console for deployment management (list, metrics, publish to marketplace).
* Native Temporal trace viewer and workflow search.
* First-class support for publishing public MCP servers with usage analytics.
* Expanded deployment regions and VPC peering for enterprise integrations.

## Related pages

* [Cloud overview →](/cloud/mcp-agent-cloud/overview)
* [Secrets & credential management →](/cloud/mcp-agent-cloud/manage-secrets)
* [Long-running tools & workflows →](/cloud/mcp-agent-cloud/long-running-tools)
* [Authentication modes →](/cloud/authentication/overview)


# Deploying MCP Servers
Source: https://docs.mcp-agent.com/cloud/mcp-agent-cloud/deploy-mcp-server

Ship FastMCP or custom MCP servers on mcp-agent cloud infrastructure

`mcp-agent cloud` is not limited to full agent workflows—you can deploy any MCP-compliant server (Python, Node, Rust, etc.) and let the platform handle hosting, auth, and observability. This is ideal for tool libraries, data access APIs, or bridge services that you want to publish without maintaining infrastructure.

## Why deploy plain MCP servers?

* **Standard MCP interface** – Serve tools, resources, and prompts that any MCP client can consume.
* **Managed runtime** – Containers, TLS, load balancing, and scaling handled automatically.
* **Security** – Secrets vault, per-client API keys, optional unauthenticated mode for public registries.
* **Observability** – Consistent logging + OTEL pipeline and CLI integration (`mcp-agent cloud logger tail`).
* **Upgrade path** – When you are ready for long-running workflows, migrate the project to `MCPApp` without changing deployment tooling.

### Side-by-side capabilities

| Capability         | Managed MCP server             | Full mcp-agent app                       |
| ------------------ | ------------------------------ | ---------------------------------------- |
| Tools & resources  | ✅ Standard MCP tools/resources | ✅ Same, plus workflow-generated tools    |
| Long-running work  | ⚠️ Request lifetime only       | ✅ Temporal workflows with pause/resume   |
| Human input        | Manual implementation          | ✅ Built-in `request_human_input` APIs    |
| Retry & durability | Manual retries/logging         | ✅ Automatic retries, state persistence   |
| Observability      | ✅ Logs + OTEL forwarding       | ✅ All of the left, plus workflow history |
| Client integration | ✅ SSE/HTTP endpoints           | ✅ Same endpoints                         |

## FastMCP example

```python  theme={null}
# main.py
from fastmcp import FastMCP

mcp = FastMCP("utilities")

@mcp.tool()
async def hash_text(text: str, algorithm: str = "sha256") -> str:
    """Generate a hash of text using hashlib."""
    import hashlib
    h = hashlib.new(algorithm)
    h.update(text.encode())
    return h.hexdigest()

@mcp.resource("utils://algorithms")
async def list_algorithms():
    return {"algorithms": ["md5", "sha1", "sha256", "sha3_512"]}

if __name__ == "__main__":
    mcp.run()
```

Configuration (`mcp_agent.config.yaml`) only needs to reference the entrypoint:

```yaml  theme={null}
name: utilities-server
description: "Handy utility tools exposed over MCP"

execution_engine: asyncio           # No workflows required

mcp:
  servers:
    utilities:
      command: "uvx"
      args: ["python", "main.py"]

logger:
  transports: [console]
  level: info
```

`mcp_agent.secrets.yaml` remains optional unless your server calls external APIs.

## MCPApp-only example (no workflows)

If you prefer to stay inside the `mcp-agent` API surface (to reuse `context`, logging, etc.) you can create tools with decorators and skip workflow definitions.

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

app = MCPApp(name="markdown_tools")

@app.tool
async def to_title_case(text: str) -> str:
    return text.title()

@app.tool
async def count_words(text: str) -> int:
    return len(text.split())

if __name__ == "__main__":
    import asyncio
    asyncio.run(app.run())
```

Config:

```yaml  theme={null}
name: markdown-tools
execution_engine: asyncio
logger:
  transports: [console]
  level: info
```

Because there are no workflows, the app behaves like a standard MCP server but you can add Temporal-backed workflows later without changing the deployment process.

## Deploy the server

1. **Authenticate** (once per environment):

   ```bash  theme={null}
   mcp-agent login          # stores MCP_API_KEY
   ```

2. **Deploy from the directory that contains `main.py` and `mcp_agent.config.yaml`:**

   ```bash  theme={null}
   mcp-agent deploy utilities-server \
     --app-description "Utility functions as MCP tools"
   ```

   * Use `--config-dir path/to/server` if deploying from a monorepo.
   * Add `--no-auth` to expose a public endpoint (e.g., for ChatGPT Apps).
   * Use `--non-interactive` in CI/CD to reuse stored secrets.

3. **Describe the deployment:**

   ```bash  theme={null}
   mcp-agent cloud servers describe utilities-server
   ```

   Copy the `Server URL` for client integration.

## Configure clients

Use either `mcp-agent install` (writes files automatically) or `mcp-agent configure --client` (prints snippets).

```bash  theme={null}
mcp-agent install https://<app_id>.deployments.mcp-agent.com/sse \
  --client cursor

mcp-agent configure https://<app_id>.deployments.mcp-agent.com/sse \
  --client vscode --write
```

`<app_id>` is the hostname reported by the CLI (for example, `app_abc123xyz.deployments.mcp-agent.com`).

For unauthenticated deployments (e.g., ChatGPT Apps), remember to deploy with `--no-auth` and run:

```bash  theme={null}
mcp-agent install <server-url> --client chatgpt
```

## Operate and monitor

Even though these servers do not use Temporal, you still get the operational surface:

* `mcp-agent cloud servers list` – inventory of deployed servers.
* `mcp-agent cloud logger tail utilities-server --follow` – live logs.
* `mcp-agent cloud servers delete utilities-server` – tear down when finished.
* `mcp-agent cloud configure --id <url>` – collect user-specific secrets if needed.

## Upgrade path to full agents

Start simple and layer on durability when required:

```python  theme={null}
# Initial FastMCP tool
@mcp.tool()
async def fetch_issue(repo: str, number: int) -> dict: ...

# Later: wrap inside MCPApp to reuse the tool and add workflows
from mcp_agent.app import MCPApp
app = MCPApp(name="issue_triage")

@app.tool
async def fetch_issue(repo: str, number: int) -> dict: ...

@app.async_tool
async def triage_issue(repo: str, number: int) -> dict:
    # Durable workflow that assigns, notifies, etc.
    ...
```

Redeploy with the same name and clients keep working while gaining new capabilities (`workflows-get_status`, pause/resume, etc.).

## Checklist for MCP server deployments

* [ ] Entrypoint (`main.py`) starts the server when executed.
* [ ] `mcp_agent.config.yaml` references the command + args.
* [ ] `requirements.txt` or `pyproject.toml` included.
* [ ] Secrets captured in `mcp_agent.secrets.yaml` (if needed).
* [ ] `.mcpacignore` excludes large/unnecessary files.
* [ ] Deployment tested locally with `uv run main.py` or `npx @modelcontextprotocol/inspector`.
* [ ] Documentation for consumers (URL, sample tool calls, auth mode).

## Resources

* Example repository: [`examples/cloud/mcp`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/cloud/mcp)
* FastMCP documentation: [github.com/jlowin/fastmcp](https://github.com/jlowin/fastmcp)
* [Deployment quickstart →](/cloud/deployment-quickstart)
* [Authentication options →](/cloud/authentication/deployment-auth)


# Long-Running Tools
Source: https://docs.mcp-agent.com/cloud/mcp-agent-cloud/long-running-tools

Design synchronous tools, async tools, and workflows for durable execution

Cloud deployments turn every tool decorator and workflow definition into a first-class MCP endpoint. This page explains how each decorator maps onto the managed runtime, how Temporal keeps work durable, and how to observe long-running runs in production.

<img src="https://github.com/user-attachments/assets/47eecaa4-d4ee-483e-a047-6f45a07731d4" alt="Temporal workflow execution timeline for an mcp-agent deployment" width="647" height="467" />

## Three building blocks

| Decorator                             | Execution model                                                                                       | When to use                                                                                                    | MCP exposure                                                                    |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `@app.tool`                           | Runs inline inside the MCP server process. Caller blocks until the tool returns.                      | “Quick” actions \< O(seconds). Ideal for fan-out RPCs, data lookups, or deterministic helpers.                 | Registered as `<tool_name>`                                                     |
| `@app.async_tool`                     | Starts a Temporal workflow, returns `{workflow_id, run_id}` immediately. Caller polls for completion. | Any async or long-running operation: multi-step plans, heavy LLM conversations, human-in-the-loop validations. | `<tool_name>` (async). Helpers `workflows-get_status`, `workflows-cancel`, etc. |
| `@app.workflow` / `@app.workflow_run` | Explicit workflow class. Useful for complex logic, reusability, or exposing multiple entrypoints.     | Multi-agent orchestration, routers, evaluator-optimizer loops, deep orchestrators.                             | `workflows-<ClassName>-run`                                                     |

All three share the same contextual features:

* Access to `context.server_registry`, `context.logger`, and configured MCP servers.
* `agent.attach_llm(...)` to work with Augmented LLMs.
* Token counting when tracing is enabled.
* Human input via `await context.request_human_input(...)`.

## Example: synchronous vs async tool

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

app = MCPApp(name="reporting_agent")

# Fast helper – returns immediately
@app.tool(description="Fetch metrics for a repository")
async def get_metrics(repo: str, ctx: Context | None = None) -> dict:
    stats = await ctx.server_registry.call_tool(
        server_name="github", tool_name="get_repo_stats", arguments={"repo": repo}
    )
    return stats

# Long-running operation – durable workflow
@app.async_tool(description="Generate a weekly engineering report")
async def generate_weekly_report(team: str, ctx: Context | None = None) -> dict:
    agent = ctx.app.create_agent(  # convenience helper – see docs/mcp-agent-sdk
        name="report_writer",
        instruction="Compile GitHub + PagerDuty + Notion into a weekly summary.",
        server_names=["github", "notion", "pagerduty"],
    )
    async with agent:
        llm = await agent.attach_llm()
        summary = await llm.generate_str(
            f"Create a weekly incident & delivery report for {team}. "
            "Include stats from the connected MCP servers."
        )
    # The value is stored in Temporal history and surfaced via workflows-get_status
    return {"report": summary}
```

Callers experience:

```bash  theme={null}
# Synchronous tool – returns result payload immediately
mcp-agent cloud invoke <server> --tool get_metrics --json '{"repo": "lastmile-ai/mcp-agent"}'

# Async tool – returns IDs to poll
mcp-agent cloud invoke <server> --tool generate_weekly_report --json '{"team": "core"}'

# Later…
mcp-agent cloud workflows describe <server> run_9b43be2a
```

## Workflow classes

For intricate flows you can define a workflow class with reusable steps, activities, and signals. This pattern gives you access to the full Temporal API (signals, queries, child workflows, timers).

```python  theme={null}
from mcp_agent.executor.workflow import Workflow, WorkflowResult

@app.workflow
class MultiAgentReview(Workflow[str]):
    """Orchestrate planner, researcher, and writer agents."""

    @app.workflow_run
    async def run(self, topic: str) -> WorkflowResult[str]:
        plan = await self.plan(topic)
        research = await self.research(plan)
        draft = await self.write(research)
        return WorkflowResult(value=draft)

    @app.task
    async def plan(self, topic: str) -> list[str]:
        ...

    @app.task
    async def research(self, plan: list[str]) -> dict:
        ...

    @app.task
    async def write(self, research: dict) -> str:
        ...
```

Temporal executes each `@app.task` as an activity. Tasks can run in parallel, include retries/backoff, or call `await self.context.request_human_input(...)` to pause.

## Monitoring and control

Use the workflow commands to introspect long-running operations:

```bash  theme={null}
# List definitions exposed by the app
mcp-agent cloud workflows list app_abc123

# List recent runs (optionally filter by status)
mcp-agent cloud workflows runs app_abc123 --status running --limit 5

# Inspect a specific run
mcp-agent cloud workflows describe app_abc123 run_cf98712

# Pause / resume with additional context
mcp-agent cloud workflows suspend app_abc123 run_cf98712
mcp-agent cloud workflows resume app_abc123 run_cf98712 \
  --payload '{"approved": true, "notes": "Ship it"}'

# Cancel if you need to stop work
mcp-agent cloud workflows cancel app_abc123 run_cf98712
```

Logs and traces remain available while the workflow executes:

* `mcp-agent cloud logger tail app_abc123 --follow`
* Configure OTEL exporters in `mcp_agent.config.yaml` or via `mcp-agent cloud logger configure`.
* Temporal metadata (start time, attempt count, memo fields) is surfaced in `workflows describe`.

## Best practices

<AccordionGroup>
  <Accordion title="Balance synchronous vs async">
    Anything that might exceed the default request timeout for clients should be an async tool. Claude Desktop and Cursor expect quick responses; returning `{run_id}` lets them switch to a progress UI.
  </Accordion>

  <Accordion title="Emit incremental progress">
    Use `context.logger.info` for status updates and `context.signal_notification` (custom signals) if you need to push progress to the caller. Future versions will surface these in the console.
  </Accordion>

  <Accordion title="Human-in-the-loop">
    `await context.request_human_input(prompt="...")` pauses the workflow and stores state in Temporal. Users resume via `mcp-agent cloud workflows resume … --payload`.
  </Accordion>

  <Accordion title="Leverage workflow memo">
    Attach lightweight metadata (`WorkflowResult(metadata=...)`) to make filtering easier (`--status`, custom reports). Memo values show up in `workflows runs`.
  </Accordion>

  <Accordion title="Namespace task queues">
    Set unique `temporal.task_queue` values per application to control worker placement and concurrency. For large deployments you can run additional workers using `mcp-agent cloud app workers`.
  </Accordion>
</AccordionGroup>

## Further reading

* [Workflow orchestration patterns →](/workflows/overview)
* [Durable agents with your own Temporal cluster →](/mcp-agent-sdk/advanced/durable-agents)
* [Authentication for long-running tools →](/cloud/authentication/deployment-auth)


# Manage Secrets
Source: https://docs.mcp-agent.com/cloud/mcp-agent-cloud/manage-secrets

Securely handle API keys and user-provided credentials for cloud deployments

Secrets management in `mcp-agent cloud` has two phases:

1. **Deployment secrets** – values known at deploy time (provider API keys, service accounts, webhooks). Stored encrypted, mounted into the runtime automatically.
2. **User secrets** – values each consumer must supply (personal access tokens, OAuth refresh tokens). Collected per user via `mcp-agent cloud configure` and scoped to that user’s configuration.

Understanding the difference lets you ship reusable agents without exposing credentials.

## Secret files at a glance

| File                                | When                                     | Contains                                                    | Checked into git?                            |
| ----------------------------------- | ---------------------------------------- | ----------------------------------------------------------- | -------------------------------------------- |
| `mcp_agent.secrets.yaml`            | Before deploy                            | Raw values you author locally                               | **No** (add to `.gitignore`)                 |
| `mcp_agent.deployed.secrets.yaml`   | Generated by `mcp-agent deploy`          | Handles for deployment secrets, `!user_secret` placeholders | Yes – safe to commit                         |
| `mcp_agent.configured.secrets.yaml` | Generated by `mcp-agent cloud configure` | User-supplied secrets bound to secret handles               | Optional – safe to share with that user only |

## Step 1 – author your secrets file

Create `mcp_agent.secrets.yaml` next to `mcp_agent.config.yaml`:

```yaml  theme={null}
openai:
  api_key: "sk-..."                 # deployment secret

notion:
  api_key: "!user_secret NOTION_KEY"  # user secret (collected later)

crm:
  base_url: "https://api.example.com"  # not a secret, but you can store config values too
```

You can tag secrets as user secrets in two ways:

```yaml  theme={null}
notion:
  api_key: "!user_secret NOTION_KEY"     # inline tagged value
```

or

```yaml  theme={null}
notion:
  api_key:
    !user_secret NOTION_KEY
```

Everything else is treated as a deployment secret by default.

## Step 2 – transform during deployment

When you run `mcp-agent deploy`, the CLI:

1. Loads `mcp_agent.secrets.yaml`.
2. Asks how to treat each value (unless already tagged or using `--non-interactive`).
3. Creates secrets via the cloud API and stores the resulting handles.
4. Writes `mcp_agent.deployed.secrets.yaml` and bundles it with your deployment.

Example output:

```
? Store OPENAI_API_KEY as a deployment secret?  [Y/n] y
? Tag NOTION_KEY as user secret?  [Y/n] y
✓ Created 1 deployment secret, 1 user secret placeholder
✓ Wrote mcp_agent.deployed.secrets.yaml (commit safe)
```

Generated file:

```yaml mcp_agent.deployed.secrets.yaml theme={null}
openai:
  api_key: !secret mcpac_sc_5c0e2d7b-5b1b-41af-b5c7-91e0a7c5c6f5

notion:
  api_key: !user_secret NOTION_KEY
```

> Each `!secret` handle references an encrypted value stored in the control plane. Handles are opaque and cannot be used outside the deployment.

## Step 3 – collect end-user secrets (optional)

If you exposed any `!user_secret` entries, share the deployment URL with your users and have them run:

```bash  theme={null}
mcp-agent cloud configure \
  --id https://<app_id>.deployments.mcp-agent.com
```

`<app_id>` is the hostname printed in your deployment output (for example, `app_abc123xyz`).

The CLI:

1. Checks what user secrets are required (`--params` shows them without storing).
2. Prompts for each secret (or reads them from `--secrets-file`).
3. Writes `mcp_agent.configured.secrets.yaml` (unless `--dry-run`).
4. Uploads encrypted user secret handles tied to the caller’s API key.

Example output:

```
? Provide value for NOTION_KEY: ************************
✓ Stored 1 user secret
✓ Wrote mcp_agent.configured.secrets.yaml
```

Subsequent runs reuse stored values; use `--dry-run` to validate without persisting changes.

### Sharing with automated clients

* Provide `mcp_agent.configured.secrets.yaml` alongside the deployment URL for headless environments (CI, scheduled jobs).
* Re-run `mcp-agent cloud configure --params` in pipelines to assert the contract matches expectations.
* If you must rotate secrets automatically, script the configure command with `--secrets-file`.

## Accessing secrets in code

Secrets are injected into your app via the config layer. Use `app.config` or the global settings helper:

```python  theme={null}
from mcp_agent.config import get_settings

settings = get_settings()
openai_key = settings.openai.api_key           # decrypted value
notion_key = settings.notion.api_key           # user secret (per user)
```

You can also access them through environment variables if you prefer:

```python  theme={null}
import os
api_key = os.environ["OPENAI__API_KEY"]
```

> Deployment secrets are available to all users of the app. User secrets are scoped to the specific user/configuration that ran `mcp-agent cloud configure` and are only injected when that user’s API key is used to connect.

## Non-interactive + CI/CD

* **Reuse existing handles**: `mcp-agent deploy --non-interactive` reuses secrets stored in `mcp_agent.deployed.secrets.yaml` and fails if new values are required.
* **Custom API URL/keys**: set `MCP_API_KEY` (or use `--api-key`) and `MCP_API_BASE_URL` for staging environments.
* **Partial updates**: if you add a new entry to `mcp_agent.secrets.yaml`, the CLI prompts only for the new value.

## Advanced tips

<AccordionGroup>
  <Accordion title="MCP_APP_SETTINGS_PRELOAD">
    For local testing or one-off overrides, set `MCP_APP_SETTINGS_PRELOAD` to a YAML string that merges into the app settings before initialization. Useful when you do not want to create a secrets file on disk.
  </Accordion>

  <Accordion title="Secret reuse across deployments">
    Handles are per deployment. If you want to share the same credential across multiple apps, store the raw value in a secure password manager and paste it during each deploy. Secret rotation APIs are on the roadmap.
  </Accordion>

  <Accordion title="Auditing & rotation">
    Today rotation is manual (`mcp-agent deploy` with a new value). We log all secret creation/update events for future audit surfaces. Automatic rotation hooks are planned post-beta.
  </Accordion>

  <Accordion title="Workspace-scoped secrets">
    By default secrets are scoped to your user account. Team-wide sharing is coming with the upcoming workspace model—expect CLI flags to target a workspace instead of a personal scope.
  </Accordion>
</AccordionGroup>

## Troubleshooting

* **“Must have API key to process secrets”** – run `mcp-agent login` (or set `MCP_API_KEY`) before deploying.
* **Secrets not injected at runtime** – double-check `mcp_agent.deployed.secrets.yaml` is present in your project and that you are reading via `get_settings()`. Also ensure the file is not ignored by `.mcpacignore`.
* **Configure prompts unexpectedly** – you likely tagged a value as `!user_secret`. If it should be global, re-run `mcp-agent deploy` and choose “store as deployment secret”.
* **Need to revoke a user’s secrets** – run `mcp-agent cloud app revoke-config --id <configuration_id>` (coming soon). For now, delete the configuration via the API or ask the user to run configure again.

## Related docs

* [Deployment quickstart →](/cloud/deployment-quickstart)
* [Authentication options →](/cloud/authentication/deployment-auth)
* [Reference configuration schema →](/reference/configuration)


# Use a Deployed Server
Source: https://docs.mcp-agent.com/cloud/mcp-agent-cloud/use-deployed-server

Configure clients, share endpoints, and automate consumption of deployed MCP servers

After deployment, each app is reachable at an HTTPS endpoint such as:

```
https://<app_id>.deployments.mcp-agent.com

Replace `<app_id>` with the hostname shown by `mcp-agent deploy` or `mcp-agent cloud servers describe` (e.g., `app_abc123xyz.deployments.mcp-agent.com`).
```

This page explains how to retrieve the URL, set up authentication, configure clients, and script interactions.

## 1. Find the server URL

```bash  theme={null}
# Show all deployments (filterable, sortable)
mcp-agent cloud servers list

# Describe a specific deployment and copy the Server URL
mcp-agent cloud servers describe app_abc123 --format text
```

The description output includes:

* `Server URL` – base URL (append `/sse` for SSE transport or `/call_tool` for HTTP).
* Authentication mode (Bearer token, unauthenticated, OAuth coming soon).
* Status, creation time, description.

## 2. Make sure clients have the right secrets

If you tagged any `!user_secret` entries, each consumer must configure the deployment before connecting:

```bash  theme={null}
# Prompts for required secrets (per API key)
mcp-agent cloud configure --id https://<app_id>.deployments.mcp-agent.com

# Inspect required parameters without storing
mcp-agent cloud configure --id <server-url> --params
```

You can supply a YAML file (`--secrets-file`) or capture the resulting file (`--secrets-output-file`) to share with your team.

## 3. Install into MCP clients

Use the top-level install command to update client-specific config files:

```bash  theme={null}
# Claude Desktop (macOS, Windows, Linux)
    mcp-agent install https://<app_id>.deployments.mcp-agent.com/sse \
  --client claude_desktop --name web-summarizer

# Cursor
    mcp-agent install https://<app_id>.deployments.mcp-agent.com/sse \
  --client cursor

# VS Code MCP extension
    mcp-agent install https://<app_id>.deployments.mcp-agent.com/sse \
  --client vscode

# Claude Code (codespaces experience)
    mcp-agent install https://<app_id>.deployments.mcp-agent.com/sse \
  --client claude_code

# ChatGPT Apps (requires --no-auth deployments)
    mcp-agent install https://<app_id>.deployments.mcp-agent.com/sse \
  --client chatgpt
```

What the command does:

* Validates your `MCP_API_KEY` (or uses `--api-key`).
* Fetches app metadata (name, unauthenticated status) for validation.
* Writes the appropriate JSON snippet to the client-specific config file.
* Masks secrets when printing to the terminal (use `--dry-run` to preview).

> Client config locations:\
> • Claude Desktop – `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)\
> • Cursor – `~/.cursor/mcp.json`\
> • VS Code – `<workspace>/.vscode/mcp.json`\
> • Claude Code – `~/.claude.json`

## 4. Manual configuration (if needed)

All MCP clients understand the same HTTP/SSE interface. A minimal configuration looks like:

```json  theme={null}
{
  "servers": {
    "web-summarizer": {
      "url": "https://<app_id>.deployments.mcp-agent.com/sse",
      "headers": {
        "Authorization": "Bearer ${MCP_API_KEY}"
      }
    }
  }
}
```

For Claude Desktop (stdio-only), wrap the HTTP server with `mcp-remote`:

```json  theme={null}
{
  "servers": {
    "web-summarizer": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<app_id>.deployments.mcp-agent.com/sse",
        "--header",
        "Authorization: Bearer ${MCP_API_KEY}"
      ]
    }
  }
}
```

## 5. Automate calls from code

### Python

1. Create or update a server entry in `mcp_agent.config.yaml`:

   ```yaml  theme={null}
   mcp:
     servers:
       web_summarizer_cloud:
         transport: sse
         url: "https://<app_id>.deployments.mcp-agent.com/sse"
         headers:
           Authorization: "Bearer ${MCP_API_KEY}"
   ```

2. Use the shared server registry to open a client session:

   ```python  theme={null}
   import asyncio
   from mcp_agent.config import get_settings
   from mcp_agent.mcp.mcp_server_registry import ServerRegistry
   from mcp_agent.mcp.gen_client import gen_client

   async def run_workflow():
       registry = ServerRegistry(config=get_settings())
       async with gen_client("web_summarizer_cloud", server_registry=registry) as client:
           launch = await client.call_tool(
               "workflows-WebSummarizerWorkflow-run",
               arguments={"run_parameters": {"url": "https://example.com"}},
           )
           run_id = launch.content[0].text
           status = await client.call_tool(
               "workflows-get_status",
               arguments={"run_id": run_id},
           )
           print(status.content[0].text)

   asyncio.run(run_workflow())
   ```

### HTTP / cURL

```bash  theme={null}
curl -X POST https://<app_id>.deployments.mcp-agent.com/call_tool \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "workflows-WebSummarizerWorkflow-run",
    "arguments": {"run_parameters": {"url": "https://example.com"}}
  }'
```

### MCP Inspector

```bash  theme={null}
npx @modelcontextprotocol/inspector \
  --transport sse \
  --server-url https://<app_id>.deployments.mcp-agent.com/sse \
  --header "Authorization: Bearer $MCP_API_KEY"
```

## 6. Provide usage instructions to end users

Consider sharing a short README with:

* The server URL and description.
* Required user secrets (from `mcp-agent cloud configure --params`).
* Example calls (like the snippets above).
* Recommended MCP clients (Claude Desktop, Cursor, ChatGPT, etc.).
* Observability tips (`mcp-agent cloud logger tail` for debugging).

## 7. Rotate tokens and access

* **Rotate API keys** – run `mcp-agent login` again or set a new `MCP_API_KEY`.
* **Revoke access** – delete individual configurations (coming soon) or redeploy with `--auth` to disable unauthenticated access.
* **Publish publicly** – ensure the deployment is unauthenticated and document explicit rate limits / expectations.

## Related docs

* [Deployment quickstart →](/cloud/deployment-quickstart)
* [Authentication options →](/cloud/authentication/deployment-auth)
* [Secrets management →](/cloud/mcp-agent-cloud/manage-secrets)


# Observability
Source: https://docs.mcp-agent.com/cloud/observability

Stream logs, emit traces, and integrate mcp-agent cloud with your OTEL stack

Robust observability is critical for diagnosing LLM workflows and multi-agent behaviour. mcp-agent cloud provides two complementary surfaces:

1. **Managed telemetry** – live log streaming, request metadata, and token usage accessible via CLI.
2. **Bring-your-own OTEL** – forward traces and metrics to any OpenTelemetry collector (Grafana, Honeycomb, Datadog, etc.).

## Live logs from the CLI

```bash  theme={null}
# Tail logs (newest first)
mcp-agent cloud logger tail app_abc123

# Follow in real time
mcp-agent cloud logger tail app_abc123 --follow

# Filter and limit
mcp-agent cloud logger tail app_abc123 \
  --since 30m \
  --grep "ERROR|timeout" \
  --limit 200 \
  --format json
```

Options:

* `--since 5m | 2h | 1d` – relative duration.
* `--grep "pattern"` – regex filtering.
* `--format text|json|yaml` – machine-readable output for automation.
* `--order-by timestamp|severity` + `--asc/--desc` – sort order (non-follow mode).

> Pro tip: Pipe JSON output into `jq` for structured analysis:\
> `mcp-agent cloud logger tail app_abc123 --format json --limit 200 | jq '.message'`

## Configure your own OTEL endpoint

Forward logs and traces to your collector:

```bash  theme={null}
mcp-agent cloud logger configure https://otel.example.com:4318/v1/logs \
  --headers "Authorization=Bearer abc123,X-Org=lastmile"
```

* `--test` validates the current configuration without saving.
* The command writes OTEL settings back into your project’s `mcp_agent.config.yaml` for portability.

### Sample OTEL configuration

```yaml mcp_agent.config.yaml theme={null}
otel:
  enabled: true
  service_name: web-summarizer
  sample_rate: 1.0
  exporters:
    - type: otlp
      protocol: http/protobuf
      endpoint: https://otel.example.com:4318
      headers:
        Authorization: "Bearer ${OTEL_API_TOKEN}"
```

Set `OTEL_API_TOKEN` in your deployment secrets to keep credentials secure.

## Instrumentation inside your app

The logging and tracing helpers automatically annotate spans with MCP metadata (tool names, agent names, token counts). Supplement with custom attributes:

```python  theme={null}
context.logger.info(
    "Planner completed",
    data={"plan_steps": len(plan), "user": context.session_id},
)

from mcp_agent.tracing.telemetry import record_attribute
record_attribute("workflow.stage", "summarize")
```

When using AugmentedLLM classes, request/response payloads and tool invocations are automatically traced (provider, model, max tokens, tool call IDs).

## Temporal workflow insights

* `mcp-agent cloud workflows describe` prints Temporal status, history length, retries, and memo.
* Enable the Temporal Web UI (coming soon) or connect to your own instance if you self-host.
* For long workflows, log progress using `context.logger.info` so run history includes human-friendly breadcrumbs.

## Tracing examples

Explore the tracing examples in the repository for end-to-end setups:

* [`examples/tracing/agent`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/tracing/agent) – structured logs + spans for agent lifecycle.
* [`examples/tracing/temporal`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/tracing/temporal) – demo with Temporal and OTEL collector.
* [`examples/tracing/langfuse`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/tracing/langfuse) – integrate with Langfuse dashboards.

## Alerting and dashboards (BYO)

Because telemetry is standardised on OTEL, you can:

* Emit metrics to Prometheus/Grafana (set up an OTLP receiver and transform logs to metrics).
* Send traces to Honeycomb/Langfuse for timeline analysis.
* Export logs to Datadog or Splunk via OTLP → vendor-specific connectors.

## Best practices

<AccordionGroup>
  <Accordion title="Include contextual metadata">
    Add `data={...}` payloads to log calls. When streamed to OTEL, these become searchable attributes (e.g., `workflow_id`, `customer_id`, `plan_length`).
  </Accordion>

  <Accordion title="Avoid sensitive content">
    Logs and traces can include LLM prompts/responses. Mask secrets before logging (`***`) or disable verbose logging in production.
  </Accordion>

  <Accordion title="Sample appropriately">
    High-volume workflows may require sampling (`otel.sample_rate`). You can also implement custom sampling logic in code (e.g., only record traces for specific users or stages).
  </Accordion>

  <Accordion title="Correlate runs">
    Store run IDs or correlation IDs in workflow memo and include them in log messages. This makes it easier to pivot between CLI output, OTEL dashboards, and Temporal history.
  </Accordion>
</AccordionGroup>

## Next steps

* [Deployment quickstart →](/cloud/deployment-quickstart)
* [Long-running tools →](/cloud/mcp-agent-cloud/long-running-tools)
* [mcp-agent SDK observability deep dive →](/mcp-agent-sdk/advanced/observability)


# Deployment Overview
Source: https://docs.mcp-agent.com/cloud/overview

Deploy mcp-agent applications to production

`mcp-agent` gives you one programming model that scales from a laptop to a managed cloud runtime. You can deploy full agents **and** standalone MCP servers (FastMCP services, ChatGPT App backends, bespoke tool APIs) without rewriting your app. This section maps the deployment options, explains when to reach for each path, and points to the detailed runbooks that follow.

## Why deploy with `mcp-agent`?

* **One protocol everywhere** – every deployment option exposes the same MCP endpoints (`call_tool`, `read_resource`, `list_prompts`). Any MCP client (Claude, Cursor, ChatGPT Apps, custom SSE client) can connect without rewriting code.
* **Durable workflows when you need them** – the same decorators (`@app.tool`, `@app.async_tool`, `@app.workflow`) run on `asyncio` locally and on Temporal in the cloud. Pause/resume, retries, and human-in-the-loop all come along for free.
* **Operational guardrails** – the CLI manages build artifacts, secrets, auth configuration, client installation, and observability so you can focus on agent logic.

<iframe src="https://www.youtube.com/embed/0C4VY-3IVNU" title="mcp-agent cloud overview" width="100%" height="420" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

## Deployment paths

* **Managed (mcp-c)** – `mcp-agent deploy` bundles your project, processes secrets, and ships it to our hosted environment. Agent workflows execute on Temporal, stdio MCP servers run as sidecar containers, and you get managed auth, logging, and tracing. [Learn the architecture →](/cloud/mcp-agent-cloud/architecture-overview)
* **Bring-your-own Temporal** – point the same project at your self-hosted Temporal cluster for on-prem or air-gapped requirements. See [Durable agents](/mcp-agent-sdk/advanced/durable-agents) for configuration.
* **Plain MCP servers** – use FastMCP or `@app.tool` only and deploy without workflows when you just need stateless tools. [Deploy an MCP server →](/cloud/mcp-agent-cloud/deploy-mcp-server)
* **Local iteration** – run with `asyncio` on your laptop for rapid development and tests. Switch to Temporal when you are ready for durability.

| Use case                   | Recommended path                                         | What you get                                            |
| -------------------------- | -------------------------------------------------------- | ------------------------------------------------------- |
| Prototype & debugging      | `uv run main.py` or `mcp-agent dev start`                | Hot reload, local logs, same decorators                 |
| Durable agents in hours    | `mcp-agent deploy` (managed)                             | Temporal-backed workflows, cloud logging, secrets, auth |
| Regulated / on-prem        | Self-hosted Temporal + `mcp_agent.config.yaml` overrides | Same workflow code, you manage infra                    |
| Publish reusable MCP tools | FastMCP or `@app.tool` deployed via cloud                | Standard MCP transport, installable from CLI            |

## Two-minute preview

```bash  theme={null}
uv tool install mcp-agent          # Install the CLI
mcp-agent login                    # Launch browser auth and create an API key
mcp-agent deploy web-summarizer    # Bundle code, process secrets, push to the cloud
mcp-agent install web-summarizer   # Add the MCP server to a client config
```

The deployment produces a URL such as:

```
https://<app_id>.deployments.mcp-agent.com
```

`<app_id>` is the hostname printed by the CLI (for example, `app_abc123xyz`).

Any MCP client can connect over SSE/WebSocket using your chosen auth mode.

## What happens after deployment?

1. **Temporal schedules your workflows** – every `@app.async_tool` and `@app.workflow` runs as a Temporal workflow with pause/resume, retries, and human input support.
2. **Each stdio MCP server is containerized** – servers declared in `mcp_agent.config.yaml` run in sand-boxed containers with managed lifecycle.
3. **Observability is turned on** – logs are streamed through the `mcp-agent cloud logger tail` API and you can forward traces to any OTLP endpoint.
4. **Clients install with one command** – `mcp-agent install` or `mcp-agent cloud configure` writes the right headers/URLs into Claude Desktop, Cursor, VS Code, or ChatGPT Apps.

<img src="https://github.com/user-attachments/assets/92118b28-07a9-4b00-8293-c8684c08ff35" alt="Overview of the mcp-c platform" width="940" height="470" />

## Explore next

<CardGroup cols={2}>
  <Card title="Deployment Quickstart" icon="rocket" href="/cloud/deployment-quickstart">
    Hands-on walk-through from project to production
  </Card>

  <Card title="mcp-c" icon="cloud" href="/cloud/mcp-agent-cloud/overview">
    Deep dive into the Cloud's architecture & lifecycle
  </Card>

  <Card title="Authentication" icon="shield-check" href="/cloud/authentication/overview">
    Compare bearer tokens, OAuth, and unauthenticated modes
  </Card>

  <Card title="Observability" icon="chart-line" href="/cloud/observability">
    Wire up OTEL exporters and live log streaming
  </Card>

  <Card title="Use cases" icon="diagram-project" href="/cloud/use-cases/deploy-agents">
    Guides for agents, MCP servers, and ChatGPT Apps
  </Card>

  <Card title="CLI reference" icon="terminal" href="/reference/cli">
    Full command catalog for automation and CI
  </Card>
</CardGroup>


# Deploy Agents
Source: https://docs.mcp-agent.com/cloud/use-cases/deploy-agents

Ship full mcp-agent applications with workflows, multi-agent patterns, and Temporal durability

This guide focuses on deploying full `mcp-agent` applications—projects that use workflows, routers, or multi-agent orchestration. It complements the [deployment quickstart](/cloud/deployment-quickstart) with agent-specific advice and links to production-ready examples.

## When to use this guide

* You rely on patterns from *Building Effective Agents* (router, evaluator-optimizer, orchestrator, swarm).
* Your workflows call external MCP servers (filesystem, fetch, bespoke services).
* You need durability (pause/resume, human input, retries) or multiple agents collaborating.
* You want to expose each workflow as an MCP tool for clients to orchestrate.

## Example projects

| Example                   | Highlights                                                                         | Link                                                                                                                                                    |
| ------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Temporal orchestrator** | Executes planner → researcher → writer pipeline using `@app.async_tool`            | [`examples/temporal/orchestrator.py`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal)                                             |
| **Deep orchestrator**     | Hierarchical planner + executor + evaluator; heavy use of AsyncIO & Temporal tasks | [`examples/workflows/workflow_deep_orchestrator`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_deep_orchestrator)     |
| **Evaluator-Optimizer**   | Iterative loop improving an artifact until evaluation passes                       | [`examples/workflows/workflow_evaluator_optimizer`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_evaluator_optimizer) |
| **Cloud research agent**  | Fetch, summarize, and persist findings; demonstrates secrets + outputs             | [`examples/cloud/hello_world`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/cloud/hello_world)                                           |

Clone one of these projects to follow along, or scaffold your own with:

```bash  theme={null}
mcp-agent init --template factory
```

## Production-ready checklist

1. **Config** – `execution_engine: temporal`, unique `temporal.task_queue`, and `mcp.servers` definitions for all external servers.
2. **Secrets** – provider keys in `mcp_agent.secrets.yaml`, user secrets tagged `!user_secret`.
3. **Workflows** – use `WorkflowResult` to attach metadata, `app.task` for reusable steps, and `context.logger` for progress.
4. **Human input** – `await context.request_human_input(...)` for approvals; handle resume payloads.
5. **Observability** – enable OTEL exporters (`otel.enabled: true`) and set `service_name` to identify your app in dashboards.
6. **Resource cleanup** – if workflows create files or tickets, add compensating actions to `finally` blocks or use Temporal activities with retries.

## Deployment workflow

```bash  theme={null}
# 1. Authenticate (once)
mcp-agent login

# 2. Review config & secrets
cat mcp_agent.config.yaml
cat mcp_agent.secrets.yaml

# 3. Run locally (Temporal server or asyncio)
uv run run_worker.py     # starts Temporal worker (see examples/temporal)
uv run main.py           # kicks off a sample workflow

# 4. Deploy
mcp-agent deploy research-assistant \
  --app-description "Planner+researcher+writer agent"

# 5. Verify
mcp-agent cloud servers describe research-assistant
mcp-agent cloud workflows list research-assistant
mcp-agent cloud logger tail research-assistant --follow
```

## Exposing multiple workflows

Every workflow class becomes an MCP tool named `workflows-<ClassName>-run`. You can expose friendly entrypoints via `@app.async_tool` as well:

```python  theme={null}
@app.async_tool(name="draft_blog_post")
async def draft_blog_post(topic: str, ctx: Context):
    workflow = BlogAuthorWorkflow(context=ctx)
    return await workflow.run_async(topic=topic)
```

Clients see both:

* `draft_blog_post` – easy entrypoint returning `{workflow_id, run_id}`
* `workflows-BlogAuthorWorkflow-run` – low-level interface
* `workflows-get_status`, `workflows-cancel`, `workflows-list` – generated automatically

Use `mcp-agent cloud workflows list` to confirm what’s exposed.

## Passing data between tasks

* Use Pydantic models for strong typing (`from mcp_agent.executor.workflow import WorkflowResult`).
* Temporal memo is available via `WorkflowResult(metadata={"session": "abc"})`.
* For large payloads, store artifacts in external systems (S3, databases) and persist references; avoid payloads that exceed Temporal history limits.

## Human-in-the-loop patterns

```python  theme={null}
from mcp_agent.human_input.types import HumanInputRequest

response = await self.context.request_human_input(
    HumanInputRequest(
        prompt="Approve the draft?",
        required=True,
        metadata={"workflow_id": self.context.workflow_id},
    )
)

if response.content != "approve":
    return WorkflowResult(status="rejected")
```

Users resume with:

```bash  theme={null}
mcp-agent cloud workflows resume research-assistant run_123 \
  --payload '{"content": "approve"}'
```

## Observability for complex agents

* Attach structured data to logs: `context.logger.info("Stage complete", data={"stage": 2})`.
* Enable token counting: `token_counter` is automatically populated when tracing is on.
* For long chains, consider writing high-level progress to an external store (Notion, Slack) so operators have context outside the CLI.

## Cleanup & rollbacks

* Redeploying with the same name updates the existing deployment with zero downtime (new containers come online before old ones are drained).
* Use `--git-tag` to relate deployments to commits.
* `mcp-agent cloud servers delete <id>` removes the runtime; workflows in progress are cancelled.
* Keep old bundles locally (stored in `.mcp-agent/dist/`) for debugging.

## Next steps

* [Long-running tools →](/cloud/mcp-agent-cloud/long-running-tools)
* [Observability →](/cloud/observability)
* [ChatGPT Apps deployment →](/cloud/use-cases/deploy-chatgpt-apps) if you plan to publish to OpenAI
* [MCP Agent SDK advanced patterns →](/mcp-agent-sdk/overview)


# Deploy ChatGPT Apps
Source: https://docs.mcp-agent.com/cloud/use-cases/deploy-chatgpt-apps

Expose mcp-agent servers as OpenAI ChatGPT Apps with interactive widgets

OpenAI’s ChatGPT Apps platform can consume MCP servers as “Actions”. This guide explains how to package an mcp-agent or FastMCP deployment for ChatGPT, including widget metadata, static assets, and authentication considerations.

## Requirements

* ChatGPT Apps developer access
* Deployed MCP server with **unauthenticated access enabled** (`mcp-agent deploy ... --no-auth`)
* Optional: frontend bundle (React, vanilla JS) if you want rich widgets; the bundle should have build output (JS, CSS) at web/build/static or web/dist/static

## Recommended project structure

```
chatgpt-app/
├── main.py                    # MCP server (FastMCP or MCPApp)
├── web/                       # Front-end assets (React build)
│   ├── build/                 # React build (or dist) output
│   │   └── static/            # Built static resources (JS, CSS, etc.)
│   └── src/                   # Optional, your React source files
├── mcp_agent.config.yaml
└── requirements.txt
```

Example: [`examples/cloud/chatgpt_app`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/cloud/chatgpt_app)

## 1. Build the widget assets

In the example project:

```bash  theme={null}
cd web
yarn install
yarn build          # Produces web/build/*
cd ..
```

The server serves these assets via FastMCP resources. For initial iteration you can inline HTML/JS inside the MCP resource, but packaging static files yields better caching.

## 2. Define widget metadata

ChatGPT Apps understand OpenAI-specific tool annotations. The example coin-flip widget uses:

```python  theme={null}
from dataclasses import dataclass
from fastmcp import FastMCP, EmbeddedResource

@dataclass
class CoinFlipWidget:
    template_uri: str
    html: str

    def to_tool_annotations(self) -> dict:
        return {
            "openai/outputTemplate": self.template_uri,
            "openai/toolInvocation/invoking": [
                {"type": "text", "text": "Flipping the coin…"}
            ],
            "openai/toolInvocation/invoked": [
                {"type": "text", "text": "Heads or tails?"}
            ],
            "openai/widgetAccessible": True,
            "openai/resultCanProduceWidget": True,
        }
```

When the tool returns an `EmbeddedResource`, ChatGPT hydrates the widget using the referenced HTML template.

## 3. Deploy with `--no-auth`

```bash  theme={null}
mcp-agent deploy chatgpt-coin-flip \
  --app-description "Coin flip widget for ChatGPT Apps" \
  --no-auth
```

Unauthenticated access is mandatory—ChatGPT Apps cannot attach custom headers or bearer tokens yet. The platform still enforces rate limits and observability, but anyone with the URL can access the server. Treat public deployments accordingly.

After deployment, update the widget template URI to the final domain:

```python  theme={null}
SERVER_URL = "https://<app_id>.deployments.mcp-agent.com"
COIN_FLIP_WIDGET = CoinFlipWidget(
    template_uri=f"ui://widget/coin-flip-{DATE_STAMP}.html",
    html=DEPLOYED_HTML_TEMPLATE.replace("{{SERVER_URL}}", SERVER_URL),
)
```

Redeploy to publish changes.

## 4. Register the action in ChatGPT Apps

1. Open [developers.openai.com/apps](https://developers.openai.com/apps).
2. Create or open your app, then add a new **Action**.
3. Choose **MCP** as the action type.
4. Provide the server URL (`https://<app_id>.deployments.mcp-agent.com`). `<app_id>` matches the hostname shown in the deployment output (for example, `app_abc123xyz`).
5. Select **Server-Sent Events** as the transport (all mcp-agent cloud deployments currently expose SSE endpoints).
6. Save and test—ChatGPT will list available tools (`coin-flip`) and display widgets declared via annotations.

## 5. Iterate on the widget

* **Cache busting** – update `template_uri` (include a timestamp or semantic version) whenever you change the HTML so ChatGPT fetches the new template.
* **State** – return structured data from the tool. The client-side widget receives this in `state.result`.
* **Accessibility** – provide meaningful `openai/toolInvocation` strings and fallback text for users who cannot render widgets.

## 6. Optional enhancements

* **Hybrid auth** – combine a public endpoint with per-user rate limiting by inspecting request metadata (e.g., custom query params) inside your tool and calling your own auth service.
* **Telemetry** – use `context.logger.info` to log widget usage; stream via `mcp-agent cloud logger tail`.
* **Publishing** – once stable, add metadata (name, description, icon) when you create the ChatGPT App so users can discover it in the directory.

## Troubleshooting

| Symptom                         | Cause                                        | Fix                                                                                   |
| ------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------- |
| ChatGPT cannot reach the server | Deployment still requires auth               | Redeploy with `--no-auth`                                                             |
| Widget fails to render          | Template URI cached                          | Bump `template_uri` with new suffix                                                   |
| SSE handshake fails             | Wrong transport or missing `/sse`            | Use server URL ending in `/sse` and ensure tool returns SSE-compatible responses      |
| Tool not listed                 | Server offline or tool registration mismatch | `mcp-agent cloud servers describe <id>` and `mcp-agent cloud logger tail` for details |

## Resources

* [ChatGPT App example source](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/cloud/chatgpt_app)
* [OpenAI Apps SDK MCP documentation](https://developers.openai.com/apps-sdk/build/mcp-server)
* [Deploying MCP servers →](/cloud/mcp-agent-cloud/deploy-mcp-server)
* [Authentication overview →](/cloud/authentication/overview)


# Deploy MCP Servers
Source: https://docs.mcp-agent.com/cloud/use-cases/deploy-mcp-servers

Host standalone MCP servers—FastMCP, custom tooling, or data backends—on mcp-agent cloud

You do not need full agent orchestration to benefit from the platform. Use mcp-agent cloud to host plain MCP servers that expose tools, resources, and prompts. Typical scenarios:

* A catalogue of internal services (Jira, GitHub, PagerDuty) surfaced to MCP clients.
* Reusable data access layers (BI dashboards, CRM fetchers).
* Utility toolkits (formatting, encryption, validation) shared across teams.
* Bridges that wrap legacy gRPC/REST APIs in MCP.

## Quick workflow

```bash  theme={null}
# 1. Authenticate
mcp-agent login

# 2. Test locally (FastMCP or custom server)
uv run main.py

# 3. Deploy from project directory
mcp-agent deploy utilities-server \
  --app-description "Utility tools exposed via MCP"

# 4. Describe & copy server URL
mcp-agent cloud servers describe utilities-server

# (The CLI prints a hostname like `app_abc123xyz.deployments.mcp-agent.com`; use that value anywhere `<app_id>` appears below.)

# 5. Install into clients
mcp-agent install https://<app_id>.deployments.mcp-agent.com/sse \
  --client cursor
```

## Project layout

```
utilities-server/
├── main.py                  # FastMCP or custom server entrypoint
├── mcp_agent.config.yaml    # Points at the command/args to start the server
├── requirements.txt         # Dependencies (or pyproject.toml)
└── mcp_agent.secrets.yaml   # Optional secrets for outbound APIs
```

Minimal config:

```yaml  theme={null}
name: utilities-server
execution_engine: asyncio
mcp:
  servers:
    utilities:
      command: "uvx"
      args: ["python", "main.py"]
logger:
  transports: [console]
  level: info
```

> Even though you are not using Temporal, the platform still provides logging, secrets, and auth.

## Authentication modes

* **Bearer token** (default) – users set `MCP_API_KEY` or run `mcp-agent login`.
* **Unauthenticated** – deploy with `--no-auth` for public servers or ChatGPT Apps.
* **OAuth (coming soon)** – follow updates in [Authentication →](/cloud/authentication/overview).

## Observability & operations

* `mcp-agent cloud logger tail <name>` – inspect logs, filter by regex, follow in real time.
* `mcp-agent cloud servers list` – inventory + status.
* `mcp-agent cloud servers delete <name>` – remove deployment.
* `mcp-agent cloud logger configure` – forward logs to your OTEL collector.

## Evolving into an agent

When you want durable workflows, wrap existing tools with `MCPApp` and redeploy under the same name. MCP clients continue to work while gaining new capabilities (`@app.async_tool`, workflow management). See [Deploy Agents →](/cloud/use-cases/deploy-agents) for the migration playbook.

## Further reading

* [Deploying MCP servers (deep dive) →](/cloud/mcp-agent-cloud/deploy-mcp-server)
* [ChatGPT Apps deployment →](/cloud/use-cases/deploy-chatgpt-apps)
* [Secrets management →](/cloud/mcp-agent-cloud/manage-secrets)


# MCP-Cloud (mcp-c)
Source: https://docs.mcp-agent.com/get-started/cloud

Deploy and host your mcp-agents and apps on the cloud.

<Info>
  `mcp-c` is in open beta, and free to use. Share feedback via [GitHub issues](https://github.com/lastmile-ai/mcp-agent/issues) or [Discord](https://lmai.link/discord/mcp-agent).
</Info>

## What is MCP-Cloud?

MCP-Cloud (mcp-c) is a fully managed cloud platform for hosting mcp-agents, apps, and mcp servers.

<iframe src="https://www.youtube.com/embed/0C4VY-3IVNU" title="mcp-agent cloud overview" width="100%" height="420" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

### Key Benefits

* **One runtime for any MCP application** – deploy durable `mcp-agent` workflows, FastMCP servers, or ChatGPT App backends. Everything is exposed as an MCP server at `https://<unique_id>.deployments.mcp-agent.com` ([Cloud overview](/cloud/mcp-agent-cloud/overview)).
* **Temporal-backed execution** – long-running tools and workflows run on Temporal with retries, pause/resume, and human input support ([Long-running tools](/cloud/mcp-agent-cloud/long-running-tools)).
* **Managed secrets & authentication** – manage secrets for both you, as the developer, and your users. Allow users to specify their own keys, and choose bearer or unauthenticated access today (OAuth coming soon) ([Manage secrets](/cloud/mcp-agent-cloud/manage-secrets) and [Deployment auth](/cloud/authentication/deployment-auth)).
* **Observability built in** – stream logs, forward traces, and inspect workflow history directly from the CLI ([Observability](/cloud/observability)).
* **Easy client install** – use `mcp-agent install` or `mcp-agent cloud configure` to wire the deployed server into Claude Desktop, Cursor, VS Code, or ChatGPT Apps ([Use a deployed server](/cloud/mcp-agent-cloud/use-deployed-server)).

With that context, the steps below show exactly how to deploy.

## 1. Authenticate

```bash  theme={null}
uvx mcp-agent login
```

The CLI opens the Cloud dashboard so you can generate an API token. Credentials are stored under `~/.mcp-agent/`.

## 2. Deploy

From the directory containing your `mcp_agent.config.yaml` (or pass `--config-dir`):

```bash  theme={null}
uvx mcp-agent deploy my-agent
```

During deployment you'll classify secrets as **deployment** (stored securely) or **user** (provided later via `mcp-agent cloud configure`).

<CodeGroup>
  ```bash basic theme={null}
  directory/
  ├── main.py
  ├── mcp_agent.config.yaml
  └── mcp_agent.secrets.yaml
  ```

  ```bash deploy theme={null}
  uvx mcp-agent deploy my-agent
  ```
</CodeGroup>

After a successful deploy you'll receive an endpoint like:

```
https://<unique_id>.deployments.mcp-agent.com
```

## 3. Connect from clients

Your cloud deployment is a standard MCP server. Use any MCP client:

<Tabs>
  <Tab title="Claude Desktop">
    ```bash  theme={null}
    uvx mcp-agent install https://<unique_id>.deployments.mcp-agent.com \
      --client claude_desktop \
      --name research-buddy
    ```

    Replace `claude_desktop` with `vscode`, `cursor`, `chatgpt`, `claude_code` to install in those clients instead.
  </Tab>

  <Tab title="Python">
    1. Add the cloud server to your config so the registry knows how to connect:

       ```yaml mcp_agent.config.yaml theme={null}
       mcp:
         servers:
           my_agent_cloud:
             transport: sse
             url: "https://<unique_id>.deployments.mcp-agent.com/sse"
             headers:
               Authorization: "Bearer ${MCP_API_KEY}"
       ```

    2. Connect via the shared registry:

       ```python  theme={null}
       import asyncio
       from mcp_agent.config import get_settings
       from mcp_agent.mcp.mcp_server_registry import ServerRegistry
       from mcp_agent.mcp.gen_client import gen_client

       async def use_agent():
           registry = ServerRegistry(config=get_settings())
           async with gen_client("my_agent_cloud", server_registry=registry) as client:
               result = await client.call_tool("my_tool", {"param": "value"})
               print(result)

       asyncio.run(use_agent())
       ```
  </Tab>
</Tabs>

## Monitor & manage

<Tabs>
  <Tab title="Logs">
    ```bash  theme={null}
    uvx mcp-agent cloud logger tail my-agent --follow
    uvx mcp-agent cloud logger tail my-agent --grep "ERROR" --since 5m
    ```
  </Tab>

  <Tab title="Servers">
    ```bash  theme={null}
    uvx mcp-agent cloud servers list
    uvx mcp-agent cloud servers describe my-agent
    ```
  </Tab>

  <Tab title="Workflows">
    ```bash  theme={null}
    uvx mcp-agent cloud workflows list
    uvx mcp-agent cloud workflows describe my-agent run_123
    ```
  </Tab>
</Tabs>

## Example: 👋 Hello World agent

```python main.py theme={null}
import asyncio
from typing import Optional

from mcp_agent.app import MCPApp
from mcp_agent.agents.agent import Agent
from mcp_agent.core.context import Context as AppContext
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

# Create the MCPApp, the root of mcp-agent.
app = MCPApp(name="hello_world", description="Hello world mcp-agent application")

# Hello world agent: an Agent using MCP servers + LLM
@app.tool()
async def finder_agent(request: str, app_ctx: Optional[AppContext] = None) -> str:
    """
    Run an Agent with access to MCP servers (fetch + filesystem) to handle 
    the input request.
    """
    agent = Agent(
        name="finder",
        instruction=(
            """You are a helpful assistant. Use MCP servers to fetch and read 
            files, then answer the request concisely."""
        ),
        server_names=["fetch", "filesystem"],
        context=app_ctx,
    )

    async with agent:
        llm = await agent.attach_llm(OpenAIAugmentedLLM)
        result = await llm.generate_str(message=request)
        return result

async def main():
    async with app.run() as agent_app:
        # Run the agent
        readme_summary = await finder_agent(
            request="Please summarize the README.md file in this directory.",
            app_ctx=agent_app.context,
        )
        print(readme_summary)


if __name__ == "__main__":
    asyncio.run(main())
```

Deploy with:

```bash  theme={null}
uvx mcp-agent deploy hello-world
```

## Learn more

* [CLI reference](/reference/cli) – all commands and flags.
* [Secrets configuration](/mcp-agent-sdk/core-components/configuring-your-application#secrets) – how secrets are merged for Cloud.
* [Cloud agent server guide](/cloud/agent-server) – architecture, auth, and best practices.


# Installation
Source: https://docs.mcp-agent.com/get-started/install

Set up mcp-agent, the CLI, and optional provider extras.

## Prerequisites

<CardGroup cols={2}>
  <Card title="Python 3.10+" icon="python">
    mcp-agent targets Python 3.10 or newer.
  </Card>

  <Card title="Node.js (optional)" icon="node-js">
    Some MCP servers (e.g. filesystem) are distributed via npx and require Node.js.
  </Card>
</CardGroup>

## Run the CLI with `uvx`

You can run `mcp-agent` commands without a global install by using [`uvx`](https://docs.astral.sh/uv/reference/cli/#uvx):

```bash  theme={null}
uvx mcp-agent --version
```

The first run downloads the package into uv's cache; subsequent runs are instant. Whenever you see a command such as `uvx mcp-agent deploy …`, you can paste it directly into your terminal. If you prefer a persistent install, `pip install mcp-agent` still works—but `uvx` keeps things simple.

## Add mcp-agent to your project

Inside your project directory, initialize a new project and add mcp-agent as a dependency:

```bash  theme={null}
uv init
uv add mcp-agent
```

Or with pip:

```bash  theme={null}
pip install mcp-agent
```

`uv add` writes to `pyproject.toml` and `uv.lock`, which the project templates (`uvx mcp-agent init …`) expect.

### Provider extras

mcp-agent includes optional extras for different LLM providers. Install the ones you need:

<AccordionGroup>
  <Accordion title="OpenAI">
    ```bash  theme={null}
    uv add "mcp-agent[openai]"
    pip install "mcp-agent[openai]"
    ```
  </Accordion>

  <Accordion title="Anthropic">
    ```bash  theme={null}
    uv add "mcp-agent[anthropic]"
    uv add "mcp-agent[anthropic_bedrock]"
    uv add "mcp-agent[anthropic_vertex]"
    pip install "mcp-agent[anthropic]"
    ```
  </Accordion>

  <Accordion title="Azure OpenAI">
    ```bash  theme={null}
    uv add "mcp-agent[azure]"
    pip install "mcp-agent[azure]"
    ```
  </Accordion>

  <Accordion title="AWS Bedrock">
    ```bash  theme={null}
    uv add "mcp-agent[bedrock]"
    pip install "mcp-agent[bedrock]"
    ```
  </Accordion>

  <Accordion title="Google Gemini">
    ```bash  theme={null}
    uv add "mcp-agent[google]"
    pip install "mcp-agent[google]"
    ```
  </Accordion>

  <Accordion title="All Providers">
    ```bash  theme={null}
    uv add "mcp-agent[openai,anthropic,azure,bedrock,google]"
    pip install "mcp-agent[openai,anthropic,azure,bedrock,google]"
    ```
  </Accordion>
</AccordionGroup>

## Verify your setup

<Steps>
  <Step title="Create a project folder">
    ```bash  theme={null}
    mkdir mcp-agent-playground
    cd mcp-agent-playground
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash  theme={null}
    uv init
    uv add mcp-agent
    ```
  </Step>

  <Step title="Smoke test">
    ```bash  theme={null}
    uv run python -c "import mcp_agent; print('mcp-agent installed successfully!')"
    ```
  </Step>
</Steps>

<Tip>
  Refer to the [CLI reference](/reference/cli) for the complete command list, then head to the [Quickstart](/get-started/quickstart) to scaffold a project with `uvx mcp-agent init`.
</Tip>

## Next steps

* [Quickstart](/get-started/quickstart) – create a finder agent and run it locally.
* [Deploy to Cloud](/get-started/cloud) – publish your agent with `uvx mcp-agent deploy`.
* [MCP Servers](/mcp-agent-sdk/mcp/overview) – learn how FastMCP and other servers plug into your agents.


# Quickstart
Source: https://docs.mcp-agent.com/get-started/quickstart

Copy, paste, and run your first mcp-agent in minutes.

Let's get you set up with a hello world mcp-agent!

## Create the agent

<Tabs>
  <Tab title="Use CLI (Recommended)">
    <Steps>
      <Step title="Create a folder">
        ```bash  theme={null}
        mkdir mcp-basic-agent
        cd mcp-basic-agent
        ```
      </Step>

      <Step title="Initialize your mcp-agent">
        ```bash  theme={null}
        uvx mcp-agent init
        uv init
        uv add "mcp-agent[openai]"
        uv sync
        ```

        (Prefer pip? `python -m venv .venv && pip install mcp-agent` works too.)
      </Step>

      <Step title="Add your model provider key">
        In the `mcp_agent.secrets.yaml` in your project directory, add your OpenAI or other model provider key.

        ```yaml mcp_agent.secrets.yaml theme={null}
        openai:
          api_key: "your-openai-api-key"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Do it manually">
    <Steps>
      <Step title="Create a folder">
        ```bash  theme={null}
        mkdir mcp-basic-agent
        cd mcp-basic-agent
        ```
      </Step>

      <Step title="Install dependencies with uv">
        ```bash  theme={null}
        uv init
        uv add "mcp-agent[openai]"
        uv sync
        ```

        (Prefer pip? `python -m venv .venv && pip install mcp-agent` works too.)
      </Step>

      <Step title="Add configuration files">
        `mcp_agent.config.yaml`

        ```yaml mcp_agent.config.yaml theme={null}
        execution_engine: asyncio
        logger:
          transports: [console]
          level: info

        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`

        ```yaml mcp_agent.secrets.yaml theme={null}
        openai:
          api_key: "your-openai-api-key"
        ```
      </Step>

      <Step title="Paste the hello world agent">
        `main.py`

        ```python main.py theme={null}
        import asyncio
        import os
        import time

        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="mcp_basic_agent")

        @app.tool()
        async def example_usage() -> str:
            async with app.run() as session:
                logger = session.logger
                context = session.context

                # Let the filesystem server access the current directory
                context.config.mcp.servers["filesystem"].args.extend([os.getcwd()])

                agent = Agent(
                    name="finder",
                    instruction="""You can read local files or fetch URLs.
                        Return the requested information when asked.""",
                    server_names=["fetch", "filesystem"],
                )

                async with agent:
                    logger.info("Connected MCP servers", data=list(context.server_registry.registry.keys()))

                    llm = await agent.attach_llm(OpenAIAugmentedLLM)
                    result = await llm.generate_str(
                        "Print the contents of README.md verbatim; create it first if missing"
                    )
                    logger.info("README contents", data=result)

                    result = await llm.generate_str(
                        "Fetch the first two paragraphs from https://modelcontextprotocol.io/introduction"
                    )
                    logger.info("Fetched content", data=result)

                    tweet = await llm.generate_str(
                        "Summarize that content in a 140-character tweet"
                    )
                    logger.info("Tweet", data=tweet)
                    return tweet

        if __name__ == "__main__":
            start = time.time()
            asyncio.run(example_usage())
            end = time.time()
            print(f"Finished in {end - start:.2f}s")
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Run it locally

```bash  theme={null}
uv run main.py
```

You should see log entries for tool discovery, file access, web fetches, and the final summary tweet. Try editing the instructions or adding new MCP servers to see how the agent evolves.

## Deploy it (optional)

You can deploy your agent as an MCP server.

```bash  theme={null}
uvx mcp-agent login
uvx mcp-agent deploy
```

## Next steps

* Check out the generated README (if you used the CLI) for tips on extending the agent.
* Layer in more capabilities using the [Effective Patterns](/mcp-agent-sdk/effective-patterns/overview) guide.
* Ready to deploy your agent? Follow [Deploy to Cloud](/get-started/cloud).


# Welcome to mcp-agent
Source: https://docs.mcp-agent.com/get-started/welcome

Build effective agents with Model Context Protocol using simple, composable patterns.

<img src="https://mintcdn.com/lastmileai-94a5811a/xKc1LECUXZUL786H/logo/mcp-agent-logo.png?fit=max&auto=format&n=xKc1LECUXZUL786H&q=85&s=ec696e1141d4591a3d5b029223bb8e03" alt="mcp-agent logo" noZoom className="rounded-2xl block" data-og-width="2704" width="2704" data-og-height="876" height="876" data-path="logo/mcp-agent-logo.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/lastmileai-94a5811a/xKc1LECUXZUL786H/logo/mcp-agent-logo.png?w=280&fit=max&auto=format&n=xKc1LECUXZUL786H&q=85&s=68fc6a5ecb3f301fc95f49e63eebb31a 280w, https://mintcdn.com/lastmileai-94a5811a/xKc1LECUXZUL786H/logo/mcp-agent-logo.png?w=560&fit=max&auto=format&n=xKc1LECUXZUL786H&q=85&s=b5880a204c1f4d2952bed2b44ac2bce1 560w, https://mintcdn.com/lastmileai-94a5811a/xKc1LECUXZUL786H/logo/mcp-agent-logo.png?w=840&fit=max&auto=format&n=xKc1LECUXZUL786H&q=85&s=c3a0a5b9b0cc7291961b819929d67bc5 840w, https://mintcdn.com/lastmileai-94a5811a/xKc1LECUXZUL786H/logo/mcp-agent-logo.png?w=1100&fit=max&auto=format&n=xKc1LECUXZUL786H&q=85&s=98d0731cd077bf5e0a57611abebe0b37 1100w, https://mintcdn.com/lastmileai-94a5811a/xKc1LECUXZUL786H/logo/mcp-agent-logo.png?w=1650&fit=max&auto=format&n=xKc1LECUXZUL786H&q=85&s=8a63a447552f7b5ea469e4bf55e1d4e2 1650w, https://mintcdn.com/lastmileai-94a5811a/xKc1LECUXZUL786H/logo/mcp-agent-logo.png?w=2500&fit=max&auto=format&n=xKc1LECUXZUL786H&q=85&s=1294781030763801df0e7de0aa224fb5 2500w" />

**mcp-agent** is your pattern library for building [Model Context Protocol](https://modelcontextprotocol.io/introduction) agents. It pairs Anthropic's [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) patterns with a batteries-included runtime so you can focus on agent behavior—not wiring.

## Why teams pick mcp-agent

<CardGroup cols={2}>
  <Card title="Composable patterns" icon="puzzle-piece">
    Parallel, router, planner, evaluator—every pattern from Anthropic's guide ships as a first-class workflow.
  </Card>

  <Card title="MCP-native" icon="plug">
    Works with any MCP server. Drop in the filesystem, fetch, Slack, Jira, or your own FastMCP servers and start calling tools immediately.
  </Card>

  <Card title="Production ready" icon="shield">
    Durable execution with Temporal, structured logging, token accounting, observability hooks, and cloud deployment via the CLI.
  </Card>

  <Card title="Lightweight & Pythonic" icon="feather">
    Define an agent with a few lines of Python—mcp-agent handles the lifecycle, connections, and MCP server wiring for you.
  </Card>
</CardGroup>

```python {1} theme={null}
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="researcher")

async def main():
    async with app.run() as session:
        agent = Agent(
            name="researcher",
            instruction="Use available tools to gather concise answers.",
            server_names=["fetch", "filesystem"],
        )

        async with agent:
            llm = await agent.attach_llm(OpenAIAugmentedLLM)
            report = await llm.generate_str("Summarize the latest MCP news")
            print(report)

if __name__ == "__main__":
    asyncio.run(main())
```

## Next steps

<CardGroup cols={2}>
  <Card title="Install the toolkit" icon="arrow-down-to-line" href="/get-started/install">
    Set up Python, optional MCP servers, and run the `mcp-agent` CLI with `uvx`.
  </Card>

  <Card title="Hello world in minutes" icon="rocket-launch" href="/get-started/quickstart">
    Scaffold an agent with `uvx mcp-agent init` and run it locally.
  </Card>

  <Card title="Deploy to the cloud" icon="cloud" href="/get-started/cloud">
    Use `uvx mcp-agent deploy` to host your agent as a managed MCP server.
  </Card>

  <Card title="Explore the patterns" icon="diagram-project" href="/mcp-agent-sdk/effective-patterns/overview">
    Learn how to combine planner, router, evaluator, and more.
  </Card>
</CardGroup>


# Authentication
Source: https://docs.mcp-agent.com/mcp-agent-sdk/advanced/authentication

Secure outbound MCP server access and protect your agent endpoints

mcp-agent supports both sides of authentication:

* **Outbound** – the agent authenticates to downstream MCP servers or third-party APIs (OAuth 2.1, API keys, service accounts).
* **Inbound** – the agent itself acts as an OAuth-protected MCP server, validating bearer tokens before exposing tools or workflows.

This page summarises the configuration surface and points to working examples. For protocol details, see the [Model Context Protocol authentication spec](https://modelcontextprotocol.io/specification/2025-06-18/server/authentication).

## Authenticating to downstream MCP servers

### OAuth 2.1

Use the `mcp.servers.<name>.auth.oauth` block to configure delegated flows. mcp-agent ships with a full OAuth client implementation that handles loopback callbacks, Redis-backed token storage, and background refresh.

```yaml  theme={null}
oauth:
  token_store:
    backend: redis             # memory (default) or redis
    redis_url: "redis://localhost:6379/0"
    redis_prefix: "mcp_agent:oauth_tokens"
  flow_timeout_seconds: 300
  loopback_ports: [33418, 33419, 33420]

mcp:
  servers:
    notion:
      command: "uvx"
      args: ["mcp-server-notion"]
      description: "Notion knowledge base"
      auth:
        oauth:
          authorization_server: "https://auth.notion.example.com"
          client_id: "${NOTION_CLIENT_ID}"
          client_secret: "${NOTION_CLIENT_SECRET}"
          scopes:
            - "workspace.read"
            - "workspace.write"
          redirect_uri_options:
            - "http://localhost:33418/callback"
```

When you run the agent, mcp-agent opens a browser window (or loopback server) to complete the OAuth flow and caches the token according to the settings above. Populate secrets via `mcp_agent.secrets.yaml`, environment variables (`export NOTION_CLIENT_SECRET=...`), or `MCP_APP_SETTINGS_PRELOAD`.

### Static headers / environment variables

When a server expects API keys or custom headers, configure them directly under `auth` or `env`. The Slack example ([`examples/usecases/mcp_basic_slack_agent`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/usecases/mcp_basic_slack_agent)) injects credentials via environment variables:

```yaml  theme={null}
mcp:
  servers:
    slack:
      command: "uvx"
      args: ["mcp-server-slack"]
      env:
        SLACK_BOT_TOKEN: "${SLACK_BOT_TOKEN}"
        SLACK_TEAM_ID: "${SLACK_TEAM_ID}"
```

You can also attach static request headers when registering a remote server—as shown in the SSE examples (`examples/mcp/mcp_sse_with_headers`):

```yaml  theme={null}
mcp:
  servers:
    github:
      transport: sse
      url: "https://api.example.com/mcp"
      headers:
        Authorization: "Bearer ${GITHUB_TOKEN}"
        X-Org-Id: "${ORG_ID}"
```

Examples in [`examples/model_providers`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/model_providers) show how to configure providers such as Azure OpenAI, Amazon Bedrock, Google Gemini, and Ollama using env vars or header-based credentials.

## Protecting your agent with OAuth

If your MCP app should require bearer tokens from clients, enable the `authorization` section. mcp-agent advertises the protected-resource metadata (`/.well-known/oauth-protected-resource`) and validates tokens via JWKS or introspection endpoints.

```yaml  theme={null}
authorization:
  enabled: true
  issuer_url: "https://auth.example.com"
  resource_server_url: "https://agent.example.com"
  service_documentation_url: "https://agent.example.com/docs"
  required_scopes: ["agent.read", "agent.execute"]
  expected_audiences: ["api://agent.example.com"]
  jwks_uri: "https://auth.example.com/.well-known/jwks.json"
  token_cache_ttl_seconds: 300
```

When deployed (locally or hosted on mcp-c), clients must present a valid access token with the listed audiences/scopes. This is fully compatible with the Model Context Protocol logging, workflow, and elicitation utilities.

For an overview of secret management (`mcp_agent.secrets.yaml`, environment overrides, preload strategies), see [Configuring your application → Secrets](/mcp-agent-sdk/core-components/configuring-your-application#secrets).

## Example projects

* [examples/basic/oauth\_basic\_agent](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/oauth_basic_agent) – minimal OAuth client that authenticates to GitHub and Notion MCP servers.
* [examples/oauth/interactive\_tool](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/interactive_tool) – demonstrates interactive authorisation from within a tool.
* [examples/oauth/pre\_authorize](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/pre_authorize) – seeds refresh tokens before launching a durable Temporal workflow.
* [examples/mcp\_agent\_server/temporal](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp_agent_server/temporal) – combines resource-server protection with long-running workflows and human approvals.


# Durable Agents (Temporal)
Source: https://docs.mcp-agent.com/mcp-agent-sdk/advanced/durable-agents

Run long-lived MCP workflows with Temporal pause/resume and human approvals

mcp-agent can execute workflows on the built-in asyncio executor or on [Temporal](https://temporal.io/). Temporal adds durable state, automatic retries, and first-class pause/resume semantics for long-running MCP tools. The best part: **switching is just a config change**—set `execution_engine: temporal` and your existing workflows, tools, and agents keep working.

<Tip>
  Outside of configuration (and starting a Temporal worker), you rarely need to touch your code. The same `@app.workflow`, `@app.workflow_run`, `@app.async_tool`, `Agent`, and AugmentedLLM APIs behave identically with Temporal behind the scenes.
</Tip>

## When to choose Temporal

| Reach for Temporal when…                                                     | Asyncio alone is enough when…                                |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Workflows must survive restarts, deploys, or worker crashes.                 | Runs are short-lived and you can re-trigger them on failure. |
| Human approvals, scheduled delays, or days-long research loops are in scope. | The agent answers a single request synchronously.            |
| You need history, querying, and signal support from the Temporal UI or CLI.  | You only need to fan out a few tasks inside one process.     |

Temporal also unlocks adaptive throttling, workflow versioning, and seamless integration with mcp-agent Cloud.

## Enable the Temporal engine

Switch the execution engine and point at a Temporal cluster (the examples assume `temporal server start-dev`):

```yaml  theme={null}
execution_engine: temporal

temporal:
  host: "localhost"
  port: 7233
  namespace: "default"
  task_queue: "mcp-agent"
  max_concurrent_activities: 10
```

Start a local server for development:

```bash  theme={null}
temporal server start-dev
# Web UI: http://localhost:8233  |  gRPC: localhost:7233
```

The [configuration reference](/reference/configuration#temporalsettings) documents TLS, API keys, automatic retries, and metadata headers when you deploy to production.

Temporal relies on a replay model: the deterministic parts of your workflow (the code you wrote under `@app.workflow_run`) are re-executed after a crash, while non-deterministic work—LLM calls, MCP tool calls, HTTP requests—is automatically offloaded to Temporal activities by the executor. mcp-agent handles that split for you; you keep writing straightforward async Python.

## Run a worker

Workers poll Temporal for workflow/activity tasks. The helper `create_temporal_worker_for_app` wires your `MCPApp` into a worker loop:

```python  theme={null}
# examples/temporal/run_worker.py
import asyncio
import logging

import workflows  # noqa: F401  # registers @app.workflow classes
from main import app
from mcp_agent.executor.temporal import create_temporal_worker_for_app

logging.basicConfig(level=logging.INFO)

async def main():
    async with create_temporal_worker_for_app(app) as worker:
        await worker.run()

if __name__ == "__main__":
    asyncio.run(main())
```

Keep this process running while you start workflows or expose durable tools.

## Launch workflows (or tools) durably

The executor API is unchanged—Temporal persists the state machine behind the scenes:

```python  theme={null}
# examples/temporal/basic.py
async with app.run() as agent_app:
    executor = agent_app.executor  # TemporalExecutor
    handle = await executor.start_workflow(
        "SimpleWorkflow",
        "Print the first 2 paragraphs of https://modelcontextprotocol.io/introduction",
    )
    result = await handle.result()
    print(result)
```

You can also expose a Temporal run as an MCP tool. The orchestrator example uses `@app.async_tool` so clients invoke a single tool call while Temporal handles retries and state:

```python  theme={null}
# examples/temporal/orchestrator.py (excerpt)
@app.async_tool(name="OrchestratorWorkflow")
async def run_orchestrator(task: str, app_ctx: AppContext | None = None) -> str:
    context = app_ctx or app.context
    orchestrator = Orchestrator(
        llm_factory=OpenAIAugmentedLLM,
        available_agents=[finder, writer, proofreader, fact_checker, style_enforcer],
        plan_type="full",
        context=context,
    )
    return await orchestrator.generate_str(task)

async with app.run() as orchestrator_app:
    executor = orchestrator_app.executor
    handle = await executor.start_workflow("OrchestratorWorkflow", task)
    report = await handle.result()
```

This pattern is ideal for “long-running tool” buttons in MCP clients: the tool call returns immediately with a run identifier and you can stream progress or resume later.

## Human approvals, pause, and resume

Temporal signals map directly to `executor.wait_for_signal` and `executor.signal_workflow`. The pause/resume workflow shipped in [`examples/mcp_agent_server/temporal`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp_agent_server/temporal) demonstrates the flow:

```python  theme={null}
# PauseResumeWorkflow (excerpt)
print(f"Workflow paused. workflow_id={self.id} run_id={self.run_id}")
try:
    await app.context.executor.wait_for_signal(
        signal_name="resume",
        workflow_id=self.id,
        run_id=self.run_id,
        timeout_seconds=60,
    )
except TimeoutError:
    raise ApplicationError("Timed out waiting for resume signal", type="SignalTimeout", non_retryable=True)

return WorkflowResult(value=f"Workflow resumed! {message}")
```

Resume it from another process, the Temporal UI, or mcp-agent Cloud (`mcp-agent workflows resume`):

```python  theme={null}
async with app.run() as agent_app:
    executor = agent_app.executor
    await executor.signal_workflow(
        workflow_name="PauseResumeWorkflow",
        workflow_id="pause-resume-123",
        signal_name="resume",
        payload={"approved_by": "alex"},
    )
```

The same helper works on the asyncio executor via `app.context.executor.signal_bus`, so you can prototype locally and switch to Temporal when you need durability.

### Nested tools and elicitation

The Temporal server example also shows how durable workflows call nested MCP servers and trigger [MCP elicitation](https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation) when a human response is required. Activities such as `call_nested_elicitation` log progress via `app.app.logger` so the request trace and Temporal history stay aligned.

## Operating durable agents

* **Temporal Web UI** ([http://localhost:8233](http://localhost:8233)) lets you inspect history, replay workflow code, and emit signals.
* **Workflow handles** expose `describe()`, `query()`, and `list()` helpers for custom dashboards or integrations.
* **Observability**: enable OpenTelemetry (`otel.enabled: true`) to stream spans + logs while Temporal provides event history.
* **Deployment**: mcp-agent Cloud uses the same configuration. Once deployed, Cloud exposes CLI commands (`mcp-agent workflows list`, `resume`, `cancel`) that call the same signal/query APIs shown above.

## Deeper dives

* [Temporal example suite](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal) – side-by-side asyncio vs. Temporal workflows (basic, router, parallel, evaluator-optimizer) plus a detailed [README](https://github.com/lastmile-ai/mcp-agent/blob/main/examples/temporal/README.md) walking through setup.
* [Temporal MCP server](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp_agent_server/temporal) – exposes durable workflows as MCP tools, demonstrates `workflows-resume`, and includes a client script for pause/resume flows.
* [Temporal tracing example](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/tracing/temporal) – shows the same code running with Jaeger exports once you flip the `execution_engine`.

## Example projects

* [examples/temporal](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal) – basic workflow, evaluator-optimizer, router, and orchestrator patterns on Temporal.
* [examples/mcp\_agent\_server/temporal](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp_agent_server/temporal) – MCP server with durable human approvals, nested servers, and elicitation.
* [examples/oauth/pre\_authorize](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/pre_authorize) – demonstrates pre-authorised credentials for background Temporal workflows.


# Logging
Source: https://docs.mcp-agent.com/mcp-agent-sdk/advanced/logging

Configure structured logging pipelines for mcp-agent

mcp-agent ships with a structured logger that captures context-rich events from apps, workflows, agents, and Temporal workers. Logs are automatically correlated with traces and forwarded to MCP clients using the [Model Context Protocol logging utility](https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/logging).

## Logger entry points

* `app.logger` – application-scoped logger, ideal for tools and startup messages.
* `context.logger` – request-specific logger with access to the active session, token counter, and upstream MCP connection.
* `agent.logger` – automatically bound when you call `async with agent:`; perfect for per-agent instrumentation.

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

app = MCPApp(name="logging_example")

@app.async_tool
async def summarize(text: str) -> str:
    logger = app.logger
    logger.info("summarize.start", data={"characters": len(text)})

    async with app.run() as running_app:
        context_logger = running_app.context.logger
        context_logger.debug("summarize.inflight", data={"preview": text[:30]})
        # ...
        result = text.upper()

    logger.info("summarize.done", data={"preview": result[:30]})
    return result
```

Each call emits an `Event` that can be routed to multiple transports. Span IDs and workflow IDs are injected automatically when tracing is enabled.

## Configure transports and levels

The `logger` section in `mcp_agent.config.yaml` controls transports, batching, and formatting:

```yaml  theme={null}
logger:
  transports: [console, file]   # also supports http, none
  level: info                   # debug | info | warning | error
  progress_display: true
  path: "logs/mcp-agent.jsonl"
  path_settings:
    path_pattern: "logs/mcp-agent-{session_id}.jsonl"
    unique_id: "session_id"     # or "timestamp"
  batch_size: 100
  flush_interval: 2.0

  # HTTP transport (optional)
  http_endpoint: "https://logging.example.com/events"
  http_headers:
    Authorization: "Bearer ${LOGGING_TOKEN}"
  http_timeout: 5.0
```

| Transport | Description                                                                  |
| --------- | ---------------------------------------------------------------------------- |
| `console` | Rich-formatted output to stdout (colours, nested JSON blocks).               |
| `file`    | JSON Lines file writer with optional timestamp/session-based file rotation.  |
| `http`    | Batch POST events to an HTTP endpoint (Elasticsearch, Datadog intake, etc.). |
| `none`    | Disable external transports (events still flow through the async event bus). |

## Structured events

Logs accept a `message` plus an optional `data` payload. The payload is serialised as JSON and preserved end-to-end:

```python  theme={null}
logger.info(
    "plan.generated",
    data={
        "steps": len(plan.steps),
        "agents": [task.agent for step in plan.steps for task in step.tasks],
    },
)
```

Sample JSON from the file transport:

```json  theme={null}
{
  "level": "INFO",
  "timestamp": "2025-01-18T02:41:09Z",
  "namespace": "logging_example.plan.generated",
  "message": "plan.generated",
  "data": {
    "steps": 3,
    "agents": ["finder", "proofreader", "editor"]
  },
  "trace": {
    "trace_id": "5f26e2c4f29be3280c7b52fb93db8550",
    "span_id": "84647445abd6213e"
  }
}
```

Because trace IDs are present, you can pivot between logs and OpenTelemetry spans in Jaeger/Tempo with a single click.

## MCP logging to upstream clients

When your app runs as an MCP server, the logger automatically forwards events to connected clients using the MCP logging channel. MCP-compatible tools (Claude Desktop, Cursor, etc.) will display your messages in their native consoles.

```python  theme={null}
# Inside a workflow or tool
context_logger.info(
    "human.approval.requested",
    data={"workflow_id": self.id, "run_id": self.run_id},
)
```

For long-running Temporal workflows, the logger falls back to a special activity (`mcp_forward_log`) so events appear in the client even while the workflow is suspended.

## Tips for production setups

* Pair logging with tracing (`otel.enabled: true`) so every event carries span metadata.
* Use `progress_display: true` when running CLI tools to get live status bars for long flows.
* Tune `batch_size`/`flush_interval` for high-volume agents; the defaults (100 events / 2 seconds) work well for most workloads.
* HTTP transports can carry filters—attach an `EventFilter` if you only want to forward warnings and errors.

## Reference implementations

* [`examples/tracing/agent`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/tracing/agent) – shows log + trace correlation and human input callbacks.
* [`examples/tracing/mcp`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/tracing/mcp) – demonstrates MCP logging surfaced inside a connected client.
* [`examples/mcp_agent_server/temporal`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp_agent_server/temporal) – Temporal workflow logs, approvals, and nested MCP servers.
* [`examples/temporal`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal) – durable workflows emitting structured log events alongside spans.


# Observability
Source: https://docs.mcp-agent.com/mcp-agent-sdk/advanced/observability

Collect traces, metrics, and token usage from mcp-agent workflows

Reliable agents need first-class visibility. mcp-agent ships with structured logging, OpenTelemetry instrumentation, and a token counter that works across every AugmentedLLM. This page shows how to wire everything together and where to find reference implementations.

## What ships out of the box

* **Structured logger** – `app.logger`, `context.logger`, and every `Agent` share the same event bus, automatically enriched with trace and workflow identifiers.
* **TokenCounter** – every AugmentedLLM records token usage, cost estimates, and parent/child relationships so you can inspect expensive branches.
* **OpenTelemetry hooks** – spans are emitted for workflows, tool calls, LLM requests, MCP server traffic, and Temporal activities when tracing is enabled.
* **Metrics integration points** – `mcp_agent.tracing.telemetry.get_meter` exposes counters/histograms ready for Prometheus or any OTLP collector.

## Enable OpenTelemetry

Add the `otel` block to `mcp_agent.config.yaml` (see the [configuration reference](/reference/configuration#opentelemetrysettings) for every option). The snippet below mirrors what the tracing examples ship with (multiple exporters are supported; include as many as you need):

```yaml  theme={null}
otel:
  enabled: true
  service_name: "mcp-agent"
  service_version: "1.0.0"
  sample_rate: 1.0
  exporters:
    - console
    - file:
        path: "logs/mcp-agent.jsonl"
        path_settings:
          path_pattern: "logs/mcp-agent-{timestamp}.jsonl"
          timestamp_format: "%Y%m%d_%H%M%S"
    # - otlp:
    #     endpoint: "http://your-collector-endpoint/v1/traces"
    #     headers:
    #       Authorization: "Bearer ${OTEL_TOKEN}"
```

Once enabled, spans automatically propagate through AugmentedLLMs, MCP server calls, and Temporal workflows. Point the OTLP exporter at your tracing backend and repeat the `- otlp` block if you want to send the same data to multiple collectors.

## Add spans and metrics in code

Use the helpers from `mcp_agent.tracing.telemetry` inside workflows, tools, or activities (or apply the `@telemetry.traced()` decorator when you want automatic span creation):

```python  theme={null}
from mcp_agent.tracing.telemetry import get_tracer, record_attributes

@app.workflow_run
async def run(self, request: dict) -> WorkflowResult[str]:
    tracer = get_tracer(self.context)
    with tracer.start_as_current_span("grading.step.plan") as span:
        record_attributes(span, request, prefix="request")
        plan = await self.plan_tasks(request)

    with tracer.start_as_current_span("grading.step.execute"):
        report = await self.execute_plan(plan)

    return WorkflowResult(value=report)

@telemetry.traced()
async def expensive_helper(...):
    ...
```

Prefer `get_tracer(self.context)` when you are inside mcp-agent primitives so trace data flows through the shared `Context`. If you are instrumenting utility code outside that context, you can fall back to standard OpenTelemetry helpers (`from opentelemetry import trace; tracer = trace.get_tracer(__name__)`).

For metrics, grab a meter and increment counters/histograms (the Prometheus exporter is enabled automatically when you add a metric reader):

```python  theme={null}
from mcp_agent.tracing.telemetry import get_meter

meter = get_meter(app.context)
grading_counter = meter.create_counter(
    "grading_runs_total", description="Number of grading workflows started"
)
grading_counter.add(1, attributes={"plan_type": plan.plan_type})
```

## Metrics collection & token accounting

### Token summaries and trees

Every AugmentedLLM exposes a token node that mirrors its call graph. The orchestrator workflow example wraps this in a helper that prints a tree:

```python  theme={null}
# examples/workflows/workflow_orchestrator_worker/main.py (excerpt)
node = await orchestrator.get_token_node()
if node:
    display_node_tree(node, context=context)

summary = await orchestrator_app.get_token_summary()
print(f"Total Cost: ${summary.cost:.4f}")
```

The `TokenNode` reports aggregate usage, per-child breakdowns, and cost estimates. You can attach the tree to your own logging, export it as JSON, or feed it into observability dashboards.

<img width="2160" alt="Image" src="https://github.com/user-attachments/assets/691021a6-1b3f-40db-9cc9-bc6f969a9880" />

*Screenshot from [`examples/tracing/agent`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/tracing/agent) showing spans and structured logs side by side.*

```text  theme={null}
Total Usage:
  Total tokens: 2,542
  Input tokens: 1,832
  Output tokens: 710
  Total cost: $0.0234

Breakdown by Model:
  gpt-4-turbo-preview: 1,234 tokens ($0.0123)
  claude-3-opus-20240229: 1,308 tokens ($0.0111)
```

*Sample output taken from [`examples/basic/token_counter`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/token_counter).*

### TokenCounter watchers

The [`TokenCounter`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/tracing/token_counter.py) tracks usage for every workflow, agent, and LLM node. Besides summaries and trees, you can attach real-time watchers or render live progress. The [`examples/basic/token_counter`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/token_counter) walkthrough demonstrates:

* `TokenProgressDisplay` for live terminal dashboards.
* Custom watcher callbacks (e.g., `token_counter.watch(...)`) that fire when token thresholds are exceeded.
* Per-model breakdowns and cost calculations stored in `TokenNode.metadata`.

```python  theme={null}
# Simplified excerpt from the example showing how to register a watcher.
# TokenMonitor is an app-defined helper; implement your own to collect whatever signals you need.
class TokenMonitor:
    async def on_token_update(self, node: TokenNode, usage: TokenUsage):
        print(f"[{node.name}] total={usage.total_tokens} input={usage.input_tokens} output={usage.output_tokens}")

monitor = TokenMonitor()
watch_id = await token_counter.watch(
    callback=monitor.on_token_update,
    node_type="llm",            # only track LLM nodes
    threshold=1_000,            # only fire when aggregated total exceeds 1,000 tokens
    include_subtree=True,       # include child usage in the threshold check
)

# Later, when you're done observing:
await token_counter.unwatch(watch_id)
```

## Export destinations

| Exporter  | Use it for                                                | Notes                                                     |
| --------- | --------------------------------------------------------- | --------------------------------------------------------- |
| `console` | Quick local debugging                                     | Emits coloured spans/logs to stdout.                      |
| `file`    | Persist traces/logs to disk                               | Combine with `path_settings` for per-run log files.       |
| `otlp`    | OpenTelemetry collectors (e.g. Datadog, Langfuse, Jaeger) | Set the endpoint + headers; works for traces and metrics. |

## Reference implementations

* [`examples/tracing/agent`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/tracing/agent) – minimal tracing + human-input callback instrumentation.
* [`examples/tracing/temporal`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/tracing/temporal) – Temporal executor with Jaeger configuration and OTLP exporters.
* [`examples/tracing/llm`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/tracing/llm) – shows span attributes for individual LLM calls and tool usage.
* [`examples/tracing/mcp`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/tracing/mcp) – emits spans and structured data for MCP server traffic.
* [`examples/tracing/langfuse`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/tracing/langfuse) – exports traces and events to Langfuse with user/session metadata.
* [`examples/tracing/temporal`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/tracing/temporal) – demonstrates how spans flow through Temporal workflows and activities.

Combine the tracing data with the structured logger (see the [Logging guide](/mcp-agent-sdk/advanced/logging)) to correlate events, spans, and MCP tool calls in one place.


# Pause and Resume
Source: https://docs.mcp-agent.com/mcp-agent-sdk/advanced/pause-and-resume

Pause and resume workflows with human-in-the-loop

<Info>
  Content to be migrated from temporal.mdx covering pause/resume and human-in-the-loop patterns.
</Info>

## Overview

With Temporal execution engine, workflows can be paused and resumed:

* **Human-in-the-loop** - Pause for human input/approval
* **Workflow suspension** - Pause execution indefinitely
* **Resume with data** - Continue execution with additional context

[See Durable Agents →](/mcp-agent-sdk/advanced/durable-agents)


# Agents
Source: https://docs.mcp-agent.com/mcp-agent-sdk/core-components/agents

Understanding agents and how to use them in the mcp-agent framework.

## What is an Agent?

In `mcp-agent`, an **Agent** describes what the model is allowed to do. It captures:

* A name and system-level instruction
* The MCP servers (and optional local functions) that should be available
* Optional behaviour hooks such as human-input callbacks or whether connections persist

On its own an agent is just configuration and connection management. The agent becomes actionable only after you attach an LLM implementation. Calling `agent.attach_llm(...)` (or constructing an AugmentedLLM with `agent=...`) returns an **AugmentedLLM**—an LLM with the agent’s instructions, tools, and memory bound in. You then use the AugmentedLLM to run generations, call tools, and chain workflows.

Key ideas:

* **Agent = policy + tool access.** It defines how the model should behave and which MCP servers or functions are reachable.
* **AugmentedLLM = Agent + model provider.** Attaching an LLM binds a concrete provider (OpenAI, Anthropic, Google, Bedrock, etc.) and exposes generation helpers such as `generate`, `generate_str`, and `generate_structured`.
* **Agents are reusable.** You can attach different AugmentedLLM providers to the same agent definition without rewriting instructions or server lists.

## Creating Your First Agent

The simplest way to create an agent is through the `Agent` class. Define the instruction and servers, then attach an LLM to obtain an AugmentedLLM:

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

# Create an agent with access to specific tools
finder_agent = Agent(
    name="finder",
    instruction="""You are an agent with access to the filesystem
    and web fetching capabilities. Your job is to find and retrieve
    information based on user requests.""",
    server_names=["fetch", "filesystem"],
)

# Use the agent in an async context
async with finder_agent:
    # Attach an LLM to the agent
    llm = await finder_agent.attach_llm(OpenAIAugmentedLLM)

    # Generate a response
    result = await llm.generate_str(
        message="Find and show me the contents of the README file"
    )
    print(result)
```

The value returned by `attach_llm` is an `AugmentedLLM` instance. It inherits the agent’s instructions and tool access, so every call to `generate_str` (or `generate` / `generate_structured`) can transparently read files, fetch URLs, or call any other MCP tool the agent exposes.

<CardGroup>
  <Card title="Tool Integration">
    Agents automatically discover and use tools from connected MCP servers,
    giving your LLM powerful capabilities.
  </Card>

  <Card title="Multi-Provider Support">
    Switch between different LLM providers (OpenAI, Anthropic, etc.) without
    changing your agent logic.
  </Card>
</CardGroup>

## AgentSpec and factory helpers

`AgentSpec` (`mcp_agent.agents.agent_spec.AgentSpec`) is the declarative version of an agent: it captures the same fields (`name`, `instruction`, `server_names`, optional functions) and is used by workflows, config files, and factories. The helpers in [`mcp_agent.workflows.factory`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/factory.py) let you turn specs into agents or AugmentedLLMs with a single call.

```python  theme={null}
from pathlib import Path
from mcp_agent.workflows.factory import (
    load_agent_specs_from_file,
    create_llm,
    create_router_llm,
)

async with app.run() as running_app:
    context = running_app.context
    specs = load_agent_specs_from_file(
        str(Path("examples/basic/agent_factory/agents.yaml")),
        context=context,
    )

    # Create a specialist LLM from a spec
    researcher_llm = create_llm(agent=specs[0], provider="openai", context=context)

    # Or compose higher-level workflows (router, parallel, orchestrator, ...)
    router = await create_router_llm(agents=specs, provider="openai", context=context)
```

Explore the [agent factory examples](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/agent_factory) to see how specs keep call sites small, how subagents can be auto-loaded from config, and how factories compose routers, orchestrators, and parallel pipelines.

## Agent Configuration

Agents can be configured either programmatically or through configuration files. The framework supports both approaches, and each definition ultimately resolves to an `AgentSpec`:

### Configuration File Approach

Create a `mcp_agent.config.yaml` file to define your agent's environment:

```yaml  theme={null}
# mcp_agent.config.yaml
$schema: ../../schema/mcp-agent.config.schema.json

execution_engine: asyncio

# Configure logging
logger:
  transports: [console, file]
  level: debug
  progress_display: true

# Define available MCP servers (tools)
mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem"]

# LLM provider configuration
openai:
  default_model: "gpt-4o-mini"
```

### Programmatic Configuration

You can also configure agents directly in code:

```python  theme={null}
from mcp_agent.config import Settings, MCPSettings, MCPServerSettings

settings = Settings(
    execution_engine="asyncio",
    mcp=MCPSettings(
        servers={
            "fetch": MCPServerSettings(
                command="uvx",
                args=["mcp-server-fetch"],
            ),
            "filesystem": MCPServerSettings(
                command="npx",
                args=["-y", "@modelcontextprotocol/server-filesystem"],
            ),
        }
    ),
    openai=OpenAISettings(
        default_model="gpt-4o-mini",
    ),
)
```

## Agent Capabilities

Once an agent has an AugmentedLLM attached, it gains the following capabilities:

### Multi-LLM Provider Support

Switch between different LLM providers seamlessly:

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

async with agent:
    # Start with OpenAI
    llm = await agent.attach_llm(OpenAIAugmentedLLM)
    result1 = await llm.generate_str("Analyze this data...")

    # Switch to Anthropic for the next task
    llm = await agent.attach_llm(AnthropicAugmentedLLM)
    result2 = await llm.generate_str("Summarize the analysis...")
```

### Advanced Model Selection

Control model selection with preferences:

```python  theme={null}
from mcp_agent.workflows.llm.augmented_llm import RequestParams
from mcp_agent.workflows.llm.llm_selector import ModelPreferences

result = await llm.generate_str(
    message="Complex reasoning task",
    request_params=RequestParams(
        modelPreferences=ModelPreferences(
            costPriority=0.1,        # Low cost priority
            speedPriority=0.2,       # Low speed priority
            intelligencePriority=0.7  # High intelligence priority
        ),
        temperature=0.3,
        maxTokens=1000,
    )
)
```

### Human Input Integration

Agents can request human input during execution:

```python  theme={null}
# The agent can automatically request human input when needed
# This is handled through the human_input_callback mechanism
# and appears as a tool the LLM can call
from mcp_agent.human_input.handler import console_input_callback

app = MCPApp(name="my_application", human_input_callback=console_input_callback)

# ...rest of your code

result = await llm.generate_str(
    "Please review this analysis and ask me any questions you need clarification on."
)
```

### Memory and Context Management

Agents maintain conversation history automatically:

```python  theme={null}
# Multi-turn conversations maintain context
result1 = await llm.generate_str("What's the weather like?")
result2 = await llm.generate_str("What about tomorrow?")  # Remembers context
```

## Agent Lifecycle Management

Agents follow a predictable lifecycle:

### 1. Initialization

When you create an agent, it:

* Loads configuration from files or code
* Connects to specified MCP servers
* Discovers available tools and capabilities

### 2. Usage

During operation, the agent:

* Processes user requests through the LLM
* Orchestrates tool calls as needed
* Maintains conversation history
* Handles errors and retries

### 3. Cleanup

When finished, the agent:

* Closes connections to MCP servers
* Releases resources
* Saves any persistent state

```python  theme={null}
# Explicit lifecycle management
agent = Agent(name="my_agent", server_names=["fetch"])

# Initialize
await agent.initialize()

# Use
llm = await agent.attach_llm(OpenAIAugmentedLLM)
result = await llm.generate_str("Hello!")

# Cleanup
await agent.shutdown()

# Or use context manager (recommended)
async with Agent(name="my_agent", server_names=["fetch"]) as agent:
    llm = await agent.attach_llm(OpenAIAugmentedLLM)
    result = await llm.generate_str("Hello!")
    # Automatic cleanup when exiting context
```

## Common Usage Patterns

### Application Integration

Use the `MCPApp` class for full application setup:

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

app = MCPApp(name="my_application")

async def main():
    async with app.run() as agent_app:
        logger = agent_app.logger
        context = agent_app.context

        # Create and use agents within the app context
        agent = Agent(
            name="assistant",
            instruction="You are a helpful assistant.",
            server_names=["filesystem", "fetch"]
        )

        async with agent:
            llm = await agent.attach_llm(OpenAIAugmentedLLM)
            result = await llm.generate_str("Help me organize my files")
            logger.info("Task completed", data={"result": result})
```

### Tool Discovery

Explore what tools are available to your agent:

```python  theme={null}
async with agent:
    # List all available tools
    tools = await agent.list_tools()
    print(f"Available tools: {[tool.name for tool in tools.tools]}")

    # Get detailed tool information
    for tool in tools.tools:
        print(f"Tool: {tool.name}")
        print(f"Description: {tool.description}")
        print(f"Input schema: {tool.inputSchema}")
```

This covers the essential concepts users need to understand and effectively use agents in the mcp-agent framework.


# Augmented LLMs
Source: https://docs.mcp-agent.com/mcp-agent-sdk/core-components/augmented-llm

Understanding augmented LLMs in mcp-agent - enhanced language models with tools, memory, and agent capabilities.

## What are Augmented LLMs?

**Augmented LLMs** are the core intelligence layer in the `mcp-agent` framework. They extend standard language models with enhanced capabilities including tool access, persistent memory, agent integration, and structured output generation.

Think of augmented LLMs as:

* **Enhanced language models** with access to external tools and data sources
* **Stateful conversational agents** that maintain memory across interactions
* **Multi-modal processors** that can handle text, images, and structured data
* **Tool-enabled systems** that can execute functions and access MCP servers

<Card>
  **Key Concept:** Augmented LLMs = Base LLM + Tools + Memory + Agent
  Integration + Structured Output
</Card>

## Provider Support

The `mcp-agent` framework supports multiple LLM providers through a unified interface:

### OpenAI

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

# Create OpenAI-powered augmented LLM
llm = await agent.attach_llm(OpenAIAugmentedLLM)

# Configuration (in mcp_agent.secrets.yaml or mcp_agent.config.yaml)
openai:
  api_key: "your-openai-api-key"
  default_model: "gpt-4o"
  reasoning_effort: "medium"  # For o1/o3 models
```

### Anthropic

```python  theme={null}
from mcp_agent.workflows.llm.augmented_llm_anthropic import AnthropicAugmentedLLM

# Create Anthropic-powered augmented LLM
llm = await agent.attach_llm(AnthropicAugmentedLLM)
```

<Tabs>
  <Tab title="Anthropic API">
    ```yaml mcp_agent.secrets.yaml theme={null}
    # Configuration for Claude models directly from Anthropic
    anthropic:
      api_key: "your-anthropic-api-key"
      default_model: "claude-3-5-sonnet-latest"
    ```
  </Tab>

  <Tab title="AWS Bedrock">
    ```yaml mcp_agent.secrets.yaml theme={null}
    # Configuration for Claude models through AWS Bedrock
    anthropic:
      provider: "bedrock"
      aws_region: "us-east-1"
      aws_access_key_id: "your-aws-access-key"
      aws_secret_access_key: "your-aws-secret-key"
      # Optional: aws_session_token for temporary credentials
    ```
  </Tab>

  <Tab title="Google Vertex AI">
    ```yaml mcp_agent.secrets.yaml theme={null}
    # Configuration for Claude models through Google Vertex AI
    anthropic:
      provider: "vertexai"
      project: "your-gcp-project-id"
      location: "us-central1"
    ```
  </Tab>
</Tabs>

### Azure

```python  theme={null}
from mcp_agent.workflows.llm.augmented_llm_azure import AzureAugmentedLLM

# Create Azure-powered augmented LLM
llm = await agent.attach_llm(AzureAugmentedLLM)
```

<Tabs>
  <Tab title="Azure OpenAI">
    ```yaml mcp_agent.secrets.yaml theme={null}
    # Configuration for Azure OpenAI inference endpoint
    azure:
      api_key: "your-azure-api-key"
      endpoint: "https://<your-resource-name>.openai.azure.com"
      api_version: "2025-04-01-preview"
      default_model: "gpt-4o-mini"
    ```
  </Tab>

  <Tab title="Azure AI">
    ```yaml mcp_agent.secrets.yaml theme={null}
    # Configuration for Azure AI inference endpoint
    azure:
      api_key: "your-azure-api-key"
      endpoint: "https://your-resource-name.services.ai.azure.com/models"
      default_model: "DeepSeek-V3"
    ```
  </Tab>
</Tabs>

### Amazon Bedrock

```python  theme={null}
from mcp_agent.workflows.llm.augmented_llm_bedrock import BedrockAugmentedLLM

# Create Bedrock-powered augmented LLM
llm = await agent.attach_llm(BedrockAugmentedLLM)
```

```yaml mcp_agent.secrets.yaml theme={null}
# Configuration for Amazon Bedrock
bedrock:
  aws_region: "us-east-1"
  aws_access_key_id: "your-aws-access-key"
  aws_secret_access_key: "your-aws-secret-key"
  # Optional: aws_session_token for temporary credentials
  default_model: "anthropic.claude-3-haiku-20240307-v1:0"
```

### Google AI

```python  theme={null}
from mcp_agent.workflows.llm.augmented_llm_google import GoogleAugmentedLLM

# Create Google-powered augmented LLM
llm = await agent.attach_llm(GoogleAugmentedLLM)
```

<Tabs>
  <Tab title="Google AI API">
    ```yaml mcp_agent.secrets.yaml theme={null}
    # Configuration for Google AI (Gemini)
    google:
      api_key: "your-google-api-key"
      default_model: "gemini-2.0-flash"
    ```
  </Tab>

  <Tab title="Vertex AI">
    ```yaml mcp_agent.secrets.yaml theme={null}
    # Configuration for Vertex AI
    google:
      vertexai: true
      project: "your-gcp-project-id"
      location: "us-central1"
      default_model: "gemini-2.0-flash"
    ```
  </Tab>
</Tabs>

### Ollama

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

# Create Ollama-powered augmented LLM (uses OpenAI-compatible API)
llm = await agent.attach_llm(OpenAIAugmentedLLM)
```

```yaml mcp_agent.config.yaml theme={null}
# Configuration for Ollama (local models)
openai:
  base_url: "http://localhost:11434/v1"
  api_key: "ollama"  # Can be any value for local Ollama
  default_model: "llama3.2"  # Or any model you have installed
```

## Core Capabilities

### 1. Multi-Turn Conversations

Augmented LLMs maintain conversation history and context across multiple interactions:

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

# Create agent with conversation capabilities
agent = Agent(
    name="conversational_agent",
    instruction="You are a helpful assistant that remembers our conversation.",
    server_names=["filesystem", "fetch"]
)

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

    # First turn
    response1 = await llm.generate_str("What files are in the current directory?")

    # Second turn - references previous context
    response2 = await llm.generate_str("Can you read the contents of the first file?")

    # Third turn - maintains full conversation history
    response3 = await llm.generate_str("Summarize what we've learned so far")
```

### 2. Tool Integration

Augmented LLMs automatically discover and use tools from connected MCP servers:

```python  theme={null}
# Agent with multiple tool sources
agent = Agent(
    name="tool_user",
    instruction="You can access files, fetch web content, and analyze data.",
    server_names=["filesystem", "fetch", "database"]
)

async with agent:
    # List available tools
    tools = await agent.list_tools()
    print(f"Available tools: {[tool.name for tool in tools.tools]}")

    llm = await agent.attach_llm(OpenAIAugmentedLLM)

    # LLM automatically uses appropriate tools
    result = await llm.generate_str(
        "Read the README.md file and fetch the latest release notes from the GitHub API"
    )
```

### 3. Structured Output Generation

Generate structured data using Pydantic models:

```python  theme={null}
from pydantic import BaseModel
from typing import List

class TaskAnalysis(BaseModel):
    priority: str
    estimated_hours: float
    dependencies: List[str]
    risk_factors: List[str]

# Generate structured output
analysis = await llm.generate_structured(
    message="Analyze this project task: 'Implement user authentication system'",
    response_model=TaskAnalysis
)

print(f"Priority: {analysis.priority}")
print(f"Estimated hours: {analysis.estimated_hours}")
```

## Configuration and Setup

### Basic Configuration

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

# OpenAI configuration
openai:
  default_model: "gpt-4o"
  reasoning_effort: "medium"

# Anthropic configuration
anthropic:
  default_model: "claude-3-5-sonnet-latest"

# MCP servers for tool access
mcp:
  servers:
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem"]
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
```

### Model Preferences

Control model selection with preferences:

```python  theme={null}
from mcp_agent.workflows.llm.augmented_llm import RequestParams
from mcp_agent.workflows.llm.llm_selector import ModelPreferences

# Configure model selection preferences
request_params = RequestParams(
    modelPreferences=ModelPreferences(
        costPriority=0.3,         # 30% weight on cost
        speedPriority=0.4,        # 40% weight on speed
        intelligencePriority=0.3  # 30% weight on intelligence
    ),
    maxTokens=4096,
    temperature=0.7,
    max_iterations=10
)

# Use preferences in generation
result = await llm.generate_str(
    message="Explain quantum computing",
    request_params=request_params
)
```

### Advanced Request Parameters

```python  theme={null}
# Comprehensive request configuration
advanced_params = RequestParams(
    model="gpt-4o",                    # Override model selection
    maxTokens=2048,                    # Response length limit
    temperature=0.7,                   # Creativity level
    max_iterations=10,                 # Tool use iterations
    parallel_tool_calls=False,         # Sequential tool execution
    use_history=True,                  # Include conversation history
    systemPrompt="You are an expert developer",
    stopSequences=["END", "STOP"],
    user="user_123"                    # User identifier
)
```

## Integration Patterns

### Agent-LLM Integration

The standard pattern for using augmented LLMs with agents:

```python  theme={null}
# 1. Create agent with capabilities
agent = Agent(
    name="data_analyst",
    instruction="""You are a data analyst with access to databases and
    file systems. Help users analyze data and generate insights.""",
    server_names=["database", "filesystem", "visualization"]
)

# 2. Connect to servers and attach LLM
async with agent:
    # Discover available tools
    tools = await agent.list_tools()
    print(f"Available tools: {[tool.name for tool in tools.tools]}")

    # Attach preferred LLM provider
    llm = await agent.attach_llm(OpenAIAugmentedLLM)

    # 3. Use LLM with full agent capabilities
    result = await llm.generate_str(
        "Analyze the sales data from Q1 and create a summary report"
    )
```

### Memory Management

Augmented LLMs automatically manage conversation memory:

```python  theme={null}
# Access conversation history
last_message = await llm.get_last_message()
last_message_text = await llm.get_last_message_str()

# Clear memory if needed
llm.history.clear()

# Set specific history
from mcp_agent.workflows.llm.augmented_llm import SimpleMemory
llm.history = SimpleMemory()
llm.history.extend(previous_messages)
```

## Generation Methods

### Basic Text Generation

```python  theme={null}
# Simple text generation
response = await llm.generate_str("What is machine learning?")

# Advanced generation with parameters
response = await llm.generate_str(
    message="Explain neural networks",
    request_params=RequestParams(
        maxTokens=1000,
        temperature=0.5
    )
)
```

### Raw Message Generation

```python  theme={null}
# Get raw message objects
messages = await llm.generate("Explain quantum computing")

# Process individual messages
for message in messages:
    content = llm.message_str(message)
    print(f"Message content: {content}")
```

### Structured Generation

```python  theme={null}
from pydantic import BaseModel
from typing import List, Optional

class CodeReview(BaseModel):
    summary: str
    issues: List[str]
    suggestions: List[str]
    score: int  # 1-10
    approved: bool

# Generate structured code review
review = await llm.generate_structured(
    message="Review this Python function: def factorial(n): return n * factorial(n-1)",
    response_model=CodeReview
)

print(f"Review score: {review.score}")
print(f"Approved: {review.approved}")
```

## Real-World Examples

### Multi-Agent Collaboration

```python  theme={null}
# Research agent
research_agent = Agent(
    name="researcher",
    instruction="You research topics and gather information.",
    server_names=["fetch", "database"]
)

# Analysis agent
analysis_agent = Agent(
    name="analyst",
    instruction="You analyze data and create insights.",
    server_names=["filesystem", "visualization"]
)

async with research_agent, analysis_agent:
    # Research phase
    research_llm = await research_agent.attach_llm(OpenAIAugmentedLLM)
    research_data = await research_llm.generate_str(
        "Research the latest trends in renewable energy"
    )

    # Analysis phase
    analysis_llm = await analysis_agent.attach_llm(AnthropicAugmentedLLM)
    analysis = await analysis_llm.generate_str(
        f"Analyze this research data and create actionable insights: {research_data}"
    )
```

### Content Generation Pipeline

```python  theme={null}
from pydantic import BaseModel

class ContentPlan(BaseModel):
    title: str
    outline: List[str]
    target_length: int
    keywords: List[str]

class BlogPost(BaseModel):
    title: str
    content: str
    meta_description: str
    tags: List[str]

# Content planning
plan = await llm.generate_structured(
    message="Create a content plan for a blog post about sustainable technology",
    response_model=ContentPlan
)

# Content generation
blog_post = await llm.generate_structured(
    message=f"""Write a blog post based on this plan:
    Title: {plan.title}
    Outline: {plan.outline}
    Target length: {plan.target_length} words
    Keywords: {plan.keywords}""",
    response_model=BlogPost
)
```

<CardGroup>
  <Card title="Agent Integration" href="/concepts/agents">
    Learn how agents use augmented LLMs for enhanced capabilities.
  </Card>

  <Card title="MCP Servers" href="/concepts/mcp-servers">
    Understand how MCP servers provide tools and data to augmented LLMs.
  </Card>

  <Card title="Examples" href="https://github.com/lastmile-ai/mcp-agent/tree/main/examples">
    Explore practical examples of augmented LLMs in action.
  </Card>
</CardGroup>


# Configuring Your Application
Source: https://docs.mcp-agent.com/mcp-agent-sdk/core-components/configuring-your-application

Learn how to configure mcp-agent applications

mcp-agent uses YAML configuration files to manage application settings, MCP servers, and model providers.

## Configuration files

Start with two YAML files at the root of your project:

<CardGroup cols={2}>
  <Card title="mcp_agent.config.yaml" icon="gear">
    Application configuration, MCP servers, logging, execution engine, model defaults
  </Card>

  <Card title="mcp_agent.secrets.yaml" icon="key">
    API keys, OAuth credentials, and other secrets (gitignored)
  </Card>
</CardGroup>

See [Specify Secrets](/mcp-agent-sdk/core-components/specify-secrets) for credential management patterns and production tips.

## Basic configuration

Here's a minimal configuration:

<CodeGroup>
  ```yaml mcp_agent.config.yaml theme={null}
  execution_engine: asyncio
  logger:
    transports: [console]
    level: info

  mcp:
    servers:
      fetch:
        command: "uvx"
        args: ["mcp-server-fetch"]

  openai:
    default_model: gpt-4o
  ```

  ```yaml mcp_agent.secrets.yaml theme={null}
  openai:
    api_key: "sk-..."
  ```
</CodeGroup>

## Execution Engine

Choose how your workflows execute:

<Tabs>
  <Tab title="asyncio">
    In-memory execution for development and simple deployments:

    ```yaml  theme={null}
    execution_engine: asyncio
    ```

    Best for:

    * Local development
    * Simple agents
    * Quick prototyping
  </Tab>

  <Tab title="Temporal">
    Durable execution with automatic retries and pause/resume:

    ```yaml  theme={null}
    execution_engine: temporal

    temporal:
      host: localhost:7233
      namespace: default
      task_queue: mcp-agent
    ```

    Best for:

    * Production deployments
    * Long-running workflows
    * Human-in-the-loop agents
  </Tab>
</Tabs>

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

## Logging

Configure logging output and level:

```yaml mcp_agent.config.yaml theme={null}
logger:
  transports: [console, file]  # Output to console and file
  level: info  # debug, info, warning, error
  path: "logs/mcp-agent.jsonl"  # For file transport
```

You can also use dynamic log filenames:

```yaml  theme={null}
logger:
  transports: [file]
  level: debug
  path_settings:
    path_pattern: "logs/mcp-agent-{unique_id}.jsonl"
    unique_id: "timestamp"  # Or "session_id"
    timestamp_format: "%Y%m%d_%H%M%S"
```

[Learn more about Logging →](/mcp-agent-sdk/advanced/logging)

## MCP Servers

Define MCP servers your agents can connect to:

```yaml mcp_agent.config.yaml theme={null}
mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
      description: "Fetch web content"

    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
      description: "Local filesystem access"

    sqlite:
      command: "uvx"
      args: ["mcp-server-sqlite", "--db-path", "data.db"]
      description: "SQLite database operations"
```

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

## Model Providers

Configure your LLM provider. Many examples follow this layout—for instance, the [basic finder agent](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/mcp_basic_agent) sets OpenAI defaults exactly this way.

<Tabs>
  <Tab title="OpenAI">
    ```yaml mcp_agent.config.yaml theme={null}
    openai:
      default_model: gpt-4o
      temperature: 0.7
      max_tokens: 4096
    ```

    ```yaml mcp_agent.secrets.yaml theme={null}
    openai:
      api_key: "sk-..."
    ```
  </Tab>

  <Tab title="Anthropic">
    ```yaml mcp_agent.config.yaml theme={null}
    anthropic:
      default_model: claude-3-5-sonnet-20241022
      temperature: 0.7
      max_tokens: 4096
    ```

    ```yaml mcp_agent.secrets.yaml theme={null}
    anthropic:
      api_key: "sk-ant-..."
    ```
  </Tab>

  <Tab title="Azure OpenAI">
    ```yaml mcp_agent.config.yaml theme={null}
    azure:
      default_model: gpt-4o
      api_version: "2024-02-15-preview"
      azure_endpoint: "https://your-resource.openai.azure.com"
    ```

    ```yaml mcp_agent.secrets.yaml theme={null}
    azure:
      api_key: "..."
    ```
  </Tab>

  <Tab title="AWS Bedrock">
    ```yaml mcp_agent.config.yaml theme={null}
    bedrock:
      default_model: anthropic.claude-3-5-sonnet-20241022-v2:0
      region: us-east-1
    ```

    ```yaml mcp_agent.secrets.yaml theme={null}
    bedrock:
      aws_access_key_id: "..."
      aws_secret_access_key: "..."
    ```
  </Tab>
</Tabs>

## OAuth configuration

Two places control OAuth behaviour:

1. **Global OAuth settings (`settings.oauth`)** configure token storage and callback behaviour (loopback ports, preload timeouts, Redis support).
2. **Per-server auth (`mcp.servers[].auth.oauth`)** specifies client credentials, scopes, and provider overrides.

```yaml mcp_agent.config.yaml theme={null}
oauth:
  token_store:
    backend: redis
    redis_url: ${OAUTH_REDIS_URL}

mcp:
  servers:
    github:
      command: "uvx"
      args: ["mcp-server-github"]
      auth:
        oauth:
          enabled: true
          client_id: ${GITHUB_CLIENT_ID}
          client_secret: ${GITHUB_CLIENT_SECRET}
          redirect_uri_options:
            - "http://127.0.0.1:33418/callback"
          include_resource_parameter: false
```

Pair this with secrets in `mcp_agent.secrets.yaml` or environment variables. For concrete walkthroughs, study the [OAuth basic agent](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/oauth_basic_agent) and the [interactive OAuth tool](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/interactive_tool). The [pre-authorize workflow example](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/pre_authorize) shows how to seed credentials before a background workflow runs.

## Programmatic configuration

You can bypass file discovery by passing a fully-formed `Settings` object (or a path) to `MCPApp`. This is especially useful for tests and scripts that compose configuration dynamically.

```python  theme={null}
from mcp_agent.app import MCPApp
from mcp_agent.config import Settings, OpenAISettings

settings = Settings(
    execution_engine="asyncio",
    openai=OpenAISettings(
        default_model="gpt-4o-mini",
        temperature=0.3,
    ),
)

app = MCPApp(name="dynamic", settings=settings)
```

Because `Settings` extends `BaseSettings`, environment variables still override any fields you set explicitly.

## Configuration discovery

When `MCPApp` starts, it resolves settings in this order:

* `MCP_APP_SETTINGS_PRELOAD` / `MCP_APP_SETTINGS_PRELOAD_STRICT`
* Explicit `settings` argument passed to `MCPApp`
* `mcp_agent.config.yaml` (or `mcp-agent.config.yaml`) discovered in the working directory, parent directories, `.mcp-agent/` folders, or `~/.mcp-agent/`
* `mcp_agent.secrets.yaml` / `mcp-agent.secrets.yaml` merged on top
* Environment variables (including values from `.env`, using `__` for nesting)

Environment variables override file-based values, while the preload option short-circuits everything else—handy for containerised deployments that mount secrets from a vault. [Specify Secrets](/mcp-agent-sdk/core-components/specify-secrets) covers strategies for each stage.

## Environment Variables

You can reference environment variables in configuration:

```yaml mcp_agent.config.yaml theme={null}
openai:
  default_model: ${OPENAI_MODEL:-gpt-4o}  # Default to gpt-4o

temporal:
  host: ${TEMPORAL_HOST:-localhost:7233}
```

<Tip>
  Use environment variables for deployment-specific settings like endpoints and regions, while keeping model choices in the config file.
</Tip>

## Project Structure

Recommended project layout:

```
your-project/
├── agent.py                  # Your agent code
├── mcp_agent.config.yaml     # Application configuration
├── mcp_agent.secrets.yaml    # API keys (gitignored)
├── .gitignore                # Ignore secrets file
├── requirements.txt          # Python dependencies
└── logs/                     # Execution logs
```

Add to `.gitignore`:

```gitignore  theme={null}
mcp_agent.secrets.yaml
logs/
*.log
```

## Complete Configuration Reference

For all available configuration options, see the [Configuration Reference](/reference/configuration).

## Next Steps

<CardGroup cols={2}>
  <Card title="Specify Secrets" icon="key" href="/mcp-agent-sdk/core-components/specify-secrets">
    Learn about secrets management
  </Card>

  <Card title="MCPApp" icon="cube" href="/mcp-agent-sdk/core-components/mcpapp">
    Understand the application context
  </Card>

  <Card title="Agents" icon="robot" href="/mcp-agent-sdk/core-components/agents">
    Create your first agent
  </Card>

  <Card title="Configuration Reference" icon="book" href="/reference/configuration">
    Complete configuration documentation
  </Card>
</CardGroup>


# Connecting to MCP Servers
Source: https://docs.mcp-agent.com/mcp-agent-sdk/core-components/connecting-to-mcp-servers

Learn how to connect to MCP servers using the MCP server registry and connection manager

## Overview

Every `MCPApp` initialises a `ServerRegistry` that knows how to start and authenticate each server defined in `mcp_agent.config.yaml`. The registry works hand in hand with `MCPConnectionManager` to provide two patterns:

* Short-lived connections using `gen_client`, perfect for one-off operations.
* Persistent connections managed by the connection manager, ideal for agents and long-running workflows.

Understanding these two layers lets you control connection reuse, lifecycle, and error handling with precision.

## Inspect configured servers

After `app.run()` the registry is accessible via the context:

```python  theme={null}
async with app.run() as running_app:
    registry = running_app.server_registry
    for name, cfg in registry.registry.items():
        running_app.logger.info(
            "Server configured",
            data={"name": name, "transport": cfg.transport},
        )
```

The registry resolves transports (`stdio`, `sse`, `streamable_http`, `websocket`), applies authentication (`api_key` or OAuth), and exposes helpers such as `register_init_hook`.

## Ephemeral sessions with `gen_client`

Use `gen_client` when you need a connection for the duration of a `with` block. It spins up the server process (for stdio transports), performs initialisation, yields an `MCPAgentClientSession`, and tears everything down automatically—a handy pattern for scripts, CLI utilities, or inspection. The [basic finder agent](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/mcp_basic_agent) uses the same underlying helpers when it initialises an agent.

```python  theme={null}
from mcp_agent.mcp.gen_client import gen_client

async with app.run():
    async with gen_client(
        server_name="fetch",
        server_registry=app.server_registry,
        context=app.context,
    ) as session:
        tools = await session.list_tools()
        print("Fetch tools:", [tool.name for tool in tools.tools])
```

This is the simplest way to script against MCP servers without committing to persistent connections.

## Persistent connections and connection pooling

The `ServerRegistry` owns a `MCPConnectionManager` (`registry.connection_manager`) that maintains long-lived connections in a background task group. You can either interact with it directly or rely on helpers such as `mcp_agent.mcp.gen_client.connect`.

```python  theme={null}
from mcp_agent.mcp.gen_client import connect, disconnect

async with app.run():
    session = await connect("filesystem", app.server_registry, context=app.context)
    try:
        result = await session.list_resources()
        print("Roots:", [r.uri for r in result.resources])
    finally:
        await disconnect("filesystem", app.server_registry)
```

When you need multiple connections simultaneously, open the manager as a context manager to ensure orderly shutdown:

```python  theme={null}
async with app.run():
    async with app.server_registry.connection_manager as manager:
        fetch_conn = await manager.get_server("fetch")
        filesystem_conn = await manager.get_server("filesystem")
        await fetch_conn.session.list_tools()
        await filesystem_conn.session.list_tools()
    # Connections are closed when the block exits
```

## Connection persistence in agents

Agents use the connection manager behind the scenes. Set `connection_persistence=True` (the default) to keep servers warm between tool calls or `False` to close the transport after each request.

```python  theme={null}
agent = Agent(
    name="finder",
    instruction="Use fetch and filesystem tools",
    server_names=["fetch", "filesystem"],
    connection_persistence=True,
    context=app.context,
)
```

Persistent connections dramatically reduce latency when calling the same server repeatedly.

## Aggregating multiple servers

`MCPAggregator` builds a “server-of-servers” using the same registry and connection manager. You can namespace tool calls or expose a merged surface area:

```python  theme={null}
from mcp_agent.mcp.mcp_aggregator import MCPAggregator

async with app.run():
    async with MCPAggregator.create(
        server_names=["fetch", "filesystem"],
        connection_persistence=True,
        context=app.context,
    ) as aggregator:
        await aggregator.list_tools()                # Combined tool view
        await aggregator.call_tool("fetch_fetch", {"url": "https://example.com"})
        await aggregator.call_tool("read_text_file", {"path": "README.md"})
```

This pattern mirrors the [`examples/basic/mcp_server_aggregator`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/mcp_server_aggregator) sample and is commonly used when turning an entire app into a single MCP server.

## OAuth-aware connections

When server definitions include `auth.oauth`, the registry and connection manager automatically coordinate with the app’s token manager. The OAuth examples highlight three recurring patterns:

* [`examples/basic/oauth_basic_agent`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/oauth_basic_agent) – an agent maintains persistent connections to the GitHub MCP server using the client-only loopback flow.
* [`examples/oauth/interactive_tool`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/interactive_tool) – a client opens a temporary `gen_client` session, receives an `auth/request`, and walks through the browser login.
* [`examples/oauth/pre_authorize`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/pre_authorize) – tokens are seeded before an asynchronous workflow runs so the background execution never needs interactive auth.

In each case, you get the same `ClientSession` interface; the difference lies in how tokens are acquired and stored.

## Initialisation hooks and authentication

You can register custom logic that runs immediately after a server initialises. It is perfect for seeding credentials, warming caches, or performing health checks.

```python  theme={null}
def after_start(session, auth):
    session.logger.info("Server ready", data={"auth": bool(auth)})

app.server_registry.register_init_hook("fetch", after_start)
```

When a server declares OAuth configuration (`mcp.servers[].auth.oauth`), `MCPApp` automatically injects an `OAuthHttpxAuth` handler so `MCPConnectionManager` can obtain and refresh tokens using the shared `TokenManager`. This means you do not need to ship long-lived access tokens in your config.

## Error handling & retries

* `MCPConnectionManager` keeps track of connection health and will surface errors via logs (`ProgressAction.FATAL_ERROR`) without crashing your application.
* Call `disconnect_all()` or `close()` if you want to force reconnection after rotating credentials.
* When a connection fails during initialisation, any awaiting `get_server` call unblocks with an exception so that workflows can decide whether to retry or degrade gracefully.

[Deep dive into MCP Servers →](/mcp-agent-sdk/core-components/mcp-servers)


# Execution Engines
Source: https://docs.mcp-agent.com/mcp-agent-sdk/core-components/execution-engine

Understanding execution engines and executors in mcp-agent

## Overview

mcp-agent provides two execution engines that determine how agent workflows are executed and managed. Each engine offers different capabilities for reliability, persistence, and deployment scenarios.

## Execution Engines

### asyncio Engine

The asyncio engine runs workflows in-memory using Python's native async/await capabilities.

**Characteristics:**

* In-memory execution
* No external dependencies
* Fast startup and iteration
* Best for development and simple deployments
* State lost on process restart

**Configuration:**

```yaml  theme={null}
execution_engine: asyncio
```

**Use cases:**

* Local development
* Quick prototyping
* Stateless operations
* Single-node deployments

### Temporal Engine

The Temporal engine provides durable workflow execution with automatic state persistence.

**Characteristics:**

* Durable execution across restarts
* Automatic retry with exponential backoff
* Workflow history and replay
* Distributed execution support
* Requires Temporal server

**Configuration:**

```yaml  theme={null}
execution_engine: temporal
temporal:
  host: "localhost:7233"
  namespace: "default"
  task_queue: "mcp-agent"
```

**Use cases:**

* Production deployments
* Long-running workflows
* Critical operations requiring reliability
* Multi-node deployments
* Workflows requiring pause/resume

📌 **Example:** The [Temporal workflow gallery](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal) showcases orchestrator, router, and evaluator/optimizer patterns running on this engine.

## Executors

Executors are the runtime components that actually execute workflows within an engine.

### AsyncioExecutor

Handles workflow execution for the asyncio engine:

```python  theme={null}
from mcp_agent.executor.executor import AsyncioExecutor

async def greet(name: str) -> str:
    return f"Hi {name}"

executor = AsyncioExecutor()
result = await executor.execute(greet, "Ada")
print(result)  # "Hi Ada"
```

**Features:**

* Direct Python function execution
* Native async/await support
* Minimal overhead

See it in action in the [basic workflows examples](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows) where tasks run entirely in-process.

### TemporalExecutor

Manages workflow execution for the Temporal engine:

```python  theme={null}
from mcp_agent.executor.temporal import TemporalExecutor
from mcp_agent.config import TemporalSettings

executor = TemporalExecutor(config=TemporalSettings(
    host="localhost:7233",
    namespace="default",
    task_queue="mcp-agent",
))
handle = await executor.start_workflow("ResearchWorkflow", {"topic": "LLMs"})
result = await handle.result()
```

**Features:**

* Workflow versioning
* Activity retries
* Distributed execution
* Workflow queries and signals

The [`examples/oauth/pre_authorize`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/pre_authorize) project combines this executor with OAuth-aware workflows.

## Choosing an Execution Engine

### Development Phase

Use asyncio engine during development:

* Fast iteration cycles
* No infrastructure requirements
* Immediate feedback
* Simple debugging

### Production Phase

Consider Temporal engine for production:

* Workflow reliability
* Automatic failure handling
* Audit trail via workflow history
* Horizontal scaling

## Execution Context

Both engines provide an execution context to workflows:

```python  theme={null}
@app.workflow
async def my_workflow(ctx: WorkflowContext, params: dict):
    # Access execution context
    workflow_id = ctx.workflow_id
    run_id = ctx.run_id
    
    # Engine-specific features
    if ctx.engine == "temporal":
        # Temporal-specific operations
        await ctx.sleep(timedelta(hours=1))
    
    return result
```

## Engine-Specific Features

### asyncio Features

* **Direct execution**: Workflows run as standard Python functions
* **Memory state**: State maintained in process memory
* **Simple cancellation**: Standard asyncio cancellation

### Temporal Features

* **Workflow replay**: Deterministic replay from history
* **Signals**: Send data to running workflows
* **Queries**: Query workflow state without affecting execution
* **Child workflows**: Spawn and manage child workflow instances
* **Timers**: Durable sleep and timeouts
* **Activities**: Retryable units of work

## Migration Between Engines

Workflows written for mcp-agent can run on either engine without modification:

```python  theme={null}
# This workflow runs on both engines
@app.workflow
async def portable_workflow(ctx: WorkflowContext, input: dict):
    agent = Agent(
        name="researcher",
        instruction="Research the topic",
        server_names=["fetch"]
    )
    
    async with agent:
        llm = await agent.attach_llm(OpenAIAugmentedLLM)
        result = await llm.generate_str(input["query"])
    
    return result
```

## Performance Considerations

### asyncio Engine

* **Latency**: Microseconds for workflow start
* **Throughput**: Limited by single process
* **Memory**: All state in RAM
* **Reliability**: No persistence

### Temporal Engine

* **Latency**: Milliseconds for workflow start
* **Throughput**: Horizontally scalable
* **Memory**: State persisted to database
* **Reliability**: Survives crashes and restarts

## Configuration Examples

### Basic asyncio Setup

```yaml  theme={null}
execution_engine: asyncio
logger:
  level: info
```

### Production Temporal Setup

```yaml  theme={null}
execution_engine: temporal
temporal:
  host: "temporal.production.internal:7233"
  namespace: "production"
  task_queue: "agent-workflows"
  worker_count: 4
  max_concurrent_activities: 20
```

## Accessing the executor in an application

`MCPApp` exposes the active executor and engine selection:

```python  theme={null}
async with app.run() as running_app:
    executor = running_app.executor
    print(executor.execution_engine)  # "asyncio" or "temporal"
```

You typically call high-level helpers (`workflow.execute()`, `executor.start_workflow`) rather than invoking executor methods directly, but the property is available when you need advanced control or diagnostics.

## Next Steps

* [Temporal Advanced Features](/advanced/temporal)
* [Workflow Patterns](/workflows/overview)
* [Configuration Guide](/configuration)


# MCPApp
Source: https://docs.mcp-agent.com/mcp-agent-sdk/core-components/mcpapp

The central application context for mcp-agent

## Overview

`MCPApp` is the orchestration layer for every mcp-agent project. It boots the global `Context`, loads configuration, wires in logging and tracing, manages MCP server connections, and exposes workflows and tools to clients. If you think of agents, LLMs, and workflows as the “workers”, `MCPApp` is the runtime that keeps them coordinated.

<CardGroup cols={2}>
  <Card title="Configuration loader" icon="gear">
    Discovers `mcp_agent.config.yaml`, merges `mcp_agent.secrets.yaml`, `.env`, and environment overrides, or uses explicit `Settings`
  </Card>

  <Card title="Runtime context" icon="stack">
    Initialises the global `Context` with registries, executors, token stores, tracing, and logging
  </Card>

  <Card title="MCP integration" icon="plug">
    Provides a FastMCP server façade so workflows and tools can be exposed over MCP
  </Card>

  <Card title="Decorator hub" icon="wand-magic-sparkles">
    Supplies decorators that turn Python callables and classes into durable workflows and tools
  </Card>
</CardGroup>

## Quick start

The fastest way to use `MCPApp` is the pattern followed in the [finder agent example](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/mcp_basic_agent):

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

app = MCPApp(name="research_assistant")

async def main():
    async with app.run() as running_app:
        logger = running_app.logger
        context = running_app.context
        logger.info("App ready", data={"servers": list(context.server_registry.registry)})
        # build agents, workflows, etc.
```

* `app.run()` initialises the context and cleans it up automatically.
* `app.initialize()` / `app.cleanup()` are still available for advanced CLI or testing flows.
* Keep one `MCPApp` per process; share it across agents, workflows, and custom tasks.

You can see this pattern reused in examples such as [mcp\_server\_aggregator](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/mcp_server_aggregator) and the OAuth samples.

## Key properties

Once initialised you gain access to the runtime building blocks via the `MCPApp` instance:

* `app.context`: the shared `Context` object containing registries, token manager, `MCPApp` reference, and request helpers.
* `app.config`: the resolved `Settings` model.
* `app.logger`: a structured logger that automatically injects the session id and context.
* `app.server_registry`: the `ServerRegistry` that tracks configured MCP servers.
* `app.executor`: the active execution backend (`AsyncioExecutor` or `TemporalExecutor`).
* `app.engine`: shorthand for `app.executor.execution_engine`.
* `app.mcp`: the FastMCP server instance backing this application (when created).

These properties make it straightforward to inspect configuration, open ephemeral MCP sessions, or schedule workflows inside your own code.

## Supplying configuration explicitly

`MCPApp` accepts multiple configuration entrypoints:

* `settings=None` (default) discovers config/secrets automatically.
* `settings="/path/to/mcp_agent.config.yaml"` loads an explicit file.
* `settings=Settings(...)` reuses an existing `Settings` instance (for example when you derive from environment variables at runtime).

Any constructor keyword arguments augment the runtime:

```python  theme={null}
from mcp_agent.app import MCPApp
from mcp_agent.config import Settings, OpenAISettings
from mcp_agent.human_input.handler import console_input_callback

app = MCPApp(
    name="grader",
    description="Grade essays with human-in-the-loop review",
    settings=Settings(openai=OpenAISettings(default_model="gpt-4o-mini")),
    human_input_callback=console_input_callback,
    signal_notification=lambda signal: print(f"Workflow waiting on {signal}"),
)
```

Common constructor hooks:

* `human_input_callback` exposes human input as a tool.
* `elicitation_callback` forwards elicitation responses from MCP clients.
* `signal_notification` surfaces Temporal/asyncio workflow signal waits (great for dashboards).
* `model_selector`: provide a custom `ModelSelector` implementation.
* `session_id`: override the generated session identifier.

## Automatic subagent loading

When `settings.agents.enabled` is true, the app automatically discovers `AgentSpec` definitions from the configured search paths (and optional inline definitions) via `load_agent_specs_from_dir`. This creates a pool of reusable subagents that can be fetched inside workflows or factories without manual registration.

```yaml  theme={null}
agents:
  enabled: true
  search_paths:
    - "./agents"
    - "~/.mcp-agent/agents"
```

Discovered specs are available on `app.context.loaded_subagents`.

## Observability and credentials

During initialisation `MCPApp`:

* Configures structured logging and progress reporting based on `settings.logger`.
* Enables tracing when `settings.otel.enabled` is true, flushing exporters safely during cleanup.
* Creates the shared `TokenManager` and `TokenStore` when OAuth is configured (`settings.oauth`), allowing downstream MCP servers to participate in delegated auth.
* Installs a token counter when tracing is enabled so you can query usage (`await app.get_token_summary()`).

### OAuth and delegated auth

`MCPApp`’s OAuth integration is what powers the GitHub flows in the [OAuth basic agent](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/oauth_basic_agent) and the server/client samples under [`examples/oauth`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth):

* If a server declares `auth.oauth`, the app injects `OAuthHttpxAuth` so connections can request tokens on demand.
* Pre-seeded tokens (for example via `workflows-store-credentials`) are written to the configured token store (memory or Redis).
* `app.context.token_manager` and `app.context.token_store` expose the runtime handles when you need custom automation.

See [Specify Secrets](/mcp-agent-sdk/core-components/specify-secrets) for credential storage options and links to the reference examples.

## Decorator toolkit

`MCPApp` is the home for all decorators that transform plain Python into MCP-ready workflows and tools:

* `@app.workflow`: register a workflow class (e.g. for Temporal orchestration).
* `@app.workflow_run`: mark the entrypoint method on a workflow.
* `@app.workflow_task`: declare reusable activities/tasks that work across engines.
* `@app.workflow_signal`: register signal handlers (Temporal-compatible).
* `@app.tool`: expose a function as a synchronous MCP tool (with auto-generated workflow bindings).
* `@app.async_tool`: expose a long-running tool that returns workflow handles.

When you export an MCP server (`create_mcp_server_for_app`), mcp-agent automatically emits additional tools like `workflows-run` and `workflows-get_status` for every decorated workflow.

## Running as an MCP server

`MCPApp` pairs with FastMCP to expose your application as an MCP server:

```python  theme={null}
from mcp_agent.mcp.server import create_mcp_server_for_app

async def main():
    async with app.run():
        server = create_mcp_server_for_app(app)
        await server.run_stdio_async()
```

You can also supply an existing `FastMCP` instance via the `mcp` parameter to piggyback on a shared server or embed the app into another MCP host.

## Integrating with agents and workflows

`app.context.server_registry` grants access to the configured MCP servers. Agents created inside the app automatically reuse the same registry and connection manager, and workflows scheduled through `app.executor` inherit the same `Context`.

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

async with app.run():
    agent = Agent(
        name="finder",
        instruction="Use fetch + filesystem to answer questions",
        server_names=["fetch", "filesystem"],
        context=app.context,
    )
    async with agent:
        llm = await agent.attach_llm(OpenAIAugmentedLLM)
        summary = await llm.generate_str("Find the README and summarise it.")
```

Because everything shares the same `Context`, server connections, logging metadata, token counters, and tracing spans remain consistent across the stack.

## Related reading

* [Configuring Your Application](/mcp-agent-sdk/core-components/configuring-your-application)
* [Connecting to MCP Servers](/mcp-agent-sdk/core-components/connecting-to-mcp-servers)
* [Workflows and Decorators](/mcp-agent-sdk/core-components/workflows)


# Specify Secrets
Source: https://docs.mcp-agent.com/mcp-agent-sdk/core-components/specify-secrets

Manage API keys and sensitive credentials securely

## Why secrets matter

Every `MCPApp` run loads a `Settings` model that merges configuration, secrets, and environment overrides. Secrets unlock LLM providers, authenticated MCP servers, OAuth clients, and third-party APIs. Treat them as production-grade credentials across local dev, CI pipelines, and deployed agents.

## Quick start: secrets file

Use the gitignored secrets file for iterative development:

```yaml mcp_agent.secrets.yaml theme={null}
openai:
  api_key: "sk-..."

anthropic:
  api_key: "sk-ant-..."

temporal:
  api_key: "..."
```

Keep both `mcp_agent.secrets.yaml` and `mcp-agent.secrets.yaml` ignored—mcp-agent will discover either casing automatically.

📌 **Try it:** the [basic finder agent example](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/mcp_basic_agent) expects credentials in this file (or matching environment variables).

## Environment variables and `.env`

`Settings` uses Pydantic’s nested delimiter (`__`) and automatically loads a `.env` file in the working directory. Any environment variable overrides the same key from config or secrets:

```bash  theme={null}
export OPENAI_API_KEY="sk-..."
export MCP_AGENT__OPENAI__DEFAULT_MODEL="gpt-4o-mini"
export MCP_AGENT__MCP__SERVERS__FETCH__AUTH__API_KEY="..."
```

You can reference these variables directly inside the config file with `${VAR_NAME}` or rely on the automatic override behaviour.

Tip: See the [token counter example](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/token_counter) for a project that mixes `.env` overrides with secrets files.

## Managing OAuth credentials

When you connect to OAuth-protected MCP servers, supply the client credentials in your secrets file or environment:

```yaml mcp_agent.secrets.yaml theme={null}
mcp:
  servers:
    github:
      auth:
        oauth:
          client_id: "github-client-id"
          client_secret: "github-client-secret"
```

Combine this with the server configuration in `mcp_agent.config.yaml` to enable the OAuth flow. The [`oauth_basic_agent` example](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/oauth_basic_agent) demonstrates the client-only loopback pattern for GitHub, while the [`oauth/interactive_tool`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/interactive_tool) sample shows a full authorization-code flow between an MCP client and server.

### Token storage backends

At startup, `MCPApp` initialises a token manager based on your config (`settings.oauth.token_store`). By default tokens live in memory; switch to Redis by adding:

```yaml mcp_agent.config.yaml theme={null}
oauth:
  token_store:
    backend: redis
    redis_url: ${OAUTH_REDIS_URL}
```

This mirrors the Redis instructions in the OAuth examples and keeps tokens durable across restarts. The [`oauth/pre_authorize` workflow example](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/pre_authorize) seeds tokens ahead of a background workflow so it never has to pop open a browser.

## Discovery & precedence

mcp-agent reads secrets and overrides in the following order (last writer wins):

* `MCP_APP_SETTINGS_PRELOAD` / `MCP_APP_SETTINGS_PRELOAD_STRICT`
* Explicit `Settings` instance passed to `MCPApp`
* `mcp_agent.config.yaml` (or `mcp-agent.config.yaml`)
* `mcp_agent.secrets.yaml` / `mcp-agent.secrets.yaml`
* Environment variables (including values from `.env`)

If `MCP_APP_SETTINGS_PRELOAD` is set, its YAML payload is treated as the complete settings document and no other sources are consulted.

## Advanced: preloading secrets without files

`MCP_APP_SETTINGS_PRELOAD` is the recommended production path when you cannot store plaintext credentials on disk. Provide a YAML or JSON string that serialises the `Settings` model:

```bash  theme={null}
export MCP_APP_SETTINGS_PRELOAD="$(python - <<'PY'
from pydantic_yaml import to_yaml_str
from mcp_agent.config import Settings, OpenAISettings
print(to_yaml_str(Settings(openai=OpenAISettings(api_key='sk-prod-...'))))
PY
)"
```

* Set `MCP_APP_SETTINGS_PRELOAD_STRICT=true` to fail fast if the payload cannot be parsed.
* Preload also supports non-secret overrides (for example, swapping model defaults).

## Best practices

* Rotate provider keys and refresh `MCP_APP_SETTINGS_PRELOAD` values via your secret manager.
* Prefer environment variables or preload for CI/CD pipelines.
* Avoid logging secret values—mcp-agent’s structured logger redacts known fields, but additional care may be required for custom data structures.
* Treat secrets files as developer convenience only; they should not ship with containers or production artefacts.

[More configuration options →](/mcp-agent-sdk/core-components/configuring-your-application)


# Workflows and Decorators
Source: https://docs.mcp-agent.com/mcp-agent-sdk/core-components/workflows

Understanding the Workflow class and decorator-based tool definition in mcp-agent

## Overview

mcp-agent gives you two complementary ways to expose agent behaviour:

1. **Decorator-based tools** – mark a plain Python function with `@app.tool` or `@app.async_tool` to expose it as an MCP tool. This is the quickest way to add synchronous or long-running behaviour to your app.
2. **Workflow classes** – build stateful, structured flows by subclassing `Workflow[T]`. Workflows give you fine-grained control over orchestration, retries, and Temporal integration.

Both options register MCP tools automatically, so any MCP client can invoke them. The high-level “workflow patterns” in [`examples/workflows`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows) (parallel, router, orchestrator, etc.) are built using these same primitives—they are patterns, not the `Workflow` base class itself.

The rest of this page walks through the decorators first (because most apps start there) and then dives into the `Workflow` class.

## Decorator-based tools

### `@app.tool` – synchronous tools

Use `@app.tool` when the work can complete within a single MCP call. The return value is sent straight back to the client—no polling required.

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

app = MCPApp(name="utility_agent")

@app.tool
async def calculate_sum(numbers: List[float]) -> float:
    """Calculate the sum of a list of numbers."""
    return sum(numbers)

@app.tool(name="get-weather")
async def get_weather(
    city: str,
    units: str = "celsius",
    app_ctx: Optional[Context] = None,
) -> dict:
    if app_ctx:
        app_ctx.logger.info("Fetching weather", data={"city": city})
    return await fetch_weather_api(city, units)
```

Key points:

* Works great for quick operations or simple glue code.
* You can accept an optional `app_ctx: Context` parameter to access logging, server registry, etc.
* The tool result is serialised and returned to the caller immediately.

### `@app.async_tool` – long-running tools

Agents often need to run tasks that take longer than an MCP request allows (multi-step research, human-in-the-loop flows, durable Temporal runs). Decorate those entry points with `@app.async_tool`:

```python  theme={null}
@app.async_tool(name="analyze-document")
async def analyze_document_async(
    document_url: str,
    analysis_type: str = "summary",
    app_ctx: Optional[Context] = None,
) -> dict:
    workflow = DocumentAnalysisWorkflow()
    handle = await app_ctx.executor.start_workflow(
        workflow,
        {"url": document_url, "type": analysis_type},
    )
    return {"workflow_id": workflow.id, "run_id": handle.id}
```

`@app.async_tool` starts a workflow in the background and returns identifiers that clients can poll via the built-in `workflows-get_status` tool. This pattern keeps your agent responsive even when the underlying work takes minutes or requires human decisions.

> **Tip:** Agent servers rely heavily on these decorators—see [Agent Servers](/mcp-agent-sdk/mcp/agent-as-mcp-server) for end-to-end examples.

## The Workflow Class

The `Workflow[T]` base class lets you model multi-step or stateful logic while still exposing an MCP tool. Workflows are most useful when you need retries, shared state, or tight integration with the execution engine (asyncio or Temporal).

### Basic workflow definition

```python  theme={null}
from mcp_agent.executor.workflow import Workflow, WorkflowResult

# Assume `read_file` / `summarise` are helper functions you provide.

@app.workflow
class SummariseFile(Workflow[str]):
    @app.workflow_run
    async def run(self, path: str) -> WorkflowResult[str]:
        content = await read_file(path)
        summary = await summarise(content)
        return WorkflowResult(value=summary)
```

Decorate the class with `@app.workflow` and the entry point with `@app.workflow_run`. Whatever you return from the method becomes the MCP tool result.

### Useful workflow features

* Access `self.context` for logging, MCP connections, and configuration.
* Store reusable helpers or caches on `self` inside `__init__`.
* Raise exceptions to trigger retries (Temporal) or propagate errors to the caller.
* Combine with `@app.workflow_task` / `@app.workflow_signal` when you need durable activities or signal handlers.

See the sections below for more elaborate compositions.

## Workflow patterns (examples/workflows)

The repository has an [`examples/workflows`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows) directory that demonstrates higher-level agent patterns: router, parallel fan-out, orchestrator, evaluator/optimizer, and more. These samples compose agents and AugmentedLLMs with helpers from `mcp_agent.workflows.factory`. They do **not** correspond one-to-one with the `Workflow` base class above—they are ready-made orchestration patterns you can adopt or customise.

Use the patterns when you want opinionated orchestration, and drop down to the `Workflow` class (or `@app.async_tool`) when you need bespoke control flow.

## Advanced Workflow Patterns

### Workflow Composition

Compose complex workflows from simpler ones:

```python  theme={null}
@app.workflow
class CompositeWorkflow(Workflow[dict]):
    @app.workflow_run
    async def run(self, request: dict) -> WorkflowResult[dict]:
        # Run sub-workflows
        step1 = DataFetchWorkflow()
        data = await step1.run(request["source"])
        
        step2 = DataProcessWorkflow()
        processed = await step2.run(data.value)
        
        step3 = ReportGenerationWorkflow()
        report = await step3.run(processed.value)
        
        return WorkflowResult(value={
            "data": data.value,
            "processed": processed.value,
            "report": report.value
        })
```

### Workflow with Agents

Integrate agents into workflows:

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

@app.workflow
class AgentWorkflow(Workflow[str]):
    @app.workflow_run
    async def run(self, task: str) -> WorkflowResult[str]:
        # Create specialized agent
        agent = Agent(
            name="researcher",
            instruction="Research thoroughly and provide detailed analysis.",
            server_names=["fetch", "filesystem"]
        )
        
        async with agent:
            # Attach LLM
            llm = await agent.attach_llm(OpenAIAugmentedLLM)
            
            # Execute task
            result = await llm.generate_str(task)
            
            return WorkflowResult(value=result)
```

### Parallel Workflow Execution

Execute multiple workflows in parallel:

```python  theme={null}
import asyncio

@app.workflow
class ParallelWorkflow(Workflow[dict]):
    @app.workflow_run
    async def run(self, tasks: List[str]) -> WorkflowResult[dict]:
        # Create workflow instances
        workflows = [
            TaskWorkflow() for _ in tasks
        ]
        
        # Run in parallel
        results = await asyncio.gather(*[
            w.run(task) for w, task in zip(workflows, tasks)
        ])
        
        # Combine results
        combined = {
            f"task_{i}": r.value 
            for i, r in enumerate(results)
        }
        
        return WorkflowResult(value=combined)
```

### Stateful Workflows

Maintain state across workflow executions:

```python  theme={null}
@app.workflow
class StatefulWorkflow(Workflow[dict]):
    def __init__(self):
        super().__init__()
        self.state = {}
    
    @app.workflow_run
    async def run(self, action: dict) -> WorkflowResult[dict]:
        action_type = action.get("type")
        
        if action_type == "set":
            self.state[action["key"]] = action["value"]
            return WorkflowResult(value={"status": "set"})
        
        elif action_type == "get":
            value = self.state.get(action["key"])
            return WorkflowResult(value={"value": value})
        
        elif action_type == "clear":
            self.state.clear()
            return WorkflowResult(value={"status": "cleared"})
        
        return WorkflowResult(value=self.state)
```

## Temporal Integration

Workflows seamlessly support Temporal for durable execution:

```python  theme={null}
# Configure for Temporal
app = MCPApp(
    name="temporal_agent",
    settings=Settings(
        execution_engine="temporal",
        temporal=TemporalSettings(
            host="localhost",
            port=7233,
            namespace="default",
            task_queue="mcp-agent"
        )
    )
)

@app.workflow
class DurableWorkflow(Workflow[str]):
    @app.workflow_run
    async def run(self, task: str) -> WorkflowResult[str]:
        # This workflow is now durable
        # It can be paused, resumed, and retried
        
        # Wait for signal (human-in-the-loop)
        await app.context.executor.signal_bus.wait_for_signal(
            Signal(name="approve", workflow_id=self.id)
        )
        
        # Continue after approval
        result = await self.process_with_approval(task)
        return WorkflowResult(value=result)
```

## MCP Server Integration

### Exposing Workflows as MCP Tools

Workflows and tools are automatically exposed when creating an MCP server:

```python  theme={null}
from mcp_agent.mcp.server import create_mcp_server_for_app

# Define workflows and tools
@app.workflow
class MyWorkflow(Workflow[str]):
    @app.workflow_run
    async def run(self, input: str) -> WorkflowResult[str]:
        return WorkflowResult(value=f"Processed: {input}")

@app.tool
async def my_tool(param: str) -> str:
    return f"Tool result: {param}"

# Create MCP server
async def main():
    async with app.run():
        mcp_server = create_mcp_server_for_app(app)
        
        # Available tools:
        # - workflows-list
        # - workflows-MyWorkflow-run
        # - workflows-get_status
        # - my_tool
        
        await mcp_server.run_stdio_async()
```

### Tool Discovery

MCP clients can discover available tools:

```python  theme={null}
# From MCP client perspective
tools = await server.list_tools()
for tool in tools:
    print(f"Tool: {tool.name}")
    print(f"Description: {tool.description}")
    print(f"Parameters: {tool.input_schema}")
```

## Best Practices

<AccordionGroup>
  <Accordion title="Choose the Right Abstraction">
    * Use `@app.tool` for simple, stateless operations
    * Use `@app.async_tool` for long-running operations that need polling
    * Use `Workflow` class for complex, multi-step processes
  </Accordion>

  <Accordion title="Type Hints and Documentation">
    Always provide type hints and docstrings:

    ```python  theme={null}
    @app.tool
    async def process_data(
        data: dict,
        options: Optional[dict] = None
    ) -> dict:
        """
        Process data with optional transformations.
        
        Args:
            data: Input data to process
            options: Optional processing options
            
        Returns:
            Processed data dictionary
        """
        # Implementation
    ```
  </Accordion>

  <Accordion title="Error Handling">
    Handle errors gracefully:

    ```python  theme={null}
    @app.workflow
    class SafeWorkflow(Workflow[str]):
        @app.workflow_run
        async def run(self, input: str) -> WorkflowResult[str]:
            try:
                result = await self.process(input)
                return WorkflowResult(value=result)
            except Exception as e:
                logger.error(f"Processing failed: {e}")
                return WorkflowResult(
                    value=None,
                    error=str(e)
                )
    ```
  </Accordion>

  <Accordion title="Resource Management">
    Use context managers for resources:

    ```python  theme={null}
    @app.workflow
    class ResourceWorkflow(Workflow[str]):
        @app.workflow_run
        async def run(self, query: str) -> WorkflowResult[str]:
            async with self.get_database() as db:
                result = await db.query(query)
                return WorkflowResult(value=result)
    ```
  </Accordion>

  <Accordion title="Logging and Observability">
    Use structured logging:

    ```python  theme={null}
    @app.tool
    async def monitored_tool(input: str, app_ctx: Optional[Context] = None) -> str:
        if app_ctx:
            logger = app_ctx.logger
            logger.info("Tool started", data={"input": input})
            
            try:
                result = await process(input)
                logger.info("Tool completed", data={"result_length": len(result)})
                return result
            except Exception as e:
                logger.error("Tool failed", data={"error": str(e)})
                raise
    ```
  </Accordion>
</AccordionGroup>

## Testing Workflows

Test your workflows locally:

```python  theme={null}
import asyncio
import pytest

@pytest.mark.asyncio
async def test_workflow():
    app = MCPApp(name="test_app")
    
    @app.workflow
    class TestWorkflow(Workflow[str]):
        @app.workflow_run
        async def run(self, input: str) -> WorkflowResult[str]:
            return WorkflowResult(value=input.upper())
    
    async with app.run():
        workflow = TestWorkflow()
        result = await workflow.run("hello")
        assert result.value == "HELLO"
```

## Migration Guide

### From Functions to Tools

```python  theme={null}
# Before: Plain function
async def calculate(x: int, y: int) -> int:
    return x + y

# After: MCP tool
@app.tool
async def calculate(x: int, y: int) -> int:
    """Calculate sum of two numbers."""
    return x + y
```

### From Scripts to Workflows

```python  theme={null}
# Before: Script
async def main():
    data = await fetch_data()
    processed = await process_data(data)
    await save_results(processed)

# After: Workflow
@app.workflow
class DataPipeline(Workflow[dict]):
    @app.workflow_run
    async def run(self, source: str) -> WorkflowResult[dict]:
        data = await self.fetch_data(source)
        processed = await self.process_data(data)
        await self.save_results(processed)
        return WorkflowResult(value=processed)
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Workflow Patterns" icon="diagram-project" href="/workflows/overview">
    Explore pre-built workflow patterns
  </Card>

  <Card title="Agent Server" icon="server" href="/cloud/agent-server">
    Deploy workflows as MCP servers
  </Card>

  <Card title="Temporal Integration" icon="clock" href="/advanced/temporal">
    Add durability with Temporal
  </Card>

  <Card title="Examples" icon="code" href="https://github.com/lastmile-ai/mcp-agent/tree/main/examples">
    See workflows in action
  </Card>
</CardGroup>


# Build Your Own Pattern
Source: https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/build-your-own

Compose custom agent workflows from the core building blocks

mcp-agent patterns are deliberately composable. You can mix routers, parallel fan-outs, evaluators, orchestrators, and plain Python callables to create flows that match your product requirements—without authoring new workflow classes.

## Building blocks recap

* [`create_llm(...)`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/factory.py#L63) – wrap an `AgentSpec` in an AugmentedLLM tied to a provider (OpenAI, Anthropic, Azure, Google, Bedrock, Ollama).
* [`create_router_llm(...)`](/mcp-agent-sdk/effective-patterns/router) / `create_router_embedding(...)` – dispatch requests to the best specialist.
* [`create_intent_classifier_llm(...)`](/mcp-agent-sdk/effective-patterns/intent-classifier) – bucket requests before routing.
* [`create_parallel_llm(...)`](/mcp-agent-sdk/effective-patterns/map-reduce) – run multiple workers in parallel and aggregate their outputs.
* [`create_evaluator_optimizer_llm(...)`](/mcp-agent-sdk/effective-patterns/evaluator-optimizer) – iterate until a reviewer approves the response.
* [`create_orchestrator(...)`](/mcp-agent-sdk/effective-patterns/planner) – break complex objectives into sequenced steps.
* [`create_deep_orchestrator(...)`](/mcp-agent-sdk/effective-patterns/deep-research) – add knowledge extraction, policy engines, and budgets.
* [`create_swarm(...)`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/factory.py#L501) – OpenAI/Anthropic-compatible handoffs between agents.
* [`load_agent_specs_from_dir(...)`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/factory.py#L553) – hydrate agents from YAML/JSON specs.

## Design playbook

1. **Model your specialists** as `AgentSpec` (name, instruction, tool access). Keep prompts short and behaviour-specific.
2. **Pick a routing strategy**: intent classifier for lightweight gating, router for multi-skill dispatch, or orchestrator for complex plans.
3. **Layer guardrails**: wrap high-risk steps in an evaluator-optimizer loop, or add policy agents inside an orchestrator step.
4. **Add determinism**: integrate `fan_out_functions` for repeatable checks or use embedding routers for fixed scoring.
5. **Expose the composition** with `@app.tool` / `@app.async_tool` so MCP clients can call it as a single tool.
6. **Instrument** with the token counter (`await workflow.get_token_node()`) and tracing (`otel.enabled: true`) before shipping.

## Example: router ➝ parallel research ➝ evaluator

```python  theme={null}
from mcp_agent.app import MCPApp
from mcp_agent.workflows.factory import (
    AgentSpec,
    create_evaluator_optimizer_llm,
    create_parallel_llm,
    create_router_llm,
)

app = MCPApp(name="composed_pattern")

# Cache long-lived components so we don't recreate them per request.
router = None
parallel_research = None
research_loop = None

@app.async_tool(name="answer_question")
async def answer(request: str) -> str:
    global router, parallel_research, research_loop
    async with app.run() as running_app:
        ctx = running_app.context

        if router is None:
            router = await create_router_llm(
                name="triage",
                agents=[
                    AgentSpec(name="qa", instruction="Answer factual questions concisely."),
                    AgentSpec(
                        name="analysis",
                        instruction="Perform deep research with citations before answering.",
                    ),
                ],
                provider="openai",
                context=ctx,
            )

        if parallel_research is None:
            parallel_research = create_parallel_llm(
                name="research_parallel",
                fan_in=AgentSpec(
                    name="aggregator",
                    instruction="Blend researcher outputs into a single structured brief.",
                ),
                fan_out=[
                    AgentSpec(
                        name="news",
                        instruction="Search recent press releases.",
                        server_names=["fetch"],
                    ),
                    AgentSpec(
                        name="financials",
                        instruction="Lookup filings and key metrics.",
                        server_names=["fetch"],
                    ),
                ],
                context=ctx,
            )

        if research_loop is None:
            research_loop = create_evaluator_optimizer_llm(
                name="research_with_qc",
                optimizer=parallel_research,
                evaluator=AgentSpec(
                    name="editor",
                    instruction=(
                        "Score the brief from 1-5. Demand improvements if it lacks citations, "
                        "actionable insights, or policy compliance."
                    ),
                ),
                min_rating=4,
                max_refinements=3,
                context=ctx,
            )

        decision = await router.route(request, top_k=1)
        top = decision[0]

        if top.category == "agent" and top.result.name == "analysis":
            return await research_loop.generate_str(request)

        if top.category == "agent":
            async with top.result:
                return await top.result.generate_str(request)

        # Fallback: let the router destination handle it directly
        return await top.result.generate_str(request)
```

Highlights:

* Router, parallel workflow, and evaluator are created once and reused across requests.
* The evaluator-loop wraps the parallel workflow, so quality checks happen before the response leaves the system.
* The entire composition is exposed as an MCP tool via `@app.async_tool`, making it callable from Claude, Cursor, or other MCP clients.

## Patterns that mix well

* **Intent classifier ➝ router**: Use the classifier for coarse gating (“is this support vs. billing?”) then route to specialists.
* **Parallel ➝ evaluator**: Run multiple evaluators in parallel (policy, clarity, bias) and feed their combined verdict back to the optimizer.
* **Orchestrator ➝ evaluator**: Wrap the final synthesis step in an evaluator loop so the orchestrator keeps iterating until the review passes.
* **Router ➝ orchestrator**: Route strategic tasks to an orchestrator for deep execution, while simple tasks go to lightweight agents.
* **Swarm handlers**: Use `create_swarm(...)` to hand off between agents mid-conversation, while still using MCP tools for capabilities.

## Operational tips

* **Share the context**: keep compositions inside `async with app.run()` so every component reuses the same `Context` (server registry, executor, secrets, tracing).
* **Tune once, reuse everywhere**: store provider/model defaults in `mcp_agent.config.yaml`; override per pattern only when necessary.
* **Observe everything**: `await workflow.get_token_node()` shows token spend for nested workflows; enable OTEL tracing to follow router choices, parallel branches, and evaluator scores.
* **Blend deterministic helpers**: pass `fan_out_functions` or router `functions` for cheap heuristics (regex, lookups) alongside LLM-heavy steps.
* **Think in tools**: once composed, wrap the entire pattern with `@app.tool` / `@app.async_tool` so it becomes an MCP tool. Other agents, orchestrators, or human operators can call it without knowing how it is assembled.

## Examples to study

* [workflow\_orchestrator\_worker](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_orchestrator_worker) – combines routing, parallel tasks, and orchestration to grade student assignments.
* [workflow\_evaluator\_optimizer](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_evaluator_optimizer) – demonstrates evaluator loops, tool exposure, and cloud deployment.
* [workflow\_parallel](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_parallel) – shows how to compose `AgentSpec`, AugmentedLLMs, and deterministic helpers inside one tool.
* [Temporal examples](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal) – walk through exposing custom compositions as durable Temporal workflows.


# Deep Research
Source: https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/deep-research

Adaptive research workflows with knowledge extraction and policy checks

```mermaid  theme={null}
flowchart TB
    A[User Objective] --> B[Create Plan]
    B --> C{Execute Tasks}
    C --> D[Extract Knowledge]
    D --> E{Objective Complete?}
    E -->|Yes| G[Synthesize Results]
    E -->|No| F{Check Policy}
    F -->|Replan| B
    F -->|Continue| C
    F -->|Stop| G

    style B fill:#e1f5fe
    style D fill:#fff3e0
    style G fill:#e8f5e9
```

## When to use it

* Investigations span many steps or hours, and you need pause/resume without losing context.
* The system must collect structured knowledge, enforce policies, and keep working until an objective is genuinely satisfied.
* You want rich telemetry (plans, queue state, budgets, knowledge base) for dashboards or human reviews.
* You need to dynamically design specialist agents on the fly rather than predefining every worker.

`DeepOrchestrator` extends the standard orchestrator with durable execution, knowledge management, policy-driven replanning, and budget awareness—mirroring Anthropic’s “deep research” guidance.

## Capabilities at a glance

* **Comprehensive planning** – multiple planning passes, dependency tracking, and verification via [`PlanVerifier`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/deep_orchestrator/plan_verifier.py).
* **Knowledge extraction** – facts are stored in `WorkspaceMemory` as [`KnowledgeItem`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/deep_orchestrator/models.py#L28) objects with categories, confidences, and timestamps.
* **Policy engine** – [`PolicyEngine`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/deep_orchestrator/policy.py) decides when to continue, replan, force completion, or emergency stop based on verification plus budget thresholds.
* **Budgeting** – [`SimpleBudget`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/deep_orchestrator/budget.py) tracks tokens, cost, and elapsed time.
* **Agent factory & cache** – dynamically spins up agents tailored to a task and caches them for reuse.
* **Temporal-ready** – built to run on `execution_engine: temporal`, with queue state and knowledge stored so runs can pause, resume, or replay.

```mermaid  theme={null}
sequenceDiagram
    participant User
    participant DeepOrchestrator
    participant Planner
    participant TodoQueue
    participant PolicyEngine
    participant AgentDesigner
    participant TaskAgent
    participant KnowledgeExtractor
    participant WorkspaceMemory
    participant Budget

    User->>DeepOrchestrator: Provide objective
    DeepOrchestrator->>Budget: Initialize budgets
    DeepOrchestrator->>WorkspaceMemory: Setup workspace

    rect rgb(240, 240, 255)
        Note over DeepOrchestrator, Planner: Planning Phase
        DeepOrchestrator->>Planner: Create comprehensive plan
        Planner->>WorkspaceMemory: Retrieve relevant knowledge
        Planner->>DeepOrchestrator: Return plan with steps & tasks
        DeepOrchestrator->>TodoQueue: Load plan with deduplication
    end

    loop Execution Loop
        DeepOrchestrator->>PolicyEngine: Decide action
        DeepOrchestrator->>Budget: Check usage

        alt Continue
            DeepOrchestrator->>TodoQueue: Get next step
            par Parallel tasks
                DeepOrchestrator->>AgentDesigner: Design task agent
                AgentDesigner->>DeepOrchestrator: Agent blueprint
                DeepOrchestrator->>TaskAgent: Execute with context
                TaskAgent->>WorkspaceMemory: Access artifacts
                TaskAgent->>DeepOrchestrator: Return result
            and Knowledge extraction
                DeepOrchestrator->>KnowledgeExtractor: Extract insights
                KnowledgeExtractor->>WorkspaceMemory: Persist knowledge
            end
            DeepOrchestrator->>TodoQueue: Mark step complete
            DeepOrchestrator->>Budget: Update totals
        else Replan
            DeepOrchestrator->>Planner: Generate new plan
            Planner->>WorkspaceMemory: Fetch accumulated knowledge
            Planner->>DeepOrchestrator: Adapted plan
            DeepOrchestrator->>TodoQueue: Merge plan
        else Force complete
            Note over DeepOrchestrator: Exit due to budget/policy
        end
        DeepOrchestrator->>DeepOrchestrator: Verify objective
    end

    rect rgb(240, 255, 240)
        Note over DeepOrchestrator, WorkspaceMemory: Synthesis Phase
        DeepOrchestrator->>WorkspaceMemory: Gather results & knowledge
        DeepOrchestrator->>DeepOrchestrator: Compose final synthesis
        DeepOrchestrator->>User: Deliver final report
    end
```

## Quick start

```python  theme={null}
from mcp_agent.app import MCPApp
from mcp_agent.workflows.factory import AgentSpec, create_deep_orchestrator
from mcp_agent.workflows.deep_orchestrator.config import DeepOrchestratorConfig

app = MCPApp(name="deep_research_example")

async def main():
    async with app.run() as running_app:
        config = DeepOrchestratorConfig.from_simple(
            name="MarketResearchOrchestrator",
            max_iterations=15,
            max_tokens=80_000,
            enable_parallel=True,
        ).with_strict_budget(max_tokens=60_000, max_cost=1.50, max_time_minutes=10)

        deep = create_deep_orchestrator(
            available_agents=[
                AgentSpec(
                    name="researcher",
                    instruction="Search primary sources and extract verifiable facts.",
                    server_names=["fetch"],
                ),
                AgentSpec(
                    name="writer",
                    instruction="Summarise findings in business-friendly language.",
                ),
            ],
            config=config,
            provider="openai",
            context=running_app.context,
        )

        answer = await deep.generate_str(
            "Produce a market overview of MCP tooling and cite your sources."
        )
        return answer
```

### What happens during a run

1. **Plan** – a comprehensive plan is generated and verified; the queue is populated with sequential steps and parallel tasks.
2. **Execute** – tasks are dispatched to existing or newly designed agents. Context is constructed via [`ContextBuilder`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/deep_orchestrator/context_builder.py) with relevance-based pruning.
3. **Extract & store knowledge** – each task outputs structured knowledge captured by [`KnowledgeExtractor`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/deep_orchestrator/knowledge.py).
4. **Verify & replan** – the policy engine evaluates progress. If confidence is low or the queue empties prematurely, it triggers replanning.
5. **Synthesis** – once the policy declares success (or the budget is exhausted), the orchestrator produces a final report with citations and knowledge summaries.

## Configuration surface

`DeepOrchestratorConfig` groups the knobs you need:

* **Execution** (`config.execution`): `max_iterations`, `max_replans`, `max_task_retries`, `enable_parallel`, `enable_filesystem`.
* **Context** (`config.context`): `task_context_budget`, relevance threshold, compression ratio, whether to propagate full context to every task.
* **Budget** (`config.budget`): token, cost, and time ceilings plus `cost_per_1k_tokens` for spend estimates.
* **Policy** (`config.policy`): maximum consecutive failures, budget warning thresholds, verification confidence requirements.
* **Cache** (`config.cache`): enable/size for the agent cache to avoid re-spawning similar agents.

Use helper methods like `with_strict_budget`, `with_resilient_execution`, and `with_minimal_context` to apply common presets.

## Inspecting progress

* `deep.queue.get_progress_summary()` – quick snapshot of pending/completed steps.
* `deep.memory.get_knowledge_summary(limit=10)` – retrieve the latest knowledge items for status dashboards.
* `await deep.get_token_node()` – drill into token/cost usage per planner iteration and worker task.
* The example dashboard (see screenshot above) listens to the orchestrator’s telemetry to display queue state, budgets, policy decisions, and knowledge categories in real time.

## Durability and human-in-the-loop

* Run with `execution_engine: temporal` to get durable execution, pause/resume, and audit logs. Temporal workers simply host your `MCPApp`; the orchestrator persists queue state, knowledge, and budgets across runs.
* Use the policy engine to hand off to humans: custom policies can emit `PolicyAction.FORCE_COMPLETE` to stop and request review, or `PolicyAction.REPLAN` after feedback.
* Knowledge and task artifacts are written to the filesystem workspace when `enable_filesystem=True`, making it straightforward to create attachments for reviewers.

## Example projects

* [workflow\_deep\_orchestrator](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_deep_orchestrator) – end-to-end student essay grader with real-time dashboard, knowledge base, and policy enforcement.
* [Temporal deep orchestrator worker](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal) – shows how to deploy DeepOrchestrator on Temporal for durable operations.

## Related reading

* [Planner (Orchestrator) pattern](/mcp-agent-sdk/effective-patterns/planner)
* [Server authentication](/mcp-agent-sdk/mcp/server-authentication)
* [Temporal workflows guide](/mcp-agent-sdk/core-components/workflows#temporal)


# Evaluator-Optimizer
Source: https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/evaluator-optimizer

Iteratively refine LLM outputs with an evaluator loop

<img src="https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/evaluator-optimizer-workflow.png?fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=6bc285f4267907d9e4096f86e7a64f56" alt="Evaluator-optimizer workflow" data-og-width="2401" width="2401" data-og-height="1000" height="1000" data-path="images/evaluator-optimizer-workflow.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/evaluator-optimizer-workflow.png?w=280&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=278c3eb2751f57bebe3b576555407425 280w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/evaluator-optimizer-workflow.png?w=560&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=7449a8b50f1a22849e684eaec4501117 560w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/evaluator-optimizer-workflow.png?w=840&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=1d878ae52e205c9f48f41faf4d16756b 840w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/evaluator-optimizer-workflow.png?w=1100&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=13c845ad87795245d44d7c7c82b9e3a8 1100w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/evaluator-optimizer-workflow.png?w=1650&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=3e21c56a890f808f3d812c7d250225f4 1650w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/evaluator-optimizer-workflow.png?w=2500&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=88597bb7c8c4b1b297358d495d8cc552 2500w" />

## When to use it

* Quality matters and you need an automated reviewer to approve or demand revisions.
* You have an explicit rubric (score threshold, policy checklist, guardrail) that can be evaluated programmatically.
* You want traceability: each attempt, its score, and the feedback that drove the next revision.
* You need to wrap another workflow (router, orchestrator, parallel, even a deterministic function) with an evaluation loop.

## How the loop works

[`create_evaluator_optimizer_llm`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/factory.py#L436) returns an [`EvaluatorOptimizerLLM`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/evaluator_optimizer/evaluator_optimizer.py) that:

1. Calls the `optimizer` to generate an initial response.
2. Sends the response to the `evaluator`, which returns an [`EvaluationResult`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/evaluator_optimizer/evaluator_optimizer.py#L30) with:
   * `rating`: a [`QualityRating`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/evaluator_optimizer/evaluator_optimizer.py#L16) (`POOR`, `FAIR`, `GOOD`, `EXCELLENT` mapped to 0–3).
   * `feedback`: free-form comments.
   * `needs_improvement`: boolean.
   * `focus_areas`: list of bullet points for the next iteration.
3. If the rating meets `min_rating`, the loop stops. Otherwise it regenerates with the optimizer, incorporating the evaluator’s feedback, until `max_refinements` is reached.
4. Every attempt is recorded in `refinement_history` for audit or UI display.

## Quick start

```python  theme={null}
from mcp_agent.app import MCPApp
from mcp_agent.workflows.factory import AgentSpec, RequestParams, create_evaluator_optimizer_llm
from mcp_agent.workflows.evaluator_optimizer.evaluator_optimizer import QualityRating

app = MCPApp(name="eval_opt_example")

async def main():
    async with app.run() as running_app:
        evaluator_optimizer = create_evaluator_optimizer_llm(
            name="policy_checked_writer",
            optimizer=AgentSpec(
                name="draft",
                instruction="Write detailed answers with citations when available.",
            ),
            evaluator=AgentSpec(
                name="compliance",
                instruction=(
                    "Score the response from 0-3.\n"
                    "Reject anything that violates policy or lacks citations."
                ),
            ),
            min_rating=QualityRating.EXCELLENT,  # require top score
            max_refinements=4,
            provider="anthropic",  # evaluator/optimizer can use different providers internally
            request_params=RequestParams(temperature=0.4),
            context=running_app.context,
        )

        result = await evaluator_optimizer.generate_str(
            "Summarise MCP Agent's router pattern for a product manager."
        )

        # Inspect the iteration history
        for attempt in evaluator_optimizer.refinement_history:
            print(
                attempt["attempt"],
                attempt["evaluation_result"].rating,
                attempt["evaluation_result"].feedback,
            )

        return result
```

You can pass an existing AugmentedLLM (router, orchestrator, parallel workflow) as the optimizer instead of an `AgentSpec`. For evaluators, strings are allowed: if you pass a literal string, the factory spins up an evaluator agent using that instruction.

## Configuration knobs

* `min_rating`: numeric threshold (0–3). Set to `None` to keep all iterations and let a human pick the best attempt.
* `max_refinements`: hard cap on iteration count; default is 3.
* `evaluator`: accept `AgentSpec`, `Agent`, `AugmentedLLM`, or string instruction. Use this to plug in policy engines or MCP tools that act as judges.
* `request_params`: forwarded to both optimizer and evaluator LLMs (temperature, max tokens, strict schema enforcement).
* `llm_factory`: automatically injected based on the `provider` you specify; override if you need custom model selection or instrumentation.
* `evaluator_optimizer.refinement_history`: list of dicts containing `response` and `evaluation_result` per attempt—useful for UI timelines or telemetry.

## Pairing with other patterns

* **Router + evaluator**: Route to a specialised agent, then run the evaluator loop before returning to the user.
* **Parallel + evaluator**: Run multiple evaluators in parallel (e.g. clarity, policy, bias). Feed the aggregated verdict back into the optimizer.
* **Deep research failsafe**: Wrap sections of a deep orchestrator plan with an evaluator-optimizer step to enforce domain-specific QA.

## Operational tips

* Evaluator instructions should reference the previous feedback: the default prompt asks the optimizer to address each focus area. Ensure your instruction echoes that requirement.
* Call `await evaluator_optimizer.get_token_node()` to see how many tokens each iteration consumed (optimiser vs evaluator).
* Log or persist `refinement_history` when you need postmortem evidence of what the evaluator flagged and how the optimizer reacted.
* Combine with OpenTelemetry (`otel.enabled: true`) to capture spans for each iteration, including evaluation scores and decision rationale.

## Example projects

* [workflow\_evaluator\_optimizer](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_evaluator_optimizer) – job application cover letter refinement with evaluator feedback surfaced via MCP tools.
* [Temporal evaluator optimizer](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal/evaluator_optimizer.py) – durable loop running under Temporal with pause/resume.

## Related reading

* [Workflow & decorators guide](/mcp-agent-sdk/core-components/workflows)
* [Parallel pattern](/mcp-agent-sdk/effective-patterns/map-reduce)


# Intent Classifier
Source: https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/intent-classifier

Classify free-form requests into discrete intents using LLMs or embeddings

## When to use it

* Short user inputs need to be mapped to a handful of flows before you invest in full orchestration.
* You want to gate automation on a confidence score (only auto-run when the intent is clear, otherwise escalate).
* You need structured metadata—like extracted entities or a human-readable reason—to feed into downstream logic.
* You want deterministic categorisation (embeddings) or richer explanations (LLM) without building a bespoke classifier.

## Defining intents

Every classifier consumes a list of [`Intent`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/intent_classifier/intent_classifier_base.py#L14) objects:

```python  theme={null}
from mcp_agent.workflows.intent_classifier.intent_classifier_base import Intent

INTENTS = [
    Intent(
        name="fetch_file",
        description="Retrieve the contents of a file from the filesystem MCP server.",
        examples=[
            "show me README.md",
            "open src/app.py",
            "cat /var/log/system.log",
        ],
        metadata={"priority": "high", "team": "infra"},
    ),
    Intent(
        name="general_question",
        description="Answer an informational question without tool use.",
        examples=["what is MCP?", "explain the router pattern"],
    ),
]
```

* **`description`** gives the classifier context and is surfaced in tracing metadata.
* **`examples`** dramatically improve accuracy—provide several phrasing variants.
* **`metadata`** is propagated to the result so you can attach business logic (e.g. SLA, handoff target).

## Choosing a classifier

| Variant         | Factory helper                            | Best for                                                                        | Output extras                                                                      |
| --------------- | ----------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| LLM-based       | `create_intent_classifier_llm(...)`       | Highest quality natural language understanding, explanations, entity extraction | `confidence` (`low`/`medium`/`high`), `p_score`, `reasoning`, `extracted_entities` |
| Embedding-based | `create_intent_classifier_embedding(...)` | Deterministic scoring, lower latency, custom embedding providers                | `p_score` (0–1 similarity)                                                         |

LLM classification enforces a strict JSON schema ([`StructuredIntentResponse`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/intent_classifier/intent_classifier_llm.py#L39)), ensuring stable output even under temperature.

## Quick start

```python  theme={null}
from mcp_agent.app import MCPApp
from mcp_agent.workflows.factory import (
    create_intent_classifier_embedding,
    create_intent_classifier_llm,
)
from mcp_agent.workflows.intent_classifier.intent_classifier_base import Intent

app = MCPApp(name="intent_demo")
INTENTS = [...]  # see definition above

async def main():
    async with app.run() as running_app:
        llm_classifier = await create_intent_classifier_llm(
            intents=INTENTS,
            provider="openai",
            classification_instruction="Return at most one intent unless the user explicitly asks for multiple.",
            context=running_app.context,
        )

        embedding_classifier = await create_intent_classifier_embedding(
            intents=INTENTS,
            provider="openai",  # or "cohere"
            context=running_app.context,
        )

        request = "Could you open README.md for me?"
        llm_result = (await llm_classifier.classify(request, top_k=2))[0]
        emb_result = (await embedding_classifier.classify(request, top_k=2))[0]

        return {
            "llm_intent": llm_result.intent,
            "llm_confidence": llm_result.confidence,
            "llm_reasoning": llm_result.reasoning,
            "embedding_intent": emb_result.intent,
            "embedding_score": emb_result.p_score,
        }
```

## Working with results

* **LLM classifier** returns `LLMIntentClassificationResult` with:
  * `intent`: matched intent name.
  * `confidence`: `"low"`, `"medium"`, `"high"` (auto-quantised from raw scores).
  * `p_score`: continuous probability (0–1).
  * `reasoning`: short explanation.
  * `extracted_entities`: optional name/value pairs surfaced by the LLM.
* **Embedding classifier** returns `IntentClassificationResult` with `intent` and `p_score`. Sort or threshold the score to decide automation boundaries.

Both variants support `top_k`, letting you offer alternatives to a human or feed multiple candidates into a downstream router.

## Integrating with the router

Intent classifiers and routers pair naturally: classify first, then route using a richer skill set.

```python  theme={null}
intent = (await llm_classifier.classify(request, top_k=1))[0]
if intent.confidence != "high":
    return "Escalating to human – intent unclear."

decisions = await router.route(
    f"[intent={intent.intent}] {request}",
    top_k=3,
)
```

The intent name/metadata can be prepended to the router prompt (as above) or used to select different router instances entirely.

## Tuning and operations

* Override `classification_instruction` to bias LLM behaviour (hierarchical intents, abstain thresholds, multilingual hints).
* Pass `request_params=RequestParams(strict=True, temperature=0)` to disable sampling variance for high-stakes automation.
* Pre-compute embeddings for cold start by calling `await classifier.initialize()` at app startup.
* Record tracing output (`otel.enabled: true`) to inspect intent descriptions, examples, and resulting confidence scores per request.

## Example projects

* [workflow\_intent\_classifier](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_intent_classifier) – shows LLM + embedding classifiers side by side with downstream routing.
* [Temporal examples](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal) – includes a classifier-driven Temporal workflow.

## Related reading

* [Router pattern](/mcp-agent-sdk/effective-patterns/router)
* [Workflow & decorators guide](/mcp-agent-sdk/core-components/workflows)


# Parallel (Map-Reduce)
Source: https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/map-reduce

Fan-out/fan-in workflows that let multiple specialists work in parallel

<img src="https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/parallel-workflow.png?fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=2081099a05e686a669ba459ad3ecff98" alt="Parallel workflow diagram" data-og-width="2401" width="2401" data-og-height="1000" height="1000" data-path="images/parallel-workflow.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/parallel-workflow.png?w=280&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=420d93611738ab1c83c9c8f163d01c00 280w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/parallel-workflow.png?w=560&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=d4022e33a803c878c765fb7b82f2f283 560w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/parallel-workflow.png?w=840&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=2daca3250bb73ad8c219e8b30d367e03 840w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/parallel-workflow.png?w=1100&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=39b0436abd20c9bd420b1710a35b629d 1100w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/parallel-workflow.png?w=1650&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=bb5144d66a80981e607fb62e403a8394 1650w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/parallel-workflow.png?w=2500&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=731ef1c525842121199cbf3137b91053 2500w" />

## When to use it

* You need several specialists to analyse the same request from different angles (e.g. proofread, fact-check, style review).
* You want deterministic aggregation of multiple perspectives into a single response.
* You have functions or agents that can run concurrently and do not depend on each other’s intermediate state.
* You want a cheap way to blend deterministic helpers (regex, heuristics) with heavyweight LLM agents.

Common scenarios include content review with multiple rubrics, multi-source research where each worker hits a different MCP server, or evaluation workflows where you want a “best effort” vote across diverse models.

## How it works

`create_parallel_llm(...)` returns a [`ParallelLLM`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/parallel/parallel_llm.py) composed of two primitives:

* **FanOut** ([`fan_out.py`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/parallel/fan_out.py)) launches every worker concurrently. Workers can be `AgentSpec`, pre-built `Agent`/`AugmentedLLM`, or plain callables via `fan_out_functions`.
* **FanIn** ([`fan_in.py`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/parallel/fan_in.py)) collects the responses and hands a [`FanInInput`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/parallel/fan_in.py#L18) structure to your aggregator. The aggregator can also be an `AgentSpec`, an `AugmentedLLM`, or a deterministic function.

FanOut returns a dictionary keyed by worker name, so the aggregator always knows who produced which output. When the aggregator is an LLM, mcp-agent automatically enters the worker contexts, attaches LLMs, and tracks token usage per branch.

## Quick start

```python  theme={null}
from mcp_agent.app import MCPApp
from mcp_agent.workflows.factory import (
    AgentSpec,
    RequestParams,
    create_parallel_llm,
)

app = MCPApp(name="parallel_example")

async def main():
    async with app.run() as running_app:
        parallel = create_parallel_llm(
            name="content_review_parallel",
            fan_in=AgentSpec(
                name="grader",
                instruction=(
                    "Blend the reviewer feedback into a single report. "
                    "Call out disagreements and provide an overall score."
                ),
            ),
            fan_out=[
                AgentSpec(
                    name="proofreader",
                    instruction="Check grammar, spelling, and clarity.",
                ),
                AgentSpec(
                    name="fact_checker",
                    instruction="Verify factual claims using the fetch server.",
                    server_names=["fetch"],
                ),
                AgentSpec(
                    name="style_enforcer",
                    instruction="Compare against the company voice and style guide.",
                ),
            ],
            fan_out_functions=[
                lambda prompt: [
                    {
                        "title": "metadata",
                        "details": {
                            "characters": len(prompt),
                            "keywords": prompt.split()[:5],
                        },
                    }
                ]
            ],
            provider="openai",
            request_params=RequestParams(maxTokens=2000, temperature=0.2),
            context=running_app.context,
        )

        result = await parallel.generate_str("Review this customer email draft.")
        return result
```

`create_parallel_llm` accepts `AgentSpec`, already-instantiated `Agent`/`AugmentedLLM`, or plain Python callables. Every worker receives the same prompt; the aggregator receives a structured summary of all responses and returns either a list of `CreateMessageResult` objects or a single string, depending on whether you call `generate` or `generate_str`.

### Working with the aggregator input

FanIn accepts several shapes (dicts or lists). For example, you can use a deterministic aggregator:

```python  theme={null}
from mcp_agent.workflows.parallel.fan_in import FanInInput

def aggregate_as_markdown(messages: FanInInput) -> str:
    blocks = []
    for source, outputs in messages.items():
        lines = "\n".join(str(item) for item in outputs)
        blocks.append(f"### {source}\n{lines}")
    return "\n\n".join(blocks)

parallel = create_parallel_llm(
    fan_in=aggregate_as_markdown,
    fan_out=[AgentSpec(name="qa", instruction="Answer with citations.")],
    context=running_app.context,
)
```

When the aggregator is an agent/LLM, mcp-agent wraps the aggregated string in a system prompt that names each contributor, making it easy to ask for weighted votes, majority decisions, or summarised findings.

## Operational tips

* **Throttle concurrency** by setting `executor.max_concurrent_activities` in `mcp_agent.config.yaml`. The parallel workflow uses the shared executor, so the limit applies across your entire app.
* **Mix deterministic helpers** via `fan_out_functions` for cheap signals (regex extractors, heuristics) alongside heavyweight LLM calls.
* **Inspect token/latency costs** with `await parallel.get_token_node()`—each fan-out worker appears as a child node, making it easy to spot the expensive branch.
* **Handle stragglers** by adjusting `RequestParams.timeoutSeconds` or adding retry logic inside the worker agents.
* **Reuse workers** by instantiating AugmentedLLMs once and passing them directly into `fan_out` to avoid repeated attachment overhead.

## Example projects

* [workflow\_parallel](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_parallel) – proofreader/fact-checker/style-enforcer with graded aggregation.
* [Temporal parallel workflow](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal) – demonstrates durable fan-out execution using Temporal as the engine.

## Related reading

* [Workflow & decorators guide](/mcp-agent-sdk/core-components/workflows)
* [Agents and AugmentedLLMs](/mcp-agent-sdk/core-components/agents)


# Overview
Source: https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/overview

Choose the right workflow pattern for your mcp-agent build

mcp-agent ships production-ready implementations of every pattern in [Anthropic's *Building Effective Agents*](https://www.anthropic.com/engineering/building-effective-agents) plus complementary flows inspired by OpenAI Swarm. Each helper in [`workflows/factory.py`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/factory.py) returns an **AugmentedLLM** that can be treated like any other LLM in the framework—compose it, expose it as a tool, or wrap it with additional logic.

## Patterns at a glance

| Pattern                                                                      | Reach for it when…                                                     | Factory helper(s)                                                              | Highlights                                                                                        | Runnable example                                                                                                                     |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| [Parallel (Map-Reduce)](/mcp-agent-sdk/effective-patterns/map-reduce)        | You need multiple specialists to look at the same request concurrently | `create_parallel_llm(...)`                                                     | Fan-out/fan-in via `FanOut` + `FanIn`, accepts agents *and* plain callables                       | [`workflow_parallel`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_parallel)                       |
| [Router](/mcp-agent-sdk/effective-patterns/router)                           | Requests must be dispatched to the best skill, server, or function     | `create_router_llm(...)`, `create_router_embedding(...)`                       | Confidence-scored results, `route_to_{agent,server,function}` helpers, optional embedding routing | [`workflow_router`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_router)                           |
| [Intent Classifier](/mcp-agent-sdk/effective-patterns/intent-classifier)     | You need lightweight intent buckets before routing or automation       | `create_intent_classifier_llm(...)`, `create_intent_classifier_embedding(...)` | Returns structured `IntentClassificationResult` with entities and metadata                        | [`workflow_intent_classifier`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_intent_classifier)     |
| [Planner (Orchestrator)](/mcp-agent-sdk/effective-patterns/planner)          | A goal requires multi-step planning and coordination across agents     | `create_orchestrator(...)`                                                     | Switch between full and iterative planning, override planner/synthesizer roles                    | [`workflow_orchestrator_worker`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_orchestrator_worker) |
| [Deep Research](/mcp-agent-sdk/effective-patterns/deep-research)             | Long-horizon investigations with budgets, memory, and policy checks    | `create_deep_orchestrator(...)`                                                | Knowledge extraction, policy engine, Temporal-friendly execution                                  | [`workflow_deep_orchestrator`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_deep_orchestrator)     |
| [Evaluator-Optimizer](/mcp-agent-sdk/effective-patterns/evaluator-optimizer) | You want an automated reviewer to approve or iterate on drafts         | `create_evaluator_optimizer_llm(...)`                                          | `QualityRating` thresholds, detailed feedback loop, `refinement_history`                          | [`workflow_evaluator_optimizer`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_evaluator_optimizer) |
| [Build Your Own](/mcp-agent-sdk/effective-patterns/build-your-own)           | You need a bespoke pattern stitched from the primitives above          | Mix helpers, native agents, and `@app.tool` decorators                         | Compose routers, parallel fan-outs, evaluators, or custom callables                               | See all workflows + [`create_swarm(...)`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/factory.py)     |

## Before you start

* Model your specialists as [`AgentSpec`](/mcp-agent-sdk/core-components/agents) or instantiate `Agent`/`AugmentedLLM` objects up front. The factory helpers accept any combination.
* Run everything inside `async with app.run() as running_app:` so the shared [`Context`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/core/context.py) is initialised (server registry, executor, tracing, secrets).
* Tune behaviour with [`RequestParams`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/llm/augmented_llm.py) (temperature, max tokens, strict schema mode) and provider-specific options (`provider="anthropic"`, Azure/OpenAI models, etc.).
* Expose the returned AugmentedLLM directly (`await llm.generate_str(...)`) or wrap it with `@app.tool` / `@app.async_tool` to make it callable over MCP.

## Composable building blocks

* Patterns are just AugmentedLLMs, so you can **nest** them—e.g. route to an orchestrator, run parallel fan-outs inside a planner step, or wrap the output of any pattern with an evaluator-optimizer loop.
* Mix LLM-powered steps with deterministic functions. Routers accept plain Python callables; parallel workflows blend `AgentSpec` with helpers like `fan_out_functions`.
* Share state via the `Context`: reuse secrets, telemetry, the executor, and the token counter across nested patterns without additional wiring.

## Observability and control

* Every pattern reports token usage through the global [`TokenCounter`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/tracing/token_counter.py). Call `await llm.get_token_node()` to inspect fan-out costs, planner iterations, or evaluation loops.
* Adjust concurrency and retries centrally in `mcp_agent.config.yaml` (`executor.max_concurrent_activities`, retry policy) instead of per-pattern plumbing.
* Enable tracing (`otel.enabled: true`) to see spans for planner steps, router decisions, evaluator iterations, and MCP tool calls in Jaeger or any OTLP backend.

## Related docs

* [Core workflows & decorators](/mcp-agent-sdk/core-components/workflows)
* [Connecting to MCP servers](/mcp-agent-sdk/core-components/connecting-to-mcp-servers)
* [Agent servers](/mcp-agent-sdk/mcp/agent-as-mcp-server)
* [Examples directory](https://github.com/lastmile-ai/mcp-agent/tree/main/examples)


# Planner (Orchestrator)
Source: https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/planner

Break complex objectives into coordinated steps

<img src="https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/orchestrator-workflow.png?fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=6d96b7de50b03a6f7f8eab785f3f8cc5" alt="Orchestrator workflow diagram" data-og-width="2401" width="2401" data-og-height="1000" height="1000" data-path="images/orchestrator-workflow.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/orchestrator-workflow.png?w=280&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=b389cf42a500f5a3beff4238e4eb884e 280w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/orchestrator-workflow.png?w=560&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=d05f7086fd5dc059641f26bb0fe6dff0 560w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/orchestrator-workflow.png?w=840&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=9ab89c3505c44d11d2d86cd3a37da27c 840w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/orchestrator-workflow.png?w=1100&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=2b3131c564a69a326d963627004a1e3a 1100w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/orchestrator-workflow.png?w=1650&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=38c22f09a613ffcddee6d28d3c902f6a 1650w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/orchestrator-workflow.png?w=2500&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=433333b48b3024f649bb4f9b7220f085 2500w" />

## When to use it

* The user request is ambiguous or multi-step and you want the system to decide *what* to do before executing.
* Different parts of the task require different agents or MCP servers (retrieve context, analyse, write, verify).
* You need visibility into the plan, intermediate results, and token spend for each subtask.
* You want to switch between full upfront planning and iterative planning based on feedback.

The orchestrator mirrors Anthropic’s “orchestrator-workers” pattern: a planner decomposes the objective, assigns workers, collects intermediate artifacts, and synthesises the final response.

## Core roles

[`create_orchestrator`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/factory.py#L214) returns an [`Orchestrator`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/orchestrator/orchestrator.py) AugmentedLLM composed of:

* **Planner** – an LLM that produces a [`Plan`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/orchestrator/orchestrator_models.py#L52) with sequential `Step`s and parallel `Task`s. You can provide your own planner agent or use the default prompt.
* **Workers** – the `available_agents` you pass in. Each step selects whichever agent (or MCP server) best fits the subtask.
* **Synthesizer** – combines the outputs of each step into the final result. Provide your own synthesizer agent to bias tone or format.

## Quick start

```python  theme={null}
from mcp_agent.app import MCPApp
from mcp_agent.workflows.factory import AgentSpec, OrchestratorOverrides, create_orchestrator

app = MCPApp(name="orchestrator_example")

async def main():
    async with app.run() as running_app:
        orchestrator = create_orchestrator(
            available_agents=[
                AgentSpec(
                    name="researcher",
                    instruction="Gather supporting evidence from trusted sources.",
                    server_names=["fetch"],
                ),
                AgentSpec(
                    name="writer",
                    instruction="Summarise findings as bullet points and a short conclusion.",
                ),
                AgentSpec(
                    name="editor",
                    instruction="Check for policy violations and tighten language.",
                ),
            ],
            plan_type="iterative",  # or "full"
            overrides=OrchestratorOverrides(
                planner_instruction="You are a project manager. Break the goal into 2-4 sequential steps.",
                synthesizer_instruction="Return Markdown with headings and a highlights section.",
            ),
            provider="openai",
            context=running_app.context,
        )

        summary = await orchestrator.generate_str(
            "Research the latest MCP Agent updates and draft a changelog."
        )
        return summary
```

Use `await orchestrator.execute(objective)` when you want full access to the [`PlanResult`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/orchestrator/orchestrator_models.py#L69): each step, the tasks that ran, agent selections, and intermediate outputs.

## Execution modes

* `plan_type="full"` builds the entire plan upfront, then executes it step by step. Use this when the task is well understood and you want deterministic execution.
* `plan_type="iterative"` plans one step at a time, feeding the latest results back into the planner. Ideal for exploratory work or when new context appears during execution.
* Guardrails:
  * `request_params.max_iterations` caps the number of planner loops.
  * `request_params.maxTokens` defaults to 16K to accommodate plans and long syntheses.
  * `request_params.use_history` is disabled—context is managed manually between steps.

## Customising prompts and roles

* Pass `planner` or `synthesizer` arguments to supply pre-built agents (with their own tools or model preferences).
* Use `OrchestratorOverrides` to replace any prompt template:
  * `get_full_plan_prompt` / `get_iterative_plan_prompt`: plug in your own prompt builders if you want richer task schemas or intermediate metadata.
  * `get_task_prompt`: control the system prompt given to each worker before it runs.
  * `get_synthesize_plan_prompt`: change the final aggregation format (JSON, Markdown, HTML).
* The orchestrator automatically loads tool availability from the context; include `server_names` on your `AgentSpec`s so planner prompts explain what each worker can do.

## Observability and debugging

* Enable tracing (`otel.enabled: true`) to capture spans for planning, each step’s parallel execution, and synthesis. Each task records which agent ran, token usage, and outputs.
* Call `await orchestrator.get_token_node()` to inspect the token/cost tree—each planner iteration and worker invocation is a child node.
* The `PlanResult` returned by `execute` contains `step_results` with every intermediate output. Persist it for audit trails or UX side panels.

## Integration tips

* Wrap the orchestrator with `@app.async_tool` to expose it as an MCP tool that other agents (or Anthropic Claude) can call.
* Combine with the [Parallel pattern](/mcp-agent-sdk/effective-patterns/map-reduce) by using a `ParallelLLM` as a worker inside a step.
* For durable execution, point `execution_engine` to `temporal` and follow the [Temporal examples](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal/orchestrator.py).
* Need policy, budgeting, or knowledge extraction? Reach for the [Deep Research pattern](/mcp-agent-sdk/effective-patterns/deep-research), which builds on this orchestrator.

## Example projects

* [workflow\_orchestrator\_worker](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_orchestrator_worker) – student essay grader that plans retrieval, analysis, and report writing.
* [Temporal orchestrator](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal/orchestrator.py) – durable planner with pause/resume.
* [workflow\_deep\_orchestrator](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_deep_orchestrator) – extended planner with dashboards, budgets, and policy enforcement.

## Related reading

* [Deep Research pattern](/mcp-agent-sdk/effective-patterns/deep-research)
* [Workflow & decorators guide](/mcp-agent-sdk/core-components/workflows)


# Router
Source: https://docs.mcp-agent.com/mcp-agent-sdk/effective-patterns/router

Intelligently dispatch requests to the best agent, MCP server, or function

<img src="https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/router-workflow.png?fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=2c990911e8acba5e80eda69ac42a274b" alt="Router workflow diagram" data-og-width="2401" width="2401" data-og-height="1000" height="1000" data-path="images/router-workflow.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/router-workflow.png?w=280&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=3286334a7ca71de2f827c78aee989f99 280w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/router-workflow.png?w=560&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=af29fb985d0caa3d325ce3d7588b11a6 560w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/router-workflow.png?w=840&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=5c31307e43bc70ef6cf81835e3aff476 840w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/router-workflow.png?w=1100&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=c72ad51cf9220e12c3915c7b4440891d 1100w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/router-workflow.png?w=1650&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=cfa981bc18c46673b4069d211e4e8094 1650w, https://mintcdn.com/lastmileai-94a5811a/uEtzAWFx4Y1y4nXl/images/router-workflow.png?w=2500&fit=max&auto=format&n=uEtzAWFx4Y1y4nXl&q=85&s=571ce6668e7dc8cc6577bdc40b4bf79d 2500w" />

## When to use it

* Incoming requests could be answered by multiple skills—agents with tools, direct MCP servers, or lightweight functions.
* You want dynamic dispatch instead of a maze of `if/else` statements or handcrafted prompts.
* You need confidence scores and rationale so a human (or another workflow) can make the final decision.
* You want to fall back to a generalist agent when no high-confidence match is found.

## Destinations and scoring

`create_router_llm(...)` builds an [`LLMRouter`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/router/router_llm.py) that instantiates a classifier LLM, inspects the candidates, and returns ranked [`LLMRouterResult`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/router/router_llm.py#L61) objects. Each result contains:

* `category`: `"agent"`, `"server"`, or `"function"`.
* `result`: the routed object (an `Agent`/`AugmentedLLM`, a server name, or a callable).
* `confidence`: `"high"`, `"medium"`, or `"low"`—computed from the model’s probability.
* `reasoning`: the model’s natural language justification.

For deterministic routing, use `create_router_embedding(...)` which compares embeddings via [`EmbeddingRouter`](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/workflows/router/router_embedding.py).

## Quick start

```python  theme={null}
from mcp_agent.app import MCPApp
from mcp_agent.mcp.gen_client import gen_client
from mcp_agent.workflows.factory import AgentSpec, create_router_llm

app = MCPApp(name="router_example")

async def main():
    async with app.run() as running_app:
        router = await create_router_llm(
            name="support_router",
            server_names=["filesystem", "fetch"],
            agents=[
                AgentSpec(
                    name="finder",
                    instruction="Locate relevant files or URLs using MCP tools.",
                    server_names=["filesystem", "fetch"],
                ),
                AgentSpec(
                    name="writer",
                    instruction="Draft polished responses using prior context.",
                ),
            ],
            functions=[
                lambda _: "Fallback: escalate to human triage.",
            ],
            routing_instruction="Prefer agents when tool use is required; use functions only for trivial replies.",
            provider="openai",
            context=running_app.context,
        )

        decisions = await router.route("Print the contents of README.md", top_k=2)
        for choice in decisions:
            print(choice.category, choice.result, choice.confidence, choice.reasoning)

        top = decisions[0]
        if top.category == "agent":
            async with top.result:  # Attach LLMs + MCP tools for the agent
                return await top.result.generate_str("Show me README.md")
        if top.category == "server":
            async with gen_client(
                top.result,
                running_app.server_registry,
                context=running_app.context,
            ) as session:
                file = await session.call_tool("read_file", {"path": "README.md"})
                return file.content
        if top.category == "function":
            return top.result("README.md")
```

## Configuration knobs

* `top_k`: expose the top *k* candidates to give humans (or downstream logic) choices.
* `routing_instruction`: prime the classifier with custom rubric; defaults to a generic prompt that lists every destination, its description, and available tools.
* `provider` / `model`: choose the model that performs routing (`openai` or `anthropic` today). You can also pass `request_params` for temperature, stop sequences, or strict JSON mode.
* `server_names`: include raw MCP servers. The router pulls descriptions from the server registry so the model knows what each server can do.
* `functions`: register local Python callables. Handy for telemetry, logging, or immediate fallbacks.
* `route_to_agent` / `route_to_server` / `route_to_function`: skip the multi-category prompt when you already know the desired destination type.
* `create_router_embedding`: swap in embedding similarity when you prefer deterministic scoring or offline model execution.

## Guardrails and observability

* Use the `confidence` signal to decide when to short-circuit or escalate. For example, enforce `confidence == "high"` before allowing automated actions.
* The router records detailed spans (`router.route`, candidate reasoning, chosen categories) when tracing is enabled, making it easy to debug ambiguous decisions in Jaeger or another OTLP backend.
* Pair with the [Intent Classifier](/mcp-agent-sdk/effective-patterns/intent-classifier) for two-stage routing: first map the request to an intent, then feed the intent into the router for fine-grained dispatch.
* Wrap the router itself in the [Evaluator-Optimizer](/mcp-agent-sdk/effective-patterns/evaluator-optimizer) pattern if you want an automated supervisor to veto low-quality routing rationales.

## Example projects

* [workflow\_router](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_router) – routes across agents, MCP servers, and plain functions with confidence/rationale logging.
* [workflow\_intent\_classifier](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows/workflow_intent_classifier) – classifies intent first, then routes to specialised handlers.
* [Temporal router](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal/router.py) – demonstrates durable routing inside Temporal workflows.

## Related reading

* [Intent Classifier pattern](/mcp-agent-sdk/effective-patterns/intent-classifier)
* [Workflow & decorators guide](/mcp-agent-sdk/core-components/workflows)


# Agent Servers
Source: https://docs.mcp-agent.com/mcp-agent-sdk/mcp/agent-as-mcp-server

Expose an mcp-agent application as an MCP server

## Why turn an agent into an MCP server?

Exposing your mcp-agent app as an MCP server lets any MCP-compatible client (Claude Desktop, Cursor, VS Code, custom tooling) call your workflows over the standard protocol. It is the easiest way to:

* Reuse an agent from multiple clients without rewriting logic
* Chain agents together (one agent can call another as a server)
* Deploy long-running workflows on dedicated infrastructure

If you want to see the full picture, start with the runnable examples:

* [`examples/mcp_agent_server/asyncio`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp_agent_server/asyncio) – in-memory execution, great for local testing
* [`examples/mcp_agent_server/temporal`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp_agent_server/temporal) – durable execution backed by Temporal

The READMEs in those folders walk through prerequisites, commands, and client integration.

## Execution modes

* **Asyncio** – Runs entirely in-memory with minimal setup. Perfect for local development, demos, or lightweight agents.
* **Temporal** – Uses the Temporal orchestration engine for durable, resumable workflows with retries and pause/resume.

You can reuse the same application code with either engine by switching the `execution_engine` setting.

## Prerequisites

Before running the examples you will need:

* Python 3.10+
* [uv](https://github.com/astral-sh/uv) for dependency management
* API keys for the model providers referenced in the example (OpenAI / Anthropic)
* A copy of the example secrets file:

```bash  theme={null}
cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml
# Edit the file or export matching environment variables
```

## Quick start (asyncio)

```python title="examples/mcp_agent_server/asyncio/main.py" theme={null}
from mcp_agent.app import MCPApp
from mcp_agent.server import create_mcp_server_for_app

app = MCPApp(name="basic_agent_server")

@app.tool
async def grade_story(story: str) -> str:
    """Grade a student's short story and return a report."""
    # Implement using your agents/LLMs…
    return "Report..."

@app.async_tool(name="grade_story_async")
async def grade_story_async(story: str) -> dict:
    """Start grading asynchronously and return workflow IDs."""
    # Launch a long-running workflow and return {"workflow_id","run_id"}
    return {"workflow_id": "...", "run_id": "..."}

if __name__ == "__main__":
    mcp_server = create_mcp_server_for_app(app)
    mcp_server.run_stdio()
```

Run it locally (from the `examples/mcp_agent_server/asyncio` directory):

```bash  theme={null}
uv run main.py            # start the MCP server
uv run client.py          # connect using gen_client
```

1. Populate `mcp_agent.secrets.yaml` (or export environment variables) with your provider keys.
2. Run `uv run main.py` to start the server.
3. Run `uv run client.py` to invoke the tools and watch status updates.

* `@app.tool` exposes a synchronous MCP tool. The client gets the final result immediately.
* `@app.async_tool` is designed for long-running work. It starts a workflow in the background, returns `workflow_id`/`run_id`, and the client polls `workflows-get_status` until completion.
* Under the hood you can launch any `Workflow` ([see the Workflow class documentation](/mcp-agent-sdk/core-components/workflows)) from inside an async tool.

The example `client.py` shows how to call your server with `gen_client`, and the README covers Claude Desktop / MCP Inspector connections.

## Temporal variant

Use the Temporal example when you need durable execution, pause/resume, or production-grade retries. It follows the same pattern as above but uses `create_temporal_worker_for_app` to run workflows on a Temporal cluster. See [`examples/mcp_agent_server/temporal`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp_agent_server/temporal) for setup instructions. In short:

1. Start a Temporal server locally (`temporal server start-dev`).
2. Run `uv run run_worker.py` to start the worker that hosts your workflows.
3. In another terminal run `uv run main.py` to expose the MCP endpoint.
4. Connect using `uv run client.py` or any MCP client.

Temporal retains workflow history, so async tools can pause for human input, survive restarts, and resume later.

## Predefined Tools

When you call `create_mcp_server_for_app(app)` the server registers:

* Every `@app.tool` / `@app.async_tool` defined on the app
* Workflow entry points (e.g. `workflows-<Workflow>-run`) for explicit `@app.workflow` classes
* A set of management tools that every MCP client can rely on:
  * `workflows-list` – discover available workflows, parameter schemas, and tool names.
  * `workflows-run` – start a workflow synchronously and receive `workflow_id`/`run_id`.
  * `workflows-get_status` – poll for status, outputs, or errors.
  * `workflows-cancel` – terminate a running workflow.
  * `workflows-resume` – resume paused workflows (useful with Temporal + signals).

Clients interact with these tools just like any other MCP server, so the experience feels native in Claude Desktop, Cursor, or custom clients.

## Connecting from MCP clients

* **Claude Desktop** – add an entry in `~/.claude-desktop/config.json` pointing to `uv run main.py` (the asyncio example README includes a copy-paste snippet).
* **MCP Inspector** – run `npx @modelcontextprotocol/inspector` and point it at your server command.
* **Custom code** – reuse the `gen_client` example provided in each folder.

Because the server speaks standard MCP, any client that understands the protocol can connect.

## Deployment options

* Run locally via `uv run`
* Package and deploy the command anywhere you can run Python
* Use `uv run mcp-agent deploy …` to publish to [mcp-agent cloud](/cloud/overview) (the example README outlines the CLI flow)

Whichever approach you choose, the public MCP endpoint looks the same to clients.

## Connecting from common MCP clients

### Claude Desktop

Update `~/.claude-desktop/config.json` with a command that starts your server:

```json  theme={null}
{
  "mcpServers": {
    "my-agent-server": {
      "command": "uv",
      "args": [
        "run",
        "examples/mcp_agent_server/asyncio/main.py"
      ]
    }
  }
}
```

For cloud deployments replace the command with `mcp-remote` plus your SSE endpoint and bearer token, as shown in the example README.

### MCP Inspector

```bash  theme={null}
npx @modelcontextprotocol/inspector \
  uv \
  --directory examples/mcp_agent_server/asyncio \
  run main.py
```

The inspector will list every exposed tool (`grade_story`, `grade_story_async`, `workflows-list`, etc.) so you can interactively test them.

### Programmatic access (`gen_client`)

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

app = MCPApp(name="client")

async def list_tools():
    async with app.run():
        async with gen_client("my-agent-server", app.server_registry, context=app.context) as session:
            tools = await session.list_tools()
            return [tool.name for tool in tools.tools]
```

## Next steps

* Browse the asyncio and Temporal READMEs for end-to-end workflows, screenshots, and configuration details.
* Review [Server Authentication](/mcp-agent-sdk/mcp/server-authentication) if your server needs API keys or OAuth.
* Combine agent servers with other agents to build multi-agent ecosystems over MCP.


# MCP Capabilities
Source: https://docs.mcp-agent.com/mcp-agent-sdk/mcp/overview

How mcp-agent integrates with the Model Context Protocol

mcp-agent is built on top of the Model Context Protocol (MCP). Agents connect to MCP servers to gain tools, data, prompts, and filesystem-style access. If you are new to the protocol, start with the [official MCP introduction](https://modelcontextprotocol.io/docs/getting-started/intro); this page shows how MCP fits into mcp-agent.

## MCP primitives at a glance

<CardGroup cols={3}>
  <Card title="Tools" icon="wrench">
    Functions exposed by MCP servers—use `agent.call_tool` or let an AugmentedLLM invoke them during generation.
  </Card>

  <Card title="Resources" icon="database">
    Structured content retrievable via URIs (`agent.list_resources`, `agent.read_resource`).
  </Card>

  <Card title="Prompts" icon="message-lines">
    Parameterised templates listed with `agent.list_prompts` and fetched via `agent.get_prompt`.
  </Card>

  <Card title="Roots" icon="folder-tree">
    Named filesystem locations agents can browse; list with `agent.list_roots`.
  </Card>

  <Card title="Elicitation" icon="question-circle">
    Servers can pause a tool to request structured user input; see the elicitation example under `examples/mcp`.
  </Card>

  <Card title="Sampling" icon="sparkles">
    Some servers provide LLM completion endpoints; try the sampling demo in [`examples/mcp`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp).
  </Card>
</CardGroup>

[Supported Capabilities →](/mcp-agent-sdk/mcp/supported-capabilities) covers each primitive in depth.

## Example-driven overview

The quickest way to learn is to run the projects in [`examples/mcp`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp):

| Example                                                                                                                  | Focus                                                        | Transport         |
| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | ----------------- |
| [`mcp_streamable_http`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp/mcp_streamable_http)             | Connect to a remote HTTP MCP server with streaming responses | `streamable_http` |
| [`mcp_sse`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp/mcp_sse)                                     | Subscribe to an SSE MCP server                               | `sse`             |
| [`mcp_websockets`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp/mcp_websockets)                       | Bi-directional WebSocket communication                       | `websocket`       |
| [`mcp_prompts_and_resources`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp/mcp_prompts_and_resources) | List and consume prompts/resources                           | stdio             |
| [`mcp_roots`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp/mcp_roots)                                 | Browse server roots (filesystem access)                      | stdio             |
| [`mcp_elicitation`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp/mcp_elicitation)                     | Handle elicitation (interactive prompts)                     | stdio             |

Each example includes a minimal server configuration and client code that connects via `gen_client`.

## Configuring servers

Add servers to `mcp_agent.config.yaml`:

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

    docs_api:
      transport: "streamable_http"
      url: "https://api.example.com/mcp"
      headers:
        Authorization: "Bearer ${DOCS_API_TOKEN}"
```

Store secrets in `mcp_agent.secrets.yaml`, environment variables, or preload settings (see [Specify Secrets](/mcp-agent-sdk/core-components/specify-secrets)).

## Using MCP capabilities from an agent

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

agent = Agent(
    name="mcp_demo",
    instruction="Use all available MCP capabilities.",
    server_names=["filesystem", "docs_api"],
)

async with agent:
    tools = await agent.list_tools()
    resources = await agent.list_resources()
    prompts = await agent.list_prompts()
    roots = await agent.list_roots()

    print("Tools:", [t.name for t in tools.tools])
    print("Resources:", [r.uri for r in resources.resources])
```

Common API calls:

* `await agent.call_tool("tool_name", arguments={...})`
* `await agent.read_resource(uri)`
* `await agent.get_prompt(name, arguments)`
* `await agent.list_roots()`

AugmentedLLMs inherit these capabilities automatically.

## Lightweight MCP client (`gen_client`)

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

app = MCPApp(name="mcp_client_demo")

async def main():
    async with app.run():
        async with gen_client("filesystem", app.server_registry, context=app.context) as session:
            tools = await session.list_tools()
            print("Tools:", [t.name for t in tools.tools])
```

For persistent connections or aggregators, see [Connecting to MCP Servers](/mcp-agent-sdk/core-components/connecting-to-mcp-servers).

## Authentication

* Static headers/API keys go in `headers` and pull values from secrets or env variables.
* OAuth flows (loopback, interactive tool flow, pre-authorised tokens) are fully supported; see [Server Authentication](/mcp-agent-sdk/mcp/server-authentication).
* Examples under [`examples/basic/oauth_basic_agent`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/oauth_basic_agent) and [`examples/oauth`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth) demonstrate each pattern.

## Related documentation

* [Connecting to MCP Servers](/mcp-agent-sdk/core-components/connecting-to-mcp-servers)
* [Server Authentication](/mcp-agent-sdk/mcp/server-authentication)
* [Agent Servers](/mcp-agent-sdk/mcp/agent-as-mcp-server)

## Detailed reference

### Transport configurations

<AccordionGroup>
  <Accordion title="STDIO (Standard Input/Output)">
    Best for local subprocess servers:

    ```yaml  theme={null}
    mcp:
      servers:
        filesystem:
          transport: "stdio"
          command: "npx"
          args: ["-y", "@modelcontextprotocol/server-filesystem"]
    ```
  </Accordion>

  <Accordion title="Server-Sent Events (SSE)">
    Ideal for streaming responses and near-real-time updates:

    ```yaml  theme={null}
    mcp:
      servers:
        sse_server:
          transport: "sse"
          url: "http://localhost:8000/sse"
          headers:
            Authorization: "Bearer ${SSE_TOKEN}"
    ```
  </Accordion>

  <Accordion title="WebSocket">
    Bi-directional, persistent connections:

    ```yaml  theme={null}
    mcp:
      servers:
        websocket_server:
          transport: "websocket"
          url: "ws://localhost:8001/ws"
    ```
  </Accordion>

  <Accordion title="Streamable HTTP">
    HTTP servers with streaming support:

    ```yaml  theme={null}
    mcp:
      servers:
        http_server:
          transport: "streamable_http"
          url: "https://api.example.com/mcp"
          headers:
            Authorization: "Bearer ${API_TOKEN}"
    ```
  </Accordion>
</AccordionGroup>

### Build a minimal MCP server

```python title="demo_server.py" theme={null}
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Resource Demo MCP Server")

@mcp.resource("demo://docs/readme")
def get_readme():
    """Provide the README file content."""
    return "# Demo Resource Server\n\nThis is a sample README resource."

@mcp.prompt()
def echo(message: str) -> str:
    """Echo the provided message."""
    return f"Prompt: {message}"

if __name__ == "__main__":
    mcp.run()
```

### Agent configuration for that server

```yaml title="mcp_agent.config.yaml" theme={null}
execution_engine: asyncio

mcp:
  servers:
    demo:
      command: "python"
      args: ["demo_server.py"]

openai:
  default_model: "gpt-4o-mini"
```

### Using tools, resources, prompts, and roots

```python  theme={null}
# Tools
result = await agent.call_tool("read_file", {"path": "/data/config.json"})

# Resources
resource = await agent.read_resource("file:///data/report.pdf")

# Prompts
prompt = await agent.get_prompt("code_review", {"language": "python", "file": "main.py"})

# Roots
roots = await agent.list_roots()
```

### Elicitation example

```python  theme={null}
from mcp.server.fastmcp import FastMCP, Context
from mcp.server.elicitation import (
    AcceptedElicitation,
    DeclinedElicitation,
    CancelledElicitation,
)
from pydantic import BaseModel, Field

mcp = FastMCP("Interactive Server")

@mcp.tool()
async def deploy_application(app_name: str, environment: str, ctx: Context) -> str:
    class DeploymentConfirmation(BaseModel):
        confirm: bool = Field(description="Confirm deployment?")
        notify_team: bool = Field(default=False)
        message: str = Field(default="")

    result = await ctx.elicit(
        message=f"Confirm deployment of {app_name} to {environment}?",
        schema=DeploymentConfirmation,
    )

    match result:
        case AcceptedElicitation(data=data):
            return "Deployed" if data.confirm else "Deployment cancelled"
        case DeclinedElicitation():
            return "Deployment declined"
        case CancelledElicitation():
            return "Deployment cancelled"
```

### Capability matrix

| Primitive   | STDIO | SSE | WebSocket | HTTP | Status                 |
| ----------- | ----- | --- | --------- | ---- | ---------------------- |
| Tools       | ✅     | ✅   | ✅         | ✅    | Fully supported        |
| Resources   | ✅     | ✅   | ✅         | ✅    | Fully supported        |
| Prompts     | ✅     | ✅   | ✅         | ✅    | Fully supported        |
| Roots       | ✅     | ✅   | ✅         | ✅    | Fully supported        |
| Elicitation | ✅     | ✅   | ✅         | ✅    | Fully supported        |
| Sampling    | ✅     | ✅   | ✅         | ✅    | Supported via examples |

### Example gallery

<CardGroup cols={2}>
  <Card title="Prompts & Resources" icon="github" href="https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp/mcp_prompts_and_resources">
    Complete example with prompts and resources
  </Card>

  <Card title="MCP Server Examples" icon="code" href="https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp">
    All MCP primitive examples
  </Card>

  <Card title="Agent Server" icon="server" href="https://github.com/lastmile-ai/mcp-agent/tree/main/examples/mcp_agent_server">
    Agents as MCP servers with all primitives
  </Card>

  <Card title="MCP Specification" icon="book" href="https://modelcontextprotocol.io/specification">
    Official MCP specification
  </Card>
</CardGroup>

## Related documentation

* [Connecting to MCP Servers](/mcp-agent-sdk/core-components/connecting-to-mcp-servers)
* [Server Authentication](/mcp-agent-sdk/mcp/server-authentication)
* [Agent Servers](/mcp-agent-sdk/mcp/agent-as-mcp-server)


# Server Authentication
Source: https://docs.mcp-agent.com/mcp-agent-sdk/mcp/server-authentication

Configure API keys and OAuth when connecting to MCP servers

mcp-agent connects to MCP servers using the credentials you provide in `mcp_agent.config.yaml`, `mcp_agent.secrets.yaml`, or environment variables. This page shows the common patterns and points to runnable examples.

## Quick reference

* **API keys / custom headers** – set `headers` on the server definition and load secrets from `mcp_agent.secrets.yaml` or environment variables.
* **OAuth (interactive loopback)** – use the same configuration as [`examples/basic/oauth_basic_agent`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/oauth_basic_agent); mcp-agent opens a browser, captures the callback, and stores tokens for reuse.
* **OAuth (authorization-code with server interaction)** – follow [`examples/oauth/interactive_tool`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/interactive_tool); the MCP server issues `auth/request` messages when a token is missing.
* **Pre-authorised tokens** – seed tokens ahead of time as in [`examples/oauth/pre_authorize`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/pre_authorize); useful for background workflows or Temporal deployments.
* **Token storage** – configure memory (default) or Redis in `settings.oauth.token_store`.

Throughout, use [Specify Secrets](/mcp-agent-sdk/core-components/specify-secrets) to manage sensitive values (secrets file, environment variables, or `MCP_APP_SETTINGS_PRELOAD`).

## Header-based authentication

For servers that require static API keys or custom headers, add them directly to the server configuration and load the secret from your secrets file or environment:

```yaml mcp_agent.config.yaml theme={null}
mcp:
  servers:
    docs_api:
      transport: "streamable_http"
      url: "https://api.example.com/mcp"
      headers:
        Authorization: "Bearer ${DOCS_API_TOKEN}"
```

```yaml mcp_agent.secrets.yaml theme={null}
DOCS_API_TOKEN: "sk-..."
```

At runtime mcp-agent resolves `${DOCS_API_TOKEN}` from the secrets file or environment and injects it into every request.

## OAuth basics

OAuth configuration is split into two pieces:

1. **Global OAuth settings** (`settings.oauth`) – token storage, loopback ports, and general behavior.
2. **Per-server OAuth settings** (`mcp.servers[].auth.oauth`) – provider-specific details such as client ID, scopes, or whether the `resource` parameter is supported.

### Global configuration

```yaml mcp_agent.config.yaml theme={null}
oauth:
  token_store:
    backend: redis        # or "memory" (default)
    redis_url: ${OAUTH_REDIS_URL}
  loopback_ports: [33418, 33419, 33420]  # used by the loopback callback server
```

Provide secrets via environment variables, a secrets file, or preload:

```bash  theme={null}
export OAUTH_REDIS_URL="redis://127.0.0.1:6379"
```

When Redis is configured, tokens survive process restarts. Without Redis, tokens are stored in memory for the lifetime of the app.

### Per-server configuration

```yaml mcp_agent.config.yaml theme={null}
mcp:
  servers:
    github:
      command: "uvx"
      args: ["mcp-server-github"]
      auth:
        oauth:
          enabled: true
          client_id: ${GITHUB_CLIENT_ID}
          client_secret: ${GITHUB_CLIENT_SECRET}
          scopes: ["repo", "read:user"]
          redirect_uri_options:
            - "http://127.0.0.1:33418/callback"
          include_resource_parameter: false  # GitHub does not accept RFC 8707 resource
```

```yaml mcp_agent.secrets.yaml theme={null}
GITHUB_CLIENT_ID: "..."
GITHUB_CLIENT_SECRET: "..."
```

This matches the configuration in [`examples/basic/oauth_basic_agent`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/oauth_basic_agent).

## OAuth flows in practice

### Loopback (client-only) flow

When `auth.oauth.enabled` is true and no token is cached, mcp-agent:

1. Launches a loopback HTTP listener on one of the `loopback_ports`.
2. Opens the provider login page in the user’s browser.
3. Receives the authorization code at the loopback URL and exchanges it for an access token.
4. Stores the token in the configured token store (memory or Redis).

Subsequent runs reuse the cached token. Try the [`oauth_basic_agent` example](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/oauth_basic_agent) to see the flow end-to-end.

### Interactive tool flow

Servers can also request authorization during tool execution by emitting `auth/request` messages. The [`examples/oauth/interactive_tool`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/interactive_tool) project demonstrates this pattern:

* The MCP server (backed by mcp-agent) exposes a tool that talks to the GitHub MCP server.
* If no token is cached, the server requests authorization; the client opens the browser and resumes once the user approves.
* Tokens are stored via the same `settings.oauth` configuration.

### Pre-authorised tokens

Sometimes workflows run in the background (for example on Temporal workers) and cannot open a browser. Pre-seed tokens using the `workflows-store-credentials` tool before the workflow runs. The [`examples/oauth/pre_authorize`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/pre_authorize) folder shows how:

1. Obtain a token out-of-band (using a previous flow or provider tooling).
2. Call `workflows-store-credentials` with the token and desired server identity.
3. Run the workflow; it reads the cached token without additional prompts.

You can store tokens in memory or Redis; Redis is recommended when multiple worker processes need access.

## Secrets and environment variables

For local development, keep OAuth credentials in `mcp_agent.secrets.yaml` (gitignored by default). In production or CI/CD, prefer environment variables or `MCP_APP_SETTINGS_PRELOAD` to avoid writing plaintext files:

```bash  theme={null}
export MCP_APP_SETTINGS_PRELOAD="$(python - <<'PY'
from pydantic_yaml import to_yaml_str
from mcp_agent.config import Settings, MCPSettings, MCPServerSettings, OAuthSettings

print(to_yaml_str(Settings(
    oauth=OAuthSettings(),
    mcp=MCPSettings(servers={
        "github": MCPServerSettings(
            command="uvx",
            args=["mcp-server-github"],
            auth={"oauth": {
                "enabled": True,
                "client_id": "your-client-id",
                "client_secret": "your-client-secret",
            }}
        )
    })
)))
PY
)"
```

Setting `MCP_APP_SETTINGS_PRELOAD_STRICT=true` causes the app to fail fast if the preload cannot be parsed.

## Debugging tips

* Set `logger.level: debug` in `mcp_agent.config.yaml` to inspect OAuth requests and token caching.
* Cached tokens live under `context.token_store`/`context.token_manager`; inspect them when writing custom automation.
* For Redis-backed storage, ensure `OAUTH_REDIS_URL` is reachable from both client and worker processes.

## Related links

* [Specify Secrets](/mcp-agent-sdk/core-components/specify-secrets)
* [Connecting to MCP Servers](/mcp-agent-sdk/core-components/connecting-to-mcp-servers)
* [OAuth basic agent example](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/oauth_basic_agent)
* [Interactive OAuth tool example](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/interactive_tool)
* [Pre-authorise workflow example](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/pre_authorize)


# MCP Agent SDK Overview
Source: https://docs.mcp-agent.com/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>


# CLI Reference
Source: https://docs.mcp-agent.com/reference/cli

Work with mcp-agent projects and MCP Agent Cloud from the command line.

The `mcp-agent` CLI is the primary interface for project scaffolding, deployment, and day‑to‑day management of MCP Agent Cloud. Run commands ad hoc with `uvx mcp-agent …` (no install required). If `mcp-agent` is listed in your project dependencies, `uv run mcp-agent …` executes inside that environment.

<Tip>
  Every command honours the global flags `--verbose/-v`, `--quiet/-q`, `--format <text|json|yaml>`, `--color/--no-color`, and `--version`.
</Tip>

## Quick reference

| Command                              | Purpose                                             | Example                                                                     |
| :----------------------------------- | :-------------------------------------------------- | :-------------------------------------------------------------------------- |
| `login`                              | Authenticate with MCP Agent Cloud.                  | `uvx mcp-agent login --no-open`                                             |
| `init`                               | Scaffold a project from a template.                 | `uvx mcp-agent init --template basic --dir apps/agent`                      |
| `init --quickstart`                  | Copy a curated quickstart example.                  | `uvx mcp-agent init --quickstart workflow --dir ./workflow-demo`            |
| `deploy <APP_NAME>`                  | Package the current directory and deploy it.        | `uvx mcp-agent deploy research-agent --non-interactive`                     |
| `cloud servers list`                 | List deployed or configured servers.                | `uvx mcp-agent cloud servers list --filter prod --format json`              |
| `install --client claude_code <URL>` | Register a deployed server with a local MCP client. | `uvx mcp-agent install https://srv_abc.deployments... --client claude_code` |

## Primary workflows

### Log in to MCP Agent Cloud

```bash  theme={null}
uvx mcp-agent login
```

| Option           | Description                                              |
| :--------------- | :------------------------------------------------------- |
| `--api-key TEXT` | Provide an existing API key (also reads `MCP_API_KEY`).  |
| `--no-open`      | Prevent the CLI from opening a browser tab during login. |

After authenticating, `uvx mcp-agent cloud auth whoami` confirms the active account (use `uv run mcp-agent …` if you prefer to stay inside your project environment). Run `uvx mcp-agent cloud auth logout` to clear stored credentials.

### Initialise a project (`mcp-agent init`)

Recent CLI changes fold the old `quickstart` command into `mcp-agent init`. You can now scaffold config files or copy full examples from one entry point.

| Flag                  | Description                                                                 |
| :-------------------- | :-------------------------------------------------------------------------- |
| `--dir, -d PATH`      | Destination directory (defaults to `.`).                                    |
| `--template, -t TEXT` | Scaffolding template.                                                       |
| `--quickstart TEXT`   | Copy an example project (backwards compatible with `mcp-agent quickstart`). |
| `--force, -f`         | Overwrite existing files.                                                   |
| `--no-gitignore`      | Skip writing `.gitignore`.                                                  |
| `--list, -l`          | Display available templates with descriptions.                              |
| `interactive`         | Guided prompts for template selection and configuration.                    |

**Scaffolding templates**

| Template  | What you get                                                  |
| :-------- | :------------------------------------------------------------ |
| `basic`   | Asyncio agent with filesystem & fetch servers plus `main.py`. |
| `server`  | MCP server starter with workflow + parallel agent examples.   |
| `token`   | Token accounting example with telemetry and monitoring hooks. |
| `factory` | Router-backed agent factory pattern.                          |
| `minimal` | Bare configuration files—bring your own application code.     |

**Quickstart examples (`--quickstart <name>`)**

| Template                                       | Contents                                                                                                         |
| :--------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |
| `workflow`                                     | Every workflow pattern (router, deep orchestrator, swarm, parallel).                                             |
| `researcher`                                   | Research assistant use case with routing and evaluation hooks.                                                   |
| `data-analysis`                                | Financial analysis agent that demonstrates multi-server orchestration.                                           |
| `state-transfer`                               | Workflow router showcasing explicit state passing.                                                               |
| `mcp-basic-agent`                              | Finder agent from the README, ready to run via `uvx python main.py` or `uv run main.py`.                         |
| `token-counter`                                | Structured logging + token metering starter.                                                                     |
| `agent-factory`                                | Agent factory with declarative routing rules.                                                                    |
| `basic-agent-server`, `reference-agent-server` | Complete MCP server implementations (asyncio + reference).                                                       |
| `elicitation`, `sampling`, `notifications`     | Packaged MCP server variations installed via `mcp_agent.data.examples`.                                          |
| `hello-world`                                  | Basic cloud-deployable example with simple tool calls.                                                           |
| `mcp`                                          | Comprehensive MCP server example showcasing tools, sampling, elicitation, notifications, prompts, and resources. |
| `temporal`                                     | Temporal integration example with durable workflows and pause/resume patterns.                                   |
| `chatgpt-app`                                  | ChatGPT App with interactive UI widgets (coin flip example with React frontend).                                 |

Examples:

```bash  theme={null}
uvx mcp-agent init --template basic --dir apps/research-agent
uvx mcp-agent init --quickstart workflow --dir ./workflow-demo --force
uvx mcp-agent init --list
```

### Deploy an application (`mcp-agent deploy`)

```bash  theme={null}
uvx mcp-agent deploy research-app \
  --config-dir ./deploy \
  --ignore-file .deployignore \
  --non-interactive
```

| Option                        | Description                                                                                                    |
| :---------------------------- | :------------------------------------------------------------------------------------------------------------- |
| `APP_NAME`                    | Optional friendly name for the deployment.                                                                     |
| `--config-dir, -c DIRECTORY`  | Directory containing configuration and source (defaults to the working directory).                             |
| `--working-dir, -w DIRECTORY` | Base directory for resolving relative paths.                                                                   |
| `--app-description, -d TEXT`  | Update the app description shown in Cloud.                                                                     |
| `--non-interactive`           | Fail instead of prompting (crucial for CI/CD).                                                                 |
| `--no-auth/--auth`            | Toggle unauthenticated server access (preserves existing setting by default).                                  |
| `--ignore-file FILE`          | Gitignore-style patterns (precedence: CLI > `.mcpacignore` in `--config-dir` > `.mcpacignore` in working dir). |
| `--git-tag / --no-git-tag`    | Create a local git tag for the deployment.                                                                     |
| `--retry-count INTEGER`       | Deployment retry attempts (1–10, default 3).                                                                   |
| `--api-url`, `--api-key`      | Override Cloud endpoint or use specific credentials (respect env vars).                                        |

Use `--dry-run` for validation without uploading, and let the CLI guide you through classifying developer versus user secrets.

### List deployed servers (`mcp-agent cloud servers list`)

```bash  theme={null}
uvx mcp-agent cloud servers list --filter prod --sort-by -created --format json
uvx mcp-agent cloud servers describe srv_123
```

| Option      | Description                                                                 |
| :---------- | :-------------------------------------------------------------------------- |
| `--limit`   | Maximum number of entries (default 100).                                    |
| `--filter`  | Case-insensitive filter applied to server name, description, or status.     |
| `--sort-by` | Sort by `name`, `created`, or `status` (prefix with `-` for reverse order). |
| `--format`  | Output format (`text`, `json`, `yaml`).                                     |

`cloud servers describe <SERVER_ID>` and `cloud servers workflows <SERVER_ID>` share the same formatting flag and surface deep metadata such as server URLs, current status, and published workflows.

### Install a deployed MCP server (`mcp-agent install`)

```bash  theme={null}
uvx mcp-agent install https://srv_abc.deployments.mcp-agent.com \
  --client claude_desktop \
  --name research-buddy \
  --dry-run
```

| Option                   | Description                                                                          |
| :----------------------- | :----------------------------------------------------------------------------------- |
| `SERVER_IDENTIFIER`      | HTTPS or SSE URL from the deployment dashboard.                                      |
| `--client, -c TEXT`      | Destination client (`vscode`, `claude_code`, `cursor`, `claude_desktop`, `chatgpt`). |
| `--name, -n TEXT`        | Override the generated client entry name.                                            |
| `--dry-run`              | Print the configuration block without writing to disk.                               |
| `--force, -f`            | Overwrite existing entries.                                                          |
| `--api-url`, `--api-key` | Override Cloud endpoints or credentials (fallback to env vars).                      |

For authenticated clients, the CLI injects `MCP_API_KEY` automatically. Use `--dry-run` when sharing configuration snippets or validating changes before committing them.

### Tail logs for a running application (`mcp-agent cloud logger tail`)

```bash  theme={null}
uvx mcp-agent cloud logger tail srv_abc123 --follow
```

| Option                          | Description                                                                                                  |           |
| :------------------------------ | :----------------------------------------------------------------------------------------------------------- | --------- |
| `--follow/-f`                   | Stream logs continuously (mutually exclusive with `--since`, `--limit`, `--order-by`, `--asc`, or `--desc`). |           |
| `--grep`                        | Filter log messages using a regex (e.g., \`--grep "ERROR                                                     | WARN"\`). |
| `--format`                      | Render output as `text`, `json`, or `yaml`.                                                                  |           |
| `--limit/-n`                    | Maximum entries to fetch in batch mode (default 100).                                                        |           |
| `--since`                       | Show logs from a relative duration (e.g., `1h`, `30m`).                                                      |           |
| `--order-by`, `--asc`, `--desc` | Sort batched results (default is newest first).                                                              |           |

Use streaming (`--follow`) when you need real-time visibility; combine `--since` with `--grep` to audit historical runs.

### Configure a deployed server (`mcp-agent cloud configure`)

```bash  theme={null}
uvx mcp-agent cloud configure \
  --id https://srv_base.deployments.mcp-agent.com/mcp \
  --secrets-file team-secrets.yaml
```

| Option                     | Description                                                                         |
| :------------------------- | :---------------------------------------------------------------------------------- |
| `--id/-i`                  | Server URL to clone and configure with your own secrets.                            |
| `--secrets-file/-s`        | YAML file containing values for required user secrets.                              |
| `--secrets-output-file/-o` | Destination for prompted secrets (defaults to `mcp_agent.configured.secrets.yaml`). |
| `--params`                 | List required secrets and exit without configuring.                                 |
| `--dry-run`                | Validate required parameters using mock clients without persisting secrets.         |
| `--api-url`, `--api-key`   | Override Cloud endpoint or credentials.                                             |

This workflow lets you adopt a published server template, supply your credentials (LLM keys, database passwords, etc.), and produce a new server deployment associated with your account.

## Cloud management commands

* **Apps (`mcp-agent cloud apps …`)** – manage logical applications.
  * `apps status <APP_ID>` displays health, version, and associated servers.
  * `apps workflows <APP_ID>` enumerates workflows exposed by that app.
  * `apps delete <APP_ID>` removes the application; `apps update` refreshes metadata.

* **Logs (`mcp-agent cloud logger tail …`)** – fetch or stream logs.
  * `--since 1h`, `--grep`, `--limit/-n`, and `--order-by timestamp|severity` tune batch retrieval.
  * `--follow/-f` enables streaming (mutually exclusive with the filtering flags).
  * `--format text|json|yaml` controls output.

* **Configure (`mcp-agent cloud configure --id <SERVER_URL> …`)** – collect user secrets after deployment.
  * `--secrets-file/-s` reuses an authored secrets.yaml.
  * `--secrets-output-file/-o` chooses where prompted secrets are written (defaults to `mcp_agent.configured.secrets.yaml`).
  * `--params` lists required secrets and exits.
  * `--dry-run` validates using mock clients without persisting anything.
  * `--api-url`, `--api-key` allow per-command overrides.

* **Auth (`mcp-agent cloud auth …`)** – the same login, whoami, and logout commands exposed at the top level, handy for scripts.

* **Workflows (`mcp-agent cloud workflows …`)** – inspect and control durable workflow runs.
  * `workflows list <SERVER|URL> [--format text|json|yaml]` lists workflow definitions.
  * `workflows runs <SERVER|URL>` surfaces recent executions.
  * `workflows describe|status <SERVER> <RUN_ID>` shows execution details.
  * `workflows resume|suspend|cancel <SERVER> <RUN_ID>` manipulates in-flight runs.

Example session:

```bash  theme={null}
# Inspect available servers
uvx mcp-agent cloud servers list

# Tail logs for a specific deployment
uvx mcp-agent cloud logger tail srv_abc123 --follow

# Resume a paused workflow run
uvx mcp-agent cloud workflows resume srv_abc123 run_xyz789

# Review required secrets before configuring an app
uvx mcp-agent cloud configure --id https://srv_abc123.deployments.mcp-agent.com/mcp --params
```

## Local development helpers

* `mcp-agent dev start` – run your app locally with optional file watching (auto-detects `main.py`, then `agent.py` when `--script` is omitted). Companion subcommands include `dev chat`, `dev go`, `dev invoke`, `dev serve`, `dev logs`, `dev keys`, and `dev models`.
* `mcp-agent config show|check|edit|builder` – inspect YAML, validate schemas, or generate config files with an interactive questionnaire (`builder` supports templates and expert mode).
* `mcp-agent doctor` – end-to-end diagnostics across configuration, secrets, provider keys, required MCP servers, and network connectivity.
* `mcp-agent install --dry-run` – even for local experiments, emit ready-to-paste client snippets without touching disk.

These commands respect the same settings discovery as the runtime: preload strings (`MCP_APP_SETTINGS_PRELOAD`), explicit paths, discovered `mcp_agent.config.yaml`/`mcp_agent.secrets.yaml`, and environment variables. Append `--help` whenever you need the latest options or examples.


# Configuration
Source: https://docs.mcp-agent.com/reference/configuration

Understand how mcp-agent loads settings, manages secrets, and connects to providers, servers, and telemetry backends.

## Overview

`mcp-agent` reads configuration from YAML files, environment variables, and optional preload strings to assemble a `Settings` object that powers every `MCPApp`. This page explains the load order, file format, and key sections you will customize for local development, automated workflows, and MCP Agent Cloud deployments.

<Tip>
  Use `uvx mcp-agent config builder` for an interactive wizard that generates both config and secrets files. Run `uvx mcp-agent config show --secrets` (or `uv run mcp-agent …` inside your project) at any time to see what the CLI discovers.
</Tip>

## How settings are loaded

* **Preload string** — if `MCP_APP_SETTINGS_PRELOAD` is set, the CLI and `MCPApp` parse it first. Set `MCP_APP_SETTINGS_PRELOAD_STRICT=true` to fail fast on invalid YAML.
* **Explicit paths** — CLI commands such as `dev serve --config` or code that calls `get_settings(config_path=...)` override the search logic.
* **Discovered files** — `Settings.find_config()` and `Settings.find_secrets()` scan the current directory, each parent, `./.mcp-agent/`, and finally `~/.mcp-agent/`.
* **Secrets merge** — `mcp_agent.secrets.yaml` is merged over the main config so sensitive values override defaults.
* **Environment variables** — every field exposes aliases like `OPENAI_API_KEY`, `ANTHROPIC_DEFAULT_MODEL`, or nested keys such as `MCP__SERVERS__filesystem__args=...`. A `.env` file in the project root is read automatically.
* **Programmatic overrides** — passing a `Settings` instance to `MCPApp(settings=...)` takes precedence over disk files.

## Primary files

<CardGroup cols={2}>
  <Card title="mcp_agent.config.yaml" icon="gear">
    Main configuration: execution engine, MCP servers, logging, providers, OAuth, and temporal settings.
  </Card>

  <Card title="mcp_agent.secrets.yaml" icon="key">
    Sensitive material such as API keys, OAuth client secrets, and passwords. Always add this file to `.gitignore`.
  </Card>
</CardGroup>

### Minimal example

```yaml  theme={null}
# mcp_agent.config.yaml
name: research_agent
execution_engine: asyncio

logger:
  transports: [console]
  level: info
  progress_display: true

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

openai:
  default_model: gpt-4o-mini

anthropic:
  default_model: claude-3-5-sonnet-20241022
```

```yaml  theme={null}
# mcp_agent.secrets.yaml
openai:
  api_key: sk-...

anthropic:
  api_key: sk-ant-...
```

### Programmatic configuration

```python  theme={null}
from mcp_agent.app import MCPApp
from mcp_agent.config import Settings, MCPSettings, MCPServerSettings, LoggerSettings

settings = Settings(
    name="programmatic_agent",
    logger=LoggerSettings(transports=["console"], level="debug"),
    mcp=MCPSettings(
        servers={
            "fetch": MCPServerSettings(command="uvx", args=["mcp-server-fetch"]),
        }
    ),
)

app = MCPApp(settings=settings)
```

## Secrets management

* Prefer storing secrets in `mcp_agent.secrets.yaml` or environment variables; the CLI and `get_settings()` automatically merge them.
* For temporary runs (CI, notebooks), serialize a `Settings` instance and set `MCP_APP_SETTINGS_PRELOAD` to the YAML string. This keeps secrets out of disk.
* When deploying with `mcp-agent deploy`, you will be prompted to classify each secret as developer- or user-provided; the CLI generates `mcp_agent.configured.secrets.yaml` with the required runtime schema.

## Top-level keys

| Key                                                           | Type                             | Purpose                                                             |
| :------------------------------------------------------------ | :------------------------------- | :------------------------------------------------------------------ |
| `name`, `description`                                         | `str`                            | Metadata used for logging and MCP server identification.            |
| `execution_engine`                                            | `"asyncio"` \| `"temporal"`      | Selects the workflow executor backend.                              |
| `mcp`                                                         | `MCPSettings`                    | Defines all upstream MCP servers available to agents and workflows. |
| `logger`                                                      | `LoggerSettings`                 | Controls console/file logging, batching, and progress display.      |
| `otel`                                                        | `OpenTelemetrySettings`          | Configures tracing exporters for observability.                     |
| `usage_telemetry`                                             | `UsageTelemetrySettings`         | Toggles anonymous usage metrics.                                    |
| `openai`, `anthropic`, `azure`, `google`, `bedrock`, `cohere` | Provider-specific settings       | Establish API endpoints, defaults, and credentials.                 |
| `agents`                                                      | `SubagentSettings`               | Autoload additional agents from disk (Claude Code style).           |
| `authorization`                                               | `MCPAuthorizationServerSettings` | Expose your app as an OAuth-protected MCP server.                   |
| `oauth`                                                       | `OAuthSettings`                  | Global client OAuth defaults and token storage.                     |
| `temporal`                                                    | `TemporalSettings`               | Host, namespace, and queue information for durable workflows.       |

## Execution engine

The default `asyncio` engine suits most agents:

```yaml  theme={null}
execution_engine: asyncio
```

Switch to Temporal when you need durable, resumable workflows:

```yaml  theme={null}
execution_engine: temporal
temporal:
  host: "${TEMPORAL_HOST:-localhost:7233}"
  namespace: "prod"
  task_queue: "mcp-agent-prod"
  max_concurrent_activities: 25
  timeout_seconds: 120
  id_reuse_policy: allow_duplicate_failed_only
  api_key: "${TEMPORAL_API_KEY}"
```

## Logging

`LoggerSettings` controls the event logger used by `MCPApp`:

```yaml  theme={null}
logger:
  transports: [console, file]
  level: debug
  progress_display: true
  path_settings:
    path_pattern: "logs/mcp-agent-{unique_id}.jsonl"
    unique_id: timestamp
    timestamp_format: "%Y%m%d_%H%M%S"
```

* `transports` accepts any combination of `console`, `file`, or `http`.
* `path_settings` generates unique filenames per run without writing fragile scripts.
* For HTTP logging, set `http_endpoint`, `http_headers`, and `batch_size`.

## Tracing and usage telemetry

Enable OpenTelemetry exporters to ship spans and metrics:

```yaml  theme={null}
otel:
  enabled: true
  sample_rate: 0.5
  exporters:
    - console
    - file: {path: "traces/mcp-agent.jsonl"}
    - otlp: {endpoint: "https://otel.example.com:4317", headers: {Authorization: "Bearer ${OTEL_TOKEN}"}}
  service_name: "mcp-agent"
  service_version: "1.2.0"
```

Usage telemetry is opt-in by default; disable if you prefer zero reporting:

```yaml  theme={null}
usage_telemetry:
  enabled: false
```

## MCP servers

Each entry in `mcp.servers` defines how to reach an upstream MCP server. Common patterns:

```yaml  theme={null}
mcp:
  servers:
    filesystem:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
      env:
        DEBUG: "true"

    fetch:
      command: uvx
      args: ["mcp-server-fetch"]

    knowledge_api:
      transport: streamable_http
      url: "https://analysis.example.com/mcp"
      headers:
        Authorization: "Bearer ${API_TOKEN}"
      http_timeout_seconds: 30
      read_timeout_seconds: 120

    websocket_demo:
      transport: websocket
      url: "wss://demo.example.com/mcp/ws"

    remote_repo:
      transport: sse
      url: "https://git.example.com/mcp/sse"
      auth:
        api_key: "${REPO_TOKEN}"
```

* `allowed_tools` restricts which tools the LLM sees per server.
* `roots` lets you remap local directories into server roots using `file://` URIs.
* For long-running HTTP transports, set `terminate_on_close: false` to keep sessions alive.

## Server authentication and OAuth

Per-server `auth` blocks support API keys or OAuth clients:

```yaml  theme={null}
mcp:
  servers:
    github:
      transport: streamable_http
      url: "https://github.example.com/mcp"
      auth:
        oauth:
          enabled: true
          authorization_server: "https://github.com/login/oauth"
          client_id: "${GITHUB_CLIENT_ID}"
          client_secret: "${GITHUB_CLIENT_SECRET}"
          scopes: ["repo", "user:email"]
          redirect_uri_options:
            - "http://127.0.0.1:33418/callback"
          include_resource_parameter: false
```

Global OAuth defaults configure token storage and callback behaviour:

```yaml  theme={null}
oauth:
  token_store:
    backend: redis
    redis_url: "redis://localhost:6379/2"
    redis_prefix: "mcp_agent:oauth_tokens"
  flow_timeout_seconds: 300
  callback_base_url: "https://agent.example.com/internal/oauth"
  loopback_ports: [33418, 33419]
```

To secure your own MCP server with OAuth 2.0, populate the `authorization` section:

```yaml  theme={null}
authorization:
  enabled: true
  issuer_url: "https://auth.example.com"
  resource_server_url: "https://agent.example.com/mcp"
  required_scopes: ["mcp.read", "mcp.write"]
  introspection_endpoint: "https://auth.example.com/oauth/introspect"
  introspection_client_id: "${INTROSPECTION_CLIENT_ID}"
  introspection_client_secret: "${INTROSPECTION_CLIENT_SECRET}"
  expected_audiences: ["agent.example.com"]
```

## Model providers

### OpenAI-compatible APIs

```yaml  theme={null}
openai:
  default_model: gpt-4o-mini
  reasoning_effort: medium
  base_url: "https://api.openai.com/v1"
  user: "research-team"
```

* Override `base_url` to target OpenAI-compatible services such as Groq (`https://api.groq.com/openai/v1`), Together, or local Ollama (`http://localhost:11434/v1`). Provide a dummy `api_key` for services that do not check it.
* Use `default_headers` to inject custom headers when talking to proxies or gateways.

### Anthropic

```yaml  theme={null}
anthropic:
  default_model: claude-3-5-sonnet-20241022
  api_key: "${ANTHROPIC_API_KEY}"
```

Run Claude via Bedrock or Vertex AI by adjusting the provider and credentials:

```yaml  theme={null}
anthropic:
  provider: bedrock
  default_model: "anthropic.claude-3-5-sonnet-20241022-v2:0"
  aws_region: "us-east-1"
  aws_access_key_id: "${AWS_ACCESS_KEY_ID}"
  aws_secret_access_key: "${AWS_SECRET_ACCESS_KEY}"
```

### Azure OpenAI

```yaml  theme={null}
azure:
  endpoint: "https://my-resource.openai.azure.com"
  api_key: "${AZURE_OPENAI_API_KEY}"
  api_version: "2024-10-01-preview"
  azure_deployment: "gpt-4o-mini"
```

Set `credential_scopes` if you authenticate with Entra ID tokens instead of API keys.

### Google Gemini and Vertex AI

```yaml  theme={null}
google:
  default_model: gemini-2.0-flash
  api_key: "${GOOGLE_API_KEY}"
  vertexai: false
```

Enable Vertex AI by toggling `vertexai` and providing project metadata:

```yaml  theme={null}
google:
  vertexai: true
  project: "my-gcp-project"
  location: "us-central1"
  default_model: "gemini-1.5-flash"
```

### Bedrock (generic) and Cohere

```yaml  theme={null}
bedrock:
  aws_access_key_id: "${AWS_ACCESS_KEY_ID}"
  aws_secret_access_key: "${AWS_SECRET_ACCESS_KEY}"
  aws_region: "us-west-2"

cohere:
  api_key: "${COHERE_API_KEY}"
```

## Subagents

Use `agents` to auto-load agent specifications from disk (Claude Code compatible):

```yaml  theme={null}
agents:
  enabled: true
  search_paths:
    - ".claude/agents"
    - "~/.mcp-agent/agents"
  pattern: "**/*.json"
  definitions:
    - name: "reviewer"
      instruction: "Review code for defects and summarize findings."
      server_names: ["filesystem", "fetch"]
```

## Temporal configuration

When `execution_engine` is `temporal`, every workflow and task decorator wires into the Temporal SDK. Ensure the queue name matches your worker process (`uv run mcp-temporal-worker ...`):

```yaml  theme={null}
temporal:
  host: "${TEMPORAL_HOST}"
  namespace: "agents"
  task_queue: "agents-tasks"
  max_concurrent_activities: 50
  timeout_seconds: 300
  rpc_metadata:
    team: agents
```

## Example scenarios

### Local development preset

```yaml  theme={null}
name: local_playground
execution_engine: asyncio
logger:
  transports: [console]
  level: debug
  progress_display: true
mcp:
  servers:
    filesystem:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
    fetch:
      command: uvx
      args: ["mcp-server-fetch"]
openai:
  default_model: gpt-4o-mini
usage_telemetry:
  enabled: false
```

### Production with Temporal and OAuth

```yaml  theme={null}
name: research_production
execution_engine: temporal
logger:
  transports: [file]
  level: info
  path_settings:
    path_pattern: "/var/log/mcp-agent/mcp-agent-{unique_id}.jsonl"
    unique_id: session_id
temporal:
  host: "${TEMPORAL_SERVER}"
  namespace: "production"
  task_queue: "research-agents"
  api_key: "${TEMPORAL_API_KEY}"
authorization:
  enabled: true
  issuer_url: "https://auth.example.com"
  resource_server_url: "https://research.example.com/mcp"
  required_scopes: ["research.run"]
oauth:
  token_store:
    backend: redis
    redis_url: "${REDIS_URL}"
mcp:
  servers:
    github:
      transport: streamable_http
      url: "https://api.example.com/github/mcp"
      auth:
        oauth:
          enabled: true
          authorization_server: "https://github.com/login/oauth"
          client_id: "${GITHUB_CLIENT_ID}"
          client_secret: "${GITHUB_CLIENT_SECRET}"
          scopes: ["repo", "workflow"]
openai:
  default_model: gpt-4o
anthropic:
  default_model: claude-3-5-sonnet-20241022
```

For CLI usage, see the [CLI reference](/reference/cli), and explore decorator capabilities in the [Decorators reference](/reference/decorators).


# Decorators Reference
Source: https://docs.mcp-agent.com/reference/decorators

Author tools and workflows with MCPApp decorators.

# Decorators

`MCPApp` exposes a small set of decorators that register tools, workflows, and workflow tasks. The decorators are engine-aware: when you switch from the default asyncio executor to Temporal, the same annotations automatically apply the appropriate Temporal SDK wrappers.

| Decorator              | Applies to            | Purpose                                                                  |
| :--------------------- | :-------------------- | :----------------------------------------------------------------------- |
| `@app.tool`            | sync function         | Exposes a blocking function as an MCP tool.                              |
| `@app.async_tool`      | async function        | Registers an async tool and publishes it through FastMCP.                |
| `@app.workflow`        | `Workflow` subclass   | Declares a workflow class and adapts it for the active execution engine. |
| `@app.workflow_run`    | async method          | Marks the primary `run` coroutine for a workflow.                        |
| `@app.workflow_task`   | async function/method | Registers an activity task reusable across workflows.                    |
| `@app.workflow_signal` | async method          | Handles inbound workflow signals (Temporal-friendly).                    |

## Tool decorators

Tools expose code as MCP functions that agents and LLMs can call. Both decorators accept the same keyword arguments:

| Parameter           | Description                                                                                                        |
| :------------------ | :----------------------------------------------------------------------------------------------------------------- |
| `name`              | Override the exported MCP tool name (defaults to the function name).                                               |
| `title`             | Short display label for clients.                                                                                   |
| `description`       | Human-readable description; the function docstring is used when omitted.                                           |
| `annotations`       | Supply a `ToolAnnotations` object or mapping for MCP metadata.                                                     |
| `icons`             | Provide one or more `Icon` instances or mappings for client rendering.                                             |
| `meta`              | Arbitrary metadata forwarded to FastMCP.                                                                           |
| `structured_output` | Set to `True` to hint that the result is structured JSON; some LLMs will choose schema-aware models automatically. |

### `@app.tool` — synchronous tools

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

app = MCPApp(name="reporting")

class Summary(BaseModel):
    title: str
    verdict: str

@app.tool(description="Summarise a raw document into a headline and verdict.", structured_output=True)
def summarise_document(text: str) -> Summary:
    """Summarise content deterministically."""
    title = text.splitlines()[0][:120]
    verdict = "APPROVED" if "ship it" in text.lower() else "NEEDS REVIEW"
    return Summary(title=title, verdict=verdict)
```

* The decorator validates the signature up-front; missing type hints or unsupported default values raise an error during import.
* `@app.tool` automatically creates a hidden workflow so the tool is reachable via both `callTool` and the workflow endpoints (`run`, `get_status`) exposed by FastMCP.
* The function executes inside the app event loop; heavy work should offload itself (for example, using `asyncio.to_thread`).

### `@app.async_tool` — asynchronous tools

```python  theme={null}
import httpx

@app.async_tool(
    name="fetch_page",
    description="Fetch raw HTML from an HTTP endpoint.",
    icons=[{"emoji": "🌐"}],
)
async def fetch_page(url: str, *, timeout: int = 20) -> str:
    async with httpx.AsyncClient(timeout=timeout) as client:
        response = await client.get(url)
        response.raise_for_status()
        return response.text
```

* The coroutine is awaited directly, so you can call other async APIs without wrappers.
* When Temporal is active, the decorated function is wrapped with `workflow.activity` metadata automatically.

## Workflow decorator suite

Workflows orchestrate complex sequences, combining tasks, tools, and signals. Every workflow subclass must inherit from `mcp_agent.executor.workflow.Workflow`.

```python  theme={null}
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 generate_outline(self, topic: str) -> str:
        outline = f"- Introduction to {topic}\n- Key findings\n- Next steps"
        self.context.logger.info("Generated outline", data={"topic": topic})
        return outline

    @app.workflow_task(retry_policy={"maximum_attempts": 3})
    async def send_to_editor(self, outline: str) -> None:
        self.context.logger.info("Sending to editor", data={"outline": outline})

    @app.workflow_signal(name="editor_feedback")
    async def editor_feedback(self, notes: str) -> None:
        self.state.feedback = notes or ""

    @app.workflow_run
    async def run(self, topic: str) -> WorkflowResult[str]:
        outline = await self.generate_outline(topic)
        await self.send_to_editor(outline)
        feedback = getattr(self.state, "feedback", "Awaiting review.")
        return WorkflowResult(value=f"{outline}\n\nEditor feedback: {feedback}")
```

### `@app.workflow`

* Registers the class with the app and applies engine-specific decorators (`workflow.defn` for Temporal, no-op for asyncio).
* An optional `workflow_id` parameter lets you export the workflow under a different name when registering.
* The decorator stores a reference to the `MCPApp`, letting workflow instances access `self.context.app`.

### `@app.workflow_run`

Wraps the `run` coroutine so that initialization, tracing, and Temporal-specific instrumentation are handled automatically. You rarely need to call it manually—applying `@app.workflow` and naming the method `run` is enough—but explicit usage lets you decorate additional entry points.

### `@app.workflow_task`

Registers a coroutine as a reusable activity. Key options:

| Option                      | Effect                                                                          |
| :-------------------------- | :------------------------------------------------------------------------------ |
| `name`                      | Override the fully qualified activity name (defaults to `<module>.<qualname>`). |
| `schedule_to_close_timeout` | Maximum wall-clock duration allowed for the task.                               |
| `retry_policy`              | Temporal retry configuration (e.g. `{"maximum_attempts": 5}`).                  |
| `**meta_kwargs`             | Arbitrary metadata stored alongside the task for inspection.                    |

The decorator enforces that the target is async; synchronous functions should wrap their blocking work with `asyncio.to_thread`.

Tasks defined outside a workflow are also supported—they are registered globally and can be reused across multiple workflows.

### `@app.workflow_signal`

Signals let external actors (humans, webhooks, other workflows) nudge a running workflow. The decorator accepts an optional `name` argument and works in both asyncio and Temporal modes.

```python  theme={null}
@app.workflow_signal(name="user_input")
async def collect_user_input(self, payload: str) -> None:
    self.context.logger.info("Received payload", data={"payload": payload})
    self.state.latest_payload = payload
```

The generated wrapper automatically strips the workflow instance (`self`) for Temporal’s signal handler signature.

<Info>
  All workflow decorators defer to the active executor. When you switch to Temporal, tasks become activities, `run` becomes a workflow entry point, and signals map to `@workflow.signal`—no additional changes required.
</Info>

## Putting it together

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

app = MCPApp(name="insight-generator")

@app.tool(description="List the MCP servers registered with this app.")
def list_servers() -> list[str]:
    return sorted((app.config.mcp.servers or {}).keys())

@app.workflow
class ResearchWorkflow(Workflow[None]):
    @app.workflow_task()
    async def gather_sources(self, query: str) -> list[str]:
        self.context.logger.info("Gathering sources", data={"query": query})
        return [f"https://example.com/search?q={query}"]

    @app.workflow_run
    async def run(self, topic: str) -> None:
        sources = await self.gather_sources(topic)
        self.context.logger.info("Workflow completed", data={"topic": topic, "sources": sources})
```

This pattern gives you:

* A reusable `list_servers` tool that exposes runtime metadata without boilerplate.
* A workflow that can run locally (asyncio) or durably (Temporal) with the same code.
* Optional signals/tasks to pause, resume, or branch as needed.

For CLI-driven workflows and deployment details, continue with the [CLI reference](/reference/cli). For configuration options that pair with these decorators, review the [Configuration reference](/reference/configuration).


# Agent Evaluation
Source: https://docs.mcp-agent.com/test-evaluate/agent-evaluation

Evaluate agent performance and reliability

Agent evaluations treat your workflow as the system under test. Connect an mcp-agent-powered agent to `mcp-eval`, run realistic scenarios, and check that it uses tools correctly, follows instructions, and produces the expected outputs.

<Info>
  Use evaluations to confirm the agent behaves as expected before you release changes.
</Info>

<Tip>
  The full agent playbook is at <a href="https://mcp-eval.ai/agent-evaluation">mcp-eval.ai/agent-evaluation</a>; reference it for extended patterns, datasets, and troubleshooting.
</Tip>

## Define the agent under test

You can point `mcp-eval` at an `AgentSpec`, an instantiated `Agent`, or a factory that builds agents on demand. For example, to test the Finder agent from `examples/basic/mcp_basic_agent`:

```python agent_under_test.py theme={null}
from mcp_eval import use_agent
from mcp_agent.agents.agent_spec import AgentSpec

use_agent(
    AgentSpec(
        name="finder",
        instruction="Locate information via fetch or filesystem tools.",
        server_names=["fetch", "filesystem"],
    )
)
```

Prefer factories when the agent keeps mutable state or long-lived connections:

```python agent_factory.py theme={null}
from mcp_eval.config import use_agent_factory
from mcp_agent.agents.agent import Agent

def make_finder():
    return Agent(
        name="finder",
        instruction="Locate information via fetch or filesystem.",
        server_names=["fetch", "filesystem"],
    )

use_agent_factory(make_finder)
```

## Choose a test style

* **Decorator tasks** (`@task`) are great for narrative scenarios and map cleanly to the patterns described in Anthropic’s *Building Effective Agents* paper.
* **Pytest** works when you want to stay inside your existing test harness.
* **Datasets** let you replay curated or generated cases against multiple agents.

The official repo includes all three styles—see the fetch server example in `lastmile-ai/mcp-eval/examples/mcp_server_fetch/tests/`.

## Write assertions that match agent expectations

`Expect` covers tool usage, quality, efficiency, and performance. Combine multiple checks in a single run:

```python agent_eval_test.py theme={null}
from mcp_eval import Expect, task

@task("Finder summarizes Example Domain")
async def test_finder_fetch(agent, session):
    response = await agent.generate_str("Fetch https://example.com and summarize it.")

    await session.assert_that(Expect.tools.was_called("fetch"))
    await session.assert_that(Expect.tools.sequence(["fetch"], allow_other_calls=True))
    await session.assert_that(
        Expect.content.contains("Example Domain"), response=response
    )
    await session.assert_that(Expect.performance.max_iterations(3))
    await session.assert_that(
        Expect.judge.llm("Summary captures the main idea", min_score=0.8),
        response=response,
    )
```

Layer efficiency expectations with path validators to mirror the workflows you built using `mcp_agent.workflows.*`:

```python path_validation.py theme={null}
await session.assert_that(
    Expect.path.efficiency(expected_tool_sequence=["fetch"], allow_extra_steps=1)
)
```

## Inspect metrics and spans

Every evaluation captures telemetry you can read during or after the test:

```python telemetry.py theme={null}
metrics = session.get_metrics()
tool_latency = metrics.tools["fetch"].avg_latency_ms
span_tree = session.get_span_tree()
```

Combine this with mcp-agent’s built-in tracing (`context.tracer`) to debug tool failures, retries, or human-input pauses.

## Scenario ideas

* **Regression suites** for workflows in `examples/workflows/`—verify orchestrators still call the same tool chain after prompt or model changes.
* **Human-in-the-loop flows**—assert that `Expect.tools.was_called("__human_input__")` fires when you send a pause signal from the `SignalRegistry`.
* **Multi-agent swarms**—ensure router decisions and downstream agents cooperate by validating tool sequences and final content.


# mcp-eval
Source: https://docs.mcp-agent.com/test-evaluate/mcp-eval

Comprehensive evaluation platform for MCP

`mcp-eval` tests Model Context Protocol servers and agents. It runs scripted scenarios, captures telemetry, and enforces assertions so you can confirm behavior is stable before releasing changes.

<Tip>
  The full documentation lives at <a href="https://mcp-eval.ai">mcp-eval.ai</a>. Keep it handy for configuration specifics, advanced examples, and release updates.
</Tip>

<Info>
  `mcp-eval` connects to your targets over MCP, executes scenarios, and records detailed metrics for every tool call.
</Info>

## Why teams run it

* Catch regressions when prompts, workflows, or model settings change
* Confirm that the right MCP tools fire in the expected order with the expected payloads
* Exercise recovery paths such as human-input pauses or fallback workflows
* Produce repeatable evidence—reports, traces, and badges—that a release is safe

## What you can cover

<Columns cols={4}>
  <Card title="Test MCP Servers" icon="server" href="./server-evaluation">
    Validate tool definitions, edge cases, and error responses before exposing servers to users
  </Card>

  <Card title="Evaluate Agents" icon="robot" href="./agent-evaluation">
    Measure tool usage, reasoning quality, and recovery behavior
  </Card>

  <Card title="Track Performance" icon="chart-line" href="https://mcp-eval.ai">
    Capture latency, token usage, and cost with built-in telemetry
  </Card>

  <Card title="Assert Quality" icon="circle-check" href="https://mcp-eval.ai/agent-evaluation">
    Combine structural checks, path validators, and LLM judges in one run
  </Card>
</Columns>

## Install mcp-eval

<CodeGroup>
  ```bash uv (recommended) theme={null}
  uv tool install mcpevals      # CLI
  uv add mcpevals               # project dependency
  mcp-eval init                 # scaffold config, tests/, and datasets/
  ```

  ```bash pip theme={null}
  pip install mcpevals
  mcp-eval init
  ```
</CodeGroup>

The `init` wizard can generate decorator tests, pytest scaffolding, and dataset examples—you can rerun it as your suite grows.

## Register what you test

After an mcp-agent workflow or aggregator is running locally:

1. **Register servers** with the same command or endpoint your agent uses:

   ```bash  theme={null}
   mcp-eval server add \
     --name fetch \
     --transport stdio \
     --command "uv" "run" "python" "-m" "mcp_servers.fetch"
   ```

2. **Register agents** by pointing to an `AgentSpec`, an instantiated `Agent`, or your `MCPApp`:

   ```yaml  theme={null}
   # tests/config/targets.yaml
   agents:
     - name: finder
       type: agent_spec
       path: ../../examples/basic/mcp_basic_agent/mcp_agent/agents/finder.py
   servers:
     - name: fetch
       transport: stdio
       command: ["uv", "run", "python", "-m", "mcp_servers.fetch"]
   ```

3. When you introduce a new workflow or capability, run `mcp-eval generate` to draft scenario ideas with LLM assistance.

## Structure evaluations

`mcp-eval` follows a code-first layout similar to Pydantic AI’s evals package: datasets hold cases, cases reference evaluators, and evaluators score the outputs.

### Decorator tasks

```python decorator_style.py theme={null}
from mcp_eval import Expect, task

@task("Finder summarizes Example Domain")
async def test_finder_fetch(agent, session):
    response = await agent.generate_str("Fetch https://example.com and summarize it.")

    await session.assert_that(Expect.tools.was_called("fetch"))
    await session.assert_that(Expect.content.contains("Example Domain"), response=response)
    await session.assert_that(Expect.performance.max_iterations(3))
```

### Pytest suites

```python pytest_style.py theme={null}
import pytest
from mcp_eval import create_agent, Expect

@pytest.mark.asyncio
async def test_finder_fetch_pytest():
    agent = await create_agent("finder")
    response = await agent.generate_str("Fetch https://example.com")
    assert "Example Domain" in response
    await Expect.tools.was_called("fetch").evaluate(agent.session)
```

### Dataset runs

```python dataset_style.py theme={null}
from mcp_eval import Case, Dataset, Expect
from mcp_eval import create_agent

dataset = Dataset(
    cases=[
        Case(
            name="fetch_example_domain",
            inputs="Fetch https://example.com and summarize it.",
            evaluators=[Expect.tools.was_called("fetch")],
        )
    ]
)

async def run_case(prompt: str) -> str:
    agent = await create_agent("finder")
    return await agent.generate_str(prompt)

report = await dataset.evaluate(run_case)  # call from an async test or helper
```

<Note>
  Datasets, cases, and evaluators match the structure in Pydantic AI evals: cases define inputs and expectations, evaluators score results, and datasets group related cases for reuse.
</Note>

## Run and inspect

```bash  theme={null}
mcp-eval run tests/   # decorator, dataset, and CLI suites
uv run pytest -q tests
```

During a run you can pull structured telemetry:

```python  theme={null}
metrics = session.get_metrics()
span_tree = session.get_span_tree()
```

## Pick a focus area

* Work through end-to-end agent scenarios in [`Agent Evaluation`](./agent-evaluation).
* Validate server behavior and tool contracts in [`MCP Server Evaluation`](./server-evaluation).
* Refer back to [mcp-eval.ai](https://mcp-eval.ai) for extended guides, configuration options, and community examples.

## Observability, reports, and CI/CD

* OpenTelemetry traces flow to Grafana, Honeycomb, Pydantic Logfire, or any OTEL target
* JSON/Markdown/HTML reports are ready for CI artifacts or release notes
* Reusable GitHub Actions (`mcp-eval/.github/actions/mcp-eval/run`) publish test results, summaries, and badges


# MCP Server Evaluation
Source: https://docs.mcp-agent.com/test-evaluate/server-evaluation

Test MCP server compatibility and functionality

Server evaluations connect your MCP implementation to a reference agent and verify that tools behave correctly, error handling works, and performance stays within limits. Run them whether your server powers an mcp-agent workflow or an external client.

<Info>
  Treat each tool as an API contract. Evaluations catch schema drift, unexpected latencies, and regressions in derived content before they reach users.
</Info>

<Tip>
  The full server guide lives at <a href="https://mcp-eval.ai/server-evaluation">mcp-eval.ai/server-evaluation</a>, with deeper dives on datasets, assertions, and debugging techniques.
</Tip>

## Connect the server under test

Register the server exactly the way your agent launches it—stdio, SSE, Docker, or remote URL:

```bash  theme={null}
mcp-eval server add \
  --name fetch \
  --transport stdio \
  --command "uv" "run" "python" "-m" "mcp_servers.fetch"
```

When you expose a suite of servers through `MCPAggregator`, evaluate both the aggregated view and the underlying servers. That ensures namespacing and tool discovery keep working when you refactor.

## Baseline assertions

* **Correctness**: validate the content returned to the agent (`Expect.content.contains`, `Expect.tools.output_matches`)
* **Tool usage**: make sure the tool you expect is the one that fired (`Expect.tools.was_called`, `Expect.tools.sequence`)
* **Performance**: guard against regressions in latency or excessive retries (`Expect.performance.response_time_under`, `Expect.performance.max_iterations`)
* **Quality**: enlist LLM judges when outputs are qualitative (`Expect.judge.llm`, `Expect.judge.multi_criteria`)

```python fetch_server_test.py theme={null}
from mcp_eval import Expect, task

@task("Fetch server returns HTML summary")
async def test_fetch_tool(agent, session):
    response = await agent.generate_str(
        "Use the fetch tool to read https://httpbin.org/html and summarize the page."
    )

    await session.assert_that(Expect.tools.was_called("fetch"))
    await session.assert_that(
        Expect.tools.output_matches("fetch", {"isError": False}, match_type="partial")
    )
    await session.assert_that(
        Expect.content.contains("httpbin", case_sensitive=False), response=response
    )
    await session.assert_that(
        Expect.judge.llm(
            "Summary should mention the simple HTML demonstration page", min_score=0.8
        ),
        response=response,
    )
```

## Encode golden paths and limits

`Expect.path.efficiency` and `Expect.tools.sequence` let you capture the ideal execution path. This is especially useful for servers that proxy other systems (databases, file systems, SaaS APIs) where unnecessary retries are costly.

```python golden_path.py theme={null}
await session.assert_that(
    Expect.path.efficiency(
        expected_tool_sequence=["fetch"],
        allow_extra_steps=1,
        tool_usage_limits={"fetch": 1},
    )
)
```

## Inspect artifacts

* Per-test JSON plus OpenTelemetry `.jsonl` traces show detailed timings and tool payloads (`./test-reports` by default)
* HTML and Markdown summaries are ready for CI upload or PR comments
* Combine with mcp-agent tracing to correlate server-side telemetry with agent orchestration