🤗 18. 본편 10: smolagents ToolCollection으로 MCP 도구 연결 기초

이번 편은 smolagents 에이전트에 외부 도구 서버(MCP)를 붙이는 가장 기본 흐름을 다룬다.
핵심 목표는 복잡한 멀티에이전트가 아니라, “도구를 안전하게 연결하고 실제로 호출되는지 확인” 하는 것이다.

• 이전 편: 🤗 17. 본편 09
• 다음 확장: MCP 인증/권한 분리, 실패 재시도 정책, 운영 로그 표준화

한 줄 결론

에이전트 도입 초반에는 모델 튜닝보다 “도구 연결 검증(연결→호출→결과)“을 먼저 표준화하면 실무 실패가 크게 줄어든다.

flowchart LR
  U[사용자 질문] --> A[CodeAgent]
  A --> C[ToolCollection.from_mcp]
  C --> M[MCP Server]
  M --> C
  C --> A
  A --> R[최종 답변 + 사용도구 로그]

---

실습 목표

• ToolCollection.from_mcp 개념을 이해한다.
• 로컬 MCP 서버(예: filesystem)를 smolagents에 연결한다.
• 도구 호출 성공 여부를 로그로 확인한다.

준비물

• 도구: Python 3.10+, Node.js 18+, 터미널
• 입력: OpenAI 호환 API 키 1개
• 실행 환경: Linux/macOS (Windows는 WSL 권장)
• 작업 폴더 예시: ~/hf-agents-lesson18

초보자 팁: 처음에는 “읽기 전용 도구”부터 붙이자. 쓰기/삭제 권한 도구는 운영 사고 위험이 크다.

1) 프로젝트/패키지 준비

• 도구: 터미널
• 입력: 가상환경 + 패키지 설치
• 실행명령:

mkdir -p ~/hf-agents-lesson18
cd ~/hf-agents-lesson18
python3 -m venv .venv
source .venv/bin/activate
pip install -U "smolagents[toolkit,litellm,mcp]" mcp

• 성공판정:
  • (.venv) 프롬프트 표시
  • pip install 에러 없이 종료

2) MCP 서버 확인(파일시스템 예시)

• 도구: 터미널
• 입력: MCP 서버 실행 가능 여부
• 실행명령:

npx -y @modelcontextprotocol/server-filesystem --help

• 성공판정:
  • help/usage 문구 출력
  • command not found 또는 npm 권한 오류가 없음

3) 환경변수 설정

• 도구: 터미널
• 입력: 모델/API 키
• 실행명령:

export OPENAI_API_KEY="YOUR_API_KEY"
export MODEL_ID="openai/gpt-4o-mini"

• 성공판정:
  • echo $MODEL_ID 값 확인 가능
  • python -c "import os; print(bool(os.getenv('OPENAI_API_KEY')))" 결과가 True

4) MCP 연결 에이전트 코드 작성

• 도구: 에디터 또는 터미널
• 입력: 아래 코드
• 실행명령:

cat > lesson18_mcp_agent.py <<'PY'
from __future__ import annotations
 
import os
 
from smolagents import CodeAgent, LiteLLMModel, ToolCollection
 
 
def build_agent() -> CodeAgent:
    model = LiteLLMModel(model_id=os.getenv("MODEL_ID", "openai/gpt-4o-mini"))
 
    # 로컬 폴더를 읽는 filesystem MCP 서버 연결 (읽기 중심 권장)
    tools = ToolCollection.from_mcp(
        command="npx",
        args=[
            "-y",
            "@modelcontextprotocol/server-filesystem",
            ".",
        ],
    )
 
    return CodeAgent(
        tools=tools.tools,
        model=model,
        max_steps=6,
    )
 
 
def main() -> None:
    agent = build_agent()
    question = "현재 폴더에서 md 파일 목록을 찾아, 파일명만 bullet 3개 이내로 요약해줘."
    result = agent.run(question)
    print("\n=== AGENT RESULT ===")
    print(result)
 
 
if __name__ == "__main__":
    main()
PY

• 성공판정:
  • lesson18_mcp_agent.py 파일 생성
  • 코드에 ToolCollection.from_mcp(...) 포함

5) 실행 및 도구 호출 검증

• 도구: Python
• 입력: 질문 1개(코드 내 기본값)
• 실행명령:

python lesson18_mcp_agent.py

• 성공판정:
  • 에이전트 출력이 생성됨
  • 로컬 파일 관련 결과가 포함됨
  • 오류 없이 종료 코드 0

6) 실패 시 점검 루틴(초보자용)

• 도구: 터미널
• 입력: 설치/환경/실행 상태 진단
• 실행명령:

pip show smolagents mcp
node -v
npm -v
 
python - <<'PY'
import os
print("MODEL_ID:", os.getenv("MODEL_ID"))
print("OPENAI_API_KEY set:", bool(os.getenv("OPENAI_API_KEY")))
PY

• 성공판정:
  • 패키지/Node 버전/환경변수 누락 여부 즉시 확인 가능

---

실무 적용 포인트

1. MCP 연결은 표준 인터페이스로 관리
   나중에 도구를 바꿔도 에이전트 구조를 크게 바꾸지 않아도 된다.
2. 권한 최소화 원칙 먼저 적용
   초반에는 읽기 전용 도구로 시작해 운영 리스크를 줄인다.
3. 도구 호출 로그를 반드시 남기기
   실패 분석(권한, 경로, 응답 포맷)에 가장 빠른 단서가 된다.
4. 작은 성공 시나리오부터 고정
   ”파일 목록 조회”처럼 단순 작업이 안정화되면, 그다음에 쓰기/변환 자동화로 확장한다.

자주 막히는 문제

1. npx 실행 실패
   • 해결: Node/npm 버전 점검, 사내망 프록시 설정 확인
2. 에이전트가 도구를 안 쓰고 추론만 함
   • 해결: 질문에 “현재 폴더에서”처럼 도구 필요성을 명시
3. 경로 권한 이슈
   • 해결: 도구 서버 실행 루트 경로를 명확히 지정하고 읽기 가능 경로인지 확인

체크리스트

• 가상환경 + 패키지 설치 완료
• MCP 서버 help 출력 확인
• API 키/모델 설정 완료
• ToolCollection.from_mcp 코드 작성 완료
• 실행 시 도구 기반 결과 확인

참고 링크 (우선순위)

1. https://github.com/huggingface/agents-course
2. https://huggingface.co/learn/agents-course
3. https://huggingface.co/docs/smolagents

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 구조화, 실습 코드 골격 작성, 체크리스트 정리를 수행했으며, 최종 발행 전 사람이 명령/링크/재현 단계를 검토했다.