DOCSEARCHbyAlgolia
Submit Docs

mcp-agent Documentation

repository·main·Indexed 27 days ago

https://github.com/lastmile-ai/mcp-agent

A composable framework for building robust agents using the Model Context Protocol (MCP). mcp-agent simplifies MCP server lifecycle management and implements production-ready agentic patterns such as map-reduce, orchestrator, router, and swarm. It supports durable execution via Temporal, provides Augmented LLM wrappers for providers like OpenAI, and includes a CLI for project scaffolding and cloud deployment.

Tokens
150.2K
Snippets
399
Records
560
Agent score
93%

What's inside mcp-agent

  1. Overview of mcp-agent

    main
    mcp-agent is a composable framework for building effective agents using the Model Context Protocol (MCP). It provides full MCP support (Tools, Resources, Prompts, Notifications, etc.), implements effective agent patterns (like map-reduce, orchestrator, and router), and supports durable execution via Temporal for scaling to production workloads without API changes.

  2. Overview of Workflow Pattern Composition

    main
    Workflow pattern composition is an advanced technique for building complex agent systems by combining simpler, reusable, and well-tested patterns. This modular approach enables building complex workflows from components, testing individual patterns in isolation, maintaining and evolving patterns independently, and scaling different patterns based on specific workloads.

  3. Observability Overview

    main

    For production agent workflows, mcp-agent supports a comprehensive observability stack to ensure reliability and performance. This includes:

    • Metrics Collection: Tracking performance, throughput, and system health.
    • Distributed Tracing: Following requests across agents, workflows, and external services.
    • Structured Logging: Centralized, searchable logs with contextual information.
    • Alerting: Proactive notifications for issues and anomalies.

  4. Choose an agent workflow pattern

    main

    The mcp-agent SDK provides production-ready implementations of various agentic patterns via helpers in workflows/factory.py. Each helper returns an AugmentedLLM that can be composed, exposed as a tool, or wrapped with additional logic.

    PatternUse CaseFactory Helper(s)
    Parallel (Map-Reduce)Multiple specialists looking at the same request concurrentlycreate_parallel_llm(...)
    RouterDispatching requests to the best skill, server, or functioncreate_router_llm(...), create_router_embedding(...)
    Intent ClassifierLightweight intent bucketing before routing/automationcreate_intent_classifier_llm(...), create_intent_classifier_embedding(...)
    Planner (Orchestrator)Multi-step planning and coordination across agentscreate_orchestrator(...)
    Deep ResearchLong-horizon investigations with budgets and memorycreate_deep_orchestrator(...)
    Evaluator-OptimizerAutomated reviewers to approve or iterate on draftscreate_evaluator_optimizer_llm(...)
    Custom/SwarmBespoke patterns stitched from primitivescreate_swarm(...)

  5. Deploy mcp-agent applications to production

    main

    mcp-agent provides a unified programming model that scales from local development to managed cloud runtimes. You can deploy full agents with durable workflows or standalone MCP servers (FastMCP services, ChatGPT App backends, bespoke tool APIs) using the same code.

    Key benefits include:

    • One protocol everywhere: All deployments expose standard MCP endpoints (call_tool, read_resource, list_prompts).
    • Durable workflows: Decorators like @app.tool, @app.async_tool, and @app.workflow transition from local asyncio to cloud-based Temporal execution, providing retries and human-in-the-loop support.
    • Operational guardrails: The CLI manages build artifacts, secrets, authentication, and observability.

  6. Understand Secret Management Phases

    main

    Secrets management in mcp-agent cloud is divided into two distinct types:

    1. Deployment secrets: Values known at deploy time (e.g., provider API keys, service accounts). These are stored encrypted and automatically mounted into the runtime for all users.
    2. User secrets: Values that individual consumers must supply (e.g., personal access tokens, OAuth tokens). These are collected per user via mcp-agent cloud configure and are scoped to that specific user's configuration.

  7. Quickstart: Deploy and install an mcp-agent application

    main

    Follow these steps to move from local development to a deployed cloud application:

    1. Install the CLI: Use uv to install the mcp-agent tool.
    2. Authenticate: Log in to create your API key.
    3. Deploy: Bundle your code and push it to the managed cloud.
    4. Install to Client: Add the deployed MCP server to your client configuration (e.g., Claude Desktop, Cursor, VS Code).
    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

  8. Quickstart: Scaffold and run a new project

    main

    You can quickly set up a new project using the mcp-agent CLI via uvx.

    1. Scaffold a project:
    uvx mcp-agent init
    1. Initialize a python environment:
    uv init
    1. Add dependencies:
    uv add "mcp-agent[openai]"
    1. Configure secrets: Add your OPENAI_API_KEY to mcp_agent.secrets.yaml or set it as an environment variable.
    2. Run the application:
    uv run main.py
    mkdir hello-mcp-agent && cd hello-mcp-agent
uvx mcp-agent init
uv init
uv add "mcp-agent[openai]"
uv run main.py

  10. Install MCP Agent Cloud SDK for development

    main

    To set up the SDK in a development environment, use uv to create a virtual environment and install the package in editable mode with development dependencies.

    # Navigate to the package root
# Create and activate a virtual environment
uv venv .venv
source .venv/bin/activate

# Install in editable mode with dev dependencies
uv pip install -e ".[dev]"

  11. Choose a deployment path for mcp-agent

    main

    Select a deployment strategy based on your requirements:

    Use caseRecommended pathDescription
    Prototype & debugginguv run main.py or mcp-agent dev startLocal development with hot reload and local logs.
    Durable agentsmcp-agent deploy (managed)Uses the managed cloud environment with Temporal-backed workflows, cloud logging, secrets, and auth.
    Regulated / on-premSelf-hosted Temporal + mcp_agent.config.yaml overridesUse your own Temporal cluster for air-gapped or regulated environments.
    Reusable MCP toolsFastMCP or @app.tool via cloudDeploy stateless tools via standard MCP transport, installable via CLI.

  12. Run mcp-agent CLI commands

    main

    You can run mcp-agent commands ad hoc without installation using uvx mcp-agent .... If the package is already a dependency in your project, use uv run mcp-agent ... to execute within your project's environment.

    All commands support these global flags:

    • --verbose/-v
    • --quiet/-q
    • --format <text|json|yaml>
    • --color / --no-color
    • --version