fast-agent (MCP server) — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

에이전트 형태를 위한 @fast.agent() / @fast.chain() / @fast.parallel() 데코레이터
MCP, Skills, ACP 1등급 지원
멀티 모델 (Anthropic, OpenAI, Bedrock, 로컬)
내장 eval 러너 + 추적 시각화 도구
에이전트를 도구로 노출하는 MCP 서버로 자체 실행 가능

라이브 데모

실제 사용 모습

fast-agent-mcp.replay ▶ 준비됨

0/0

설치

클라이언트 선택

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

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

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

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

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

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

VS Code → Cline → MCP Servers → Edit

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

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

~/.codeium/windsurf/mcp_config.json

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

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

~/.continue/config.json

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

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

~/.config/zed/settings.json

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

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

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

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

사용 사례

실전 활용법: fast-agent

Python 30줄로 심층 조사 에이전트 구축

👤 재현 가능한 조사 에이전트를 원하는 개발자 ⏱ ~60 min intermediate

언제 쓸까: 채팅에서 'X 조사'를 프로토타입했고 호출 가능한 에이전트로 만들고 싶을 때.

사전 조건

Python 3.11+ and uv — uv가 없으면 설치; fast-agent는 uv를 사용함
fast-agent 설치 — uvx fast-agent-mcp init; 프로젝트 디렉토리로 이동

흐름

스캐폴드

Use fast-agent. Generate a research agent skeleton with tavily search + fetch + summarize tools.✓ 복사됨

→ @fast.agent 데코레이터가 있는 agent.py
MCP 연결

Attach the tavily-mcp and filesystem MCP servers in fastagent.config.yaml.✓ 복사됨

→ 설정 검증됨; 서버 연결됨
실행 + 반복

Run with: research 'state of small embedding models 2026'. Inspect the trace.✓ 복사됨

→ 검색 → 페치 → 요약 체인을 보여주는 추적; 출처가 있는 브리핑 출력
eval 추가

Author a 5-prompt eval; run nightly. Fail if any source citation is missing.✓ 복사됨

→ eval 출력 녹색/빨간색; 야간 cron 설정됨

결과: 팀원에게 넘길 수 있는 재현 가능한 조사 파이프라인.

함정

데코레이터 마법으로 에이전트가 무엇을 하는지 불분명 — 항상 추적 읽기; 에이전트가 작동한다고 선언하기 전에 각 도구 호출 이해

함께 쓰기: tavily-mcp · filesystem

fast-agent를 MCP 서버로 노출

👤 팀 간에 에이전트를 공유하는 개발자 ⏱ ~25 min intermediate

언제 쓸까: fast-agent로 내부 에이전트를 구축했고 다른 사람들이 Claude에서 호출하기를 원할 때.

흐름

에이전트를 노출 대상으로 표시

Add @fast.agent(expose=True) to the decorator; specify name and description for tool discovery.✓ 복사됨

→ 에이전트가 MCP 도구로도 표시됨
MCP 서버로 실행

Run: fast-agent serve --transport stdio.✓ 복사됨

→ 에이전트가 도구로 나열된 stdio MCP 서버 실행 중
클라이언트에 추가

Add the fast-agent stdio config to my Claude Desktop config.✓ 복사됨

→ Claude에서 도구 표시; 호출하면 에이전트 실행됨

결과: 다른 MCP처럼 팀 전체에서 재사용 가능한 커스텀 에이전트.

함정

에이전트가 작성자만 가진 로컬 파일에 의존 — 설정 + 에셋을 에이전트 패키지에 포함; 필요한 환경 변수 문서화

eval 러너로 두 가지 prompt 버전 비교

👤 프로덕션용 prompt를 조정하는 모든 분 ⏱ ~45 min intermediate

언제 쓸까: 두 가지 prompt 표현을 놓고 데이터로 선택하고 싶을 때.

흐름

eval 작성

Define an eval with 12 representative inputs and golden outputs.✓ 복사됨

→ evals/<name>.yaml
두 번 실행

Run eval against prompt v1, then v2. Compare pass rates + token usage.✓ 복사됨

→ 델타가 있는 비교 표
선택 + 고정

Save the winning prompt to prompts/winning.md; tag the eval as the regression baseline.✓ 복사됨

→ 고정된 기준선; 향후 PR이 이것을 기준으로 실행됨

결과: 데이터 기반 prompt 선택 + 회귀 안전망.

함정

12개 입력이 모두 정상 경로 — 적대적 케이스 추가 — 빈 입력, 잘못된 형식 입력, 모순된 사실

조합

다른 MCP와 조합해 10배 효율

fast-agent-mcp + tavily-mcp + filesystem

웹 + 파일시스템 MCP가 연결된 조사 에이전트 작성

Build a research agent that uses tavily for search, filesystem for note persistence.✓ 복사됨

fast-agent-mcp + mcpjam-inspector

배포 전 MCPJam UI로 fast-agent 서버 검사

Run fast-agent as MCP server; connect via mcpjam-inspector to verify tool schemas.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
agent.run	messages, agent_name?	에이전트를 처음부터 끝까지 구동	Model + tool calls
agent.list	—	노출된 에이전트 탐색	0
eval.run	eval_name, prompt_version?	커밋 전 / 야간 회귀 검사	Model API per prompt
trace.get	run_id	특정 실행 디버그	0

비용 및 제한

운영 비용

API 쿼터: 선택한 모델 제공자의 할당량
호출당 토큰: 에이전트 설계에 따라 매우 가변적
금액: 프레임워크 무료; 모델 제공자에게 비용 지불
팁: 개발 시 --model haiku-4.5 사용; 프로덕션 실행과 eval에만 sonnet으로 전환

보안

권한, 시크릿, 파급범위

최소 스코프: Whatever attached MCPs need

자격 증명 저장: fastagent.secrets.yaml (gitignored) 또는 환경 변수

데이터 외부 송신: 연결된 MCP 서버와 선택한 모델 제공자로

절대 부여 금지: 개발 환경에 프로덕션 쓰기 token

데코레이터가 로컬 컨텍스트를 캡처할 수 있음 — 에이전트 상태에 비밀 키가 실수로 직렬화되지 않도록 주의

문제 해결

자주 발생하는 오류와 해결

에이전트가 수렴하지 않고 루프

max_steps 설정; 추적에서 루프 찾기. 보통 도구가 모호한 출력을 반환하고 모델이 계속 재시도

확인: trace.get(run_id)

Eval이 0%를 보고하지만 수동 실행은 작동

golden_output 형식 확인 — 엄격한 동등성 vs 시맨틱 매칭

설정의 MCP 서버 연결 실패

먼저 서버 명령을 독립 실행; fastagent.secrets.yaml에 환경 변수가 있는지 확인

첫 실행이 느림

uv가 첫 호출 시 의존성을 가져옴; 이후에는 캐시됨. CI에서 사전 워밍

대안

fast-agent 다른 것과 비교

대안	언제 쓰나	단점/장점
PrefectHQ/fastmcp	완전한 에이전트 프레임워크가 아닌 표준 MCP 서버 프레임워크를 원할 때	fastmcp은 서버 구축용; fast-agent는 에이전트 구축 (및 오케스트레이션)용
LangGraph	팀이 이미 LangChain 생태계에 투자했을 때	더 일반적; MCP 네이티브 낮음
mcp-agent (lastmile-ai)	더 미니멀한 튜토리얼 수준의 프레임워크를 선호할 때	범위가 작음; 배터리 포함 기능 적음

fast-agent