mcp-agent MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

Pattern library: Orchestrator, Router, Evaluator, Swarm, Parallel, Deep Research
Durable workflows via Temporal (same code, just change executor)
MCPApp lifecycle manages server connections cleanly
Decorators: @app.workflow, @app.tool, @app.workflow_task

라이브 데모

실제 사용 모습

mcp-agent.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-agent": {
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-agent",
      "command": "uvx",
      "args": [
        "mcp-agent"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-agent": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-agent"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add mcp-agent -- uvx mcp-agent

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: mcp-agent

Build an orchestrator-workers agent for research tasks

👤 Python devs building multi-step agents ⏱ ~60 min advanced

언제 쓸까: The task is too big for one LLM pass but decomposes into parallel subtasks (e.g., research 10 competitors).

사전 조건

Python 3.10+ — standard
MCP servers you want the agent to use — List them in the mcp-agent config

흐름

Define worker agents

Create 2 Agents — scraper with the firecrawl server, writer with filesystem. Give each a focused instruction set.✓ 복사됨

→ Two Agent instances
Wire the orchestrator

Wrap them with create_orchestrator(planner_llm=..., workers=[scraper, writer]). Max iterations = 10.✓ 복사됨

→ Orchestrator returns plan + execution handle
Run a real task

Run: 'Research the 5 top-rated Postgres MCPs on GitHub. For each, write a 1-page summary to ./reports/<slug>.md.'✓ 복사됨

→ 5 files generated with coherent content

결과: A parallelized agent that completes what would be 30 min of manual multi-step work in 3-5 min.

함정

Orchestrator creates too many or too few subtasks — Give the planner LLM explicit guidance: 'break into 3-7 subtasks, each <5 minutes of work'
Workers re-fetch the same data — Share a cache via the app state or pass results explicitly through the plan

함께 쓰기: mcp-use · fastmcp

Build an evaluator-optimizer agent for high-quality writing

👤 Teams shipping content pipelines ⏱ ~45 min advanced

언제 쓸까: First-draft LLM output is too sloppy for production. You need an automatic 'keep iterating until it passes' loop.

흐름

Define the writer and evaluator

Writer: produces a draft given a brief. Evaluator: scores on [accuracy, clarity, tone] 1-5, with rationale.✓ 복사됨

→ Two agents defined
Set the loop

Use EvaluatorOptimizer with min_rating=4 across all criteria, max_iterations=5. Pass brief as input.✓ 복사됨

→ Loop runs, iterations visible in logs
Observe convergence

For 10 diverse briefs, log: initial score, final score, iterations needed. Are there briefs that never converge?✓ 복사됨

→ Stats with outliers identified

결과: Consistent-quality output without human review in the loop.

함정

Evaluator is lenient, loop exits on iter 1 with mediocre output — Calibrate the evaluator — give it 3 example inputs with expected scores in the system prompt
Budget blows up when max_iterations is high — Cap at 3-4; if it doesn't converge by then, the brief is the problem, not the model

Make an agent workflow durable with Temporal

👤 Platform engineers running agents in production ⏱ ~90 min advanced

언제 쓸까: Your agent flow is long-running (minutes to hours), can't afford to restart from zero if a node dies.

사전 조건

Running Temporal cluster — temporal server start-dev for local, Temporal Cloud or self-hosted for prod

흐름

Annotate workflows

Decorate my existing orchestrator function with @app.workflow and individual steps with @app.workflow_task.✓ 복사됨

→ Workflow registered with Temporal
Switch the executor

Change the app config executor: 'temporal'. Register the worker. Start a workflow.✓ 복사됨

→ Temporal UI shows the running workflow
Verify crash recovery

Kill the Python worker mid-workflow. Restart it. Confirm the workflow resumes from the last completed activity.✓ 복사됨

→ No duplicate work, no lost state

결과: Agent workflows survive process restarts, deploys, and OOMs — critical for hour-long research tasks.

함정

Activities aren't idempotent and resume causes double-writes — Every activity must be safe to retry — use idempotency keys on external writes

조합

다른 MCP와 조합해 10배 효율

mcp-agent + mcp-use

mcp-use for client plumbing + mcp-agent for workflow patterns

Use mcp-use to connect filesystem + git. Wrap with mcp-agent's Orchestrator to plan a multi-repo refactor.✓ 복사됨

mcp-agent + fastmcp

Build custom MCPs with FastMCP that your mcp-agent workflows consume

Expose our internal ranking API via FastMCP, then use it in an mcp-agent Router that classifies customer questions.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
MCPApp	config_path or config object	Top-level — one per process	free
Agent(name, instruction, server_names)	configured with which MCP servers it can use	Define each worker/role	free
AugmentedLLM.generate / generate_str / generate_structured	messages, optional schema	Direct LLM call with MCP tools wired	LLM tokens
create_parallel_llm / create_router_llm / create_orchestrator	agents + planner LLM	Instantiate one of the built-in patterns	LLM tokens × pattern fan-out
@app.workflow / @app.workflow_task	decorator on async function	When using Temporal executor	free
EvaluatorOptimizer	writer_agent, evaluator_agent, min_rating, max_iterations	Quality-critical outputs	expensive — cap max_iterations

비용 및 제한

운영 비용

API 쿼터: None from mcp-agent; LLM + MCP costs passthrough
호출당 토큰: Patterns amplify — a Parallel with 5 workers is 5× the tokens of a single LLM call
금액: Free library; LLM + optional Temporal infra are real costs
팁: Patterns like Orchestrator fan out — put an explicit token budget check in the planner LLM's system prompt

보안

권한, 시크릿, 파급범위

자격 증명 저장: env vars for LLM keys + per-MCP secrets

데이터 외부 송신: LLM provider + each configured MCP server + Temporal (if enabled)

문제 해결

자주 발생하는 오류와 해결

Workflow hangs at start with no logs

MCP server failed to spawn. Enable debug logging: logger: {level: 'DEBUG'} in config. Usually a bad command/env in the server entry.

Orchestrator returns plan but no execution

You called .plan() instead of .generate(). Use the full method to execute the plan.

Temporal workflow fails with serialization error

Your activity returns a non-serializable object (e.g., an MCP client handle). Activities must return JSON-serializable values.

LLM ignores available tools and hallucinates

The system prompt is likely truncated or missing tool list. Upgrade to a tool-use-strong model (Sonnet, GPT-4o) and verify tools in list_tools before running.

대안

mcp-agent 다른 것과 비교

대안	언제 쓰나	단점/장점
mcp-use	You want lighter client plumbing without the pattern library	Write orchestration code yourself
LangGraph	You want stateful graphs with time-travel debugging	More LangChain-centric; MCP is bolted on
CrewAI	You want opinionated role-based agent crews	Different mental model; MCP support is secondary

mcp-agent

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

설치

클라이언트 선택

사용 사례

실전 활용법: mcp-agent

Build an orchestrator-workers agent for research tasks

사전 조건

흐름

함정

Build an evaluator-optimizer agent for high-quality writing

흐름

함정

Make an agent workflow durable with Temporal

사전 조건

흐름

함정

조합

다른 MCP와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

mcp-agent 다른 것과 비교

더 보기

리소스