MCP智能体框架

The [Getting Started guide](https://docs.mcp-agent.com/get-started/overview) walks through configuration and secrets in detail.

```

Documentation & build with LLMs

mcp-agent's complete documentation is available at docs.mcp-agent.com, including full SDK guides, CLI reference, and advanced patterns. This readme gives a high-level overview to get you started.

• llms-full.txt: contains entire documentation.
• llms.txt: sitemap listing key pages in the docs.
• docs MCP server

Installation

We recommend using uv to manage your Python projects (uv init).

uv add "mcp-agent"

Alternatively:

pip install mcp-agent

Also add optional packages for LLM providers (e.g. uv add "mcp-agent[openai, anthropic, google, azure, bedrock]").

Cloud deployment

Deploy to mcp-agent Cloud for managed Temporal execution, secrets, and HTTPS MCP endpoints.

uvx mcp-agent login
uvx mcp-agent deploy my-agent
uvx mcp-agent cloud apps list

Docs: Cloud overview • Deployment quickstart • Examples: examples/cloud.

How do I deploy to Cloud?

Run uvx mcp-agent deploy <app-name> after logging in with uvx mcp-agent login. The CLI packages your project, provisions secrets, and exposes an MCP endpoint backed by a durable Temporal runtime. See the Cloud quickstart for step-by-step screenshots and CLI output.

Quickstart

[!TIP] The examples directory has several example applications to get started with. To run an example, clone this repo (or generate one with uvx mcp-agent init --template basic --dir my-first-agent)

> cd examples/basic/mcp_basic_agent # Or any other example
> # Option A: secrets YAML
> # cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml && edit mcp_agent.secrets.yaml
> uv run main.py
> 

Here is a basic "finder" agent that uses the fetch and filesystem servers to look up a file, read a blog and write a tweet. Example link:

<details open> <summary>finder_agent.py</summary>

import asyncio
import os

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

async def example_usage():
    async with app.run() as mcp_agent_app:
        logger = mcp_agent_app.logger
        # This agent can read the filesystem or fetch URLs
        finder_agent = Agent(
            name="finder",
            instruction="""You can read local files or fetch URLs.
                Return the requested information when asked.""",
            server_names=["fetch", "filesystem"], # MCP servers this Agent can use
        )

        async with finder_agent:
            # Automatically initializes the MCP servers and adds their tools for LLM use
            tools = await finder_agent.list_tools()
            logger.info(f"Tools available:", data=tools)

            # Attach an OpenAI LLM to the agent (defaults to GPT-4o)
            llm = await finder_agent.attach_llm(OpenAIAugmentedLLM)

            # This will perform a file lookup and read using the filesystem server
            result = await llm.generate_str(
                message="Show me what's in README.md verbatim"
            )
            logger.info(f"README.md contents: {result}")

            # Uses the fetch server to fetch the content from URL
            result = await llm.generate_str(
                message="Print the first two paragraphs from https://www.anthropic.com/research/building-effective-agents"
            )
            logger.info(f"Blog intro: {result}")

            # Multi-turn interactions by default
            result = await llm.generate_str("Summarize that in a 128-char tweet")
            logger.info(f"Tweet: {result}")

if __name__ == "__main__":
    asyncio.run(example_usage())

</details>

<details> <summary>mcp_agent.config.yaml</summary>

execution_engine: asyncio
logger:
  transports: [console] # You can use [file, console] for both
  level: debug
  path: "logs/mcp-agent.jsonl" # Used for file transport
  # For dynamic log filenames:
  # path_settings:
  #   path_pattern: "logs/mcp-agent-{unique_id}.jsonl"
  #   unique_id: "timestamp"  # Or "session_id"
  #   timestamp_format: "%Y%m%d_%H%M%S"

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

openai:
  # Secrets (API keys, etc.) are stored in an mcp_agent.secrets.yaml file which can be gitignored
  default_model: gpt-4o

</details>

<details> <summary>Agent output</summary> <img width="2398" alt="Image" src="https://github.com/user-attachments/assets/eaa60fdf-bcc6-460b-926e-6fa8534e9089" /> </details>

Examples

Browse gallery.md for runnable examples, demo videos, and community projects grouped by concept. Every entry cites the docs page and command you need to run it locally.

Add your LLM API key to `mcp_agent.secrets.yaml` or set it in env.

Configuration & secrets

Settings load from mcp_agent.config.yaml, mcp_agent.secrets.yaml, environment variables, and optional preload strings. Keep secrets out of source control.

```yaml

mcp_agent.config.yaml

execution_engine: asyncio mcp: servers: fetch: command: "uvx" args: ["mcp-server-fetch"] filesystem: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem"] openai: default_model: gpt-4o-mini

mcp_agent.config.yaml excerpt

oauth: providers: github: client_id: "${GITHUB_CLIENT_ID}" client_secret: "${GITHUB_CLIENT_SECRET}" scopes: ["repo", "user"] ```

Docs: Advanced authentication • Server authentication • Examples: examples/basic/oauth_basic_agent.

mcp_agent.config.yaml

logger: transports: [console] level: info otel: enabled: true exporters: - console

`TokenCounter` tracks token usage for agents, workflows, and LLM nodes. Attach watchers to stream updates or trigger alerts.

App configuration

Build Settings objects programmatically when you need dynamic config (tests, multi-tenant hosts) instead of YAML files.

from mcp_agent.config import Settings, MCPSettings, MCPServerSettings

settings = Settings(
    execution_engine="asyncio",
    mcp=MCPSettings(
        servers={
            "fetch": MCPServerSettings(command="uvx", args=["mcp-server-fetch"]),
        }
    ),
)
app = MCPApp(name="configured_app", settings=settings)

Docs: Configuring your application.

CLI reference

uvx mcp-agent scaffolds projects, manages secrets, inspects workflows, and deploys to Cloud.

uvx mcp-agent init --template basic             # Scaffold a new project
uvx mcp-agent deploy my-agent                   # Deploy to mcp-agent Cloud

Docs: CLI reference • Getting started guides.

Where is the API reference?

Every class, decorator, and CLI command is documented on docs.mcp-agent.com. The API reference and the llms-full.txt are designed so LLMs (or you) can ingest the whole surface area easily.

Core Components

Every project revolves around a single MCPApp runtime that loads configuration, registers agents and MCP servers, and exposes tools/workflows. The Core Components guide walks through these building blocks.

Workflows & decorators

MCPApp decorators convert coroutines into durable workflows and tools. The same annotations work for both asyncio and Temporal execution.

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 draft(self, topic: str) -> str:
        return f"- intro to {topic}\n- highlights\n- next steps"

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

Docs: Decorator reference • Examples: examples/workflows.

MCP integration

Connect to existing MCP servers programmatically or aggregate several into one façade.

from mcp_agent.mcp.gen_client import gen_client

async with app.run():
    async with gen_client("filesystem", app.server_registry, context=app.context) as client:
        resources = await client.list_resources()
        app.logger.info("Filesystem resources", data={"uris": [r.uri for r in resources.resources]})

Docs: MCP integration overview • Examples: examples/mcp.

Workflow patterns

Key agent patterns are implemented as an AugmentedLLM. Use factory helpers to wire them up or inspect the runnable projects listed in gallery.md.

Composing workflows

Mix and match AgentSpecs to build higher-level workflows using the factory helpers—routers, parallel pipelines, orchestrators, and more.

```python from mcp_agent.workflows.factory import create_router_llm

FAQs