DeepMCPAgent 소개
DeepMCPAgent는 LangChain 또는 LangGraph 기반의 에이전트를 쉽게 만들 수 있도록 돕는 Python 패키지입니다. 이 프로젝트의 가장 큰 특징은 **Model Context Protocol(MCP)**을 활용해 도구(tool)를 직접 하드코딩하지 않고 자동으로 탐색하고 연결한다는 점입니다. 즉, 개발자가 별도의 수동 설정 없이도 HTTP 또는 SSE 기반 MCP 서버에서 도구를 실시간으로 불러와 사용할 수 있습니다. 이를 통해 복잡한 API 연동이나 새로운 기능 확장이 훨씬 단순해집니다.
특히 DeepMCPAgent는 특정 LLM 제공자에 종속되지 않고, OpenAI, Anthropic, Ollama, Groq, 또는 로컬 모델 등 **모델에 구애받지 않는 구조(model-agnostic)**를 제공합니다. 사용자는 LangChain이 지원하는 어떤 채팅 모델이든 연결할 수 있으며, 모델을 문자열(provider-id)로 지정하거나 직접 인스턴스를 넘겨 유연하게 활용할 수 있습니다.
또한 DeepMCPAgent는 선택적으로 DeepAgents를 설치해 고급 에이전트 루프를 활용할 수 있으며, 그렇지 않은 경우에도 안정적인 LangGraph ReAct 기반 실행이 가능합니다. 도구 호출은 JSON-Schema → Pydantic → LangChain BaseTool로 변환되어 타입 안정성과 검증된 입력 구조를 보장합니다. 이런 아키텍처 덕분에 개발자는 복잡한 도구 호출 과정을 신경 쓰지 않고도 곧바로 프로덕션 수준의 에이전트를 만들 수 있습니다.
일반적인 LangChain 기반 프로젝트에서는 도구(tool)를 직접 정의하고 연결해야 합니다. 예를 들어 OpenAI API를 호출하거나, DB 쿼리 도구를 붙이려면 수동으로 작성해야 하죠. 그러나 DeepMCPAgent는 MCP 프로토콜을 통해 도구를 동적으로 불러오기 때문에, 별도의 하드코딩 과정이 필요 없습니다. 이는 복잡한 시스템이나 다수의 외부 API를 연결해야 하는 상황에서 큰 장점으로 작용합니다.
또한 LangGraph 기반의 ReAct 에이전트와도 차이가 있습니다. ReAct는 LLM과 툴 간의 상호작용을 잘 구조화했지만, 기본적으로 툴의 정의와 연결은 수동으로 해야 합니다. 반면 DeepMCPAgent는 MCP 서버와 FastMCP 클라이언트를 통해 이를 자동화하므로, 유지보수와 확장이 훨씬 수월합니다. 결과적으로, 기존 LangChain/LangGraph의 장점을 그대로 가져오면서도 “도구 자동 연결”이라는 새로운 기능을 제공합니다.
즉, DeepMCPAgent는 LangChain의 유연함 + LangGraph의 구조적 에이전트 설계 + MCP의 자동화된 도구 탐색 을 결합한 프로젝트라고 할 수 있습니다.
DeepMCPAgent의 주요 기능
-
동적 도구 탐색: DeepMCPAgent는 MCP 서버(FastMCP 기반 HTTP/SSE 서버)와 연결해 list_tools 요청을 보내고, 반환된 JSON-Schema 정보를 Pydantic 모델로 변환한 뒤 LangChain BaseTool로 구성합니다. 이를 통해 도구 호출 시 입력값이 자동 검증되며, 오류 가능성을 줄여줍니다.
-
모델 독립적 구조: 모델은 OpenAI gpt-4.1, Anthropic claude-3.5, Ollama의 llama3.1 등 원하는 것을 자유롭게 지정할 수 있습니다. 문자열로 지정하면 LangChain의 init_chat_model()을 통해 API 키를 읽고 모델을 초기화하며, 직접 인스턴스를 전달하면 더 세밀한 제어가 가능합니다.
-
CLI와 Python API 지원: 개발자가 Python 코드를 직접 작성하지 않아도 CLI만으로 MCP 서버와 연결하고 도구 목록을 확인하거나 대화형 에이전트를 실행할 수 있습니다. 예를 들어, 아래와 같은 단순한 명령어만으로 MCP 서버에서 제공하는 기능을 즉시 확인할 수 있습니다.:
deepmcpagent list-tools \ --http name=math url=http://127.0.0.1:8000/mcp transport=http \ --model-id "openai:gpt-4.1"
DeepMCPAgent의 아키텍처 개요
┌────────────────┐ list_tools / call_tool ┌─────────────────────────┐
│ LangChain/LLM │ ──────────────────────────────────▶ │ FastMCP Client (HTTP/SSE)│
│ (your model) │ └───────────┬──────────────┘
└──────┬─────────┘ tools (LC BaseTool) │
│ │
▼ ▼
LangGraph Agent One or many MCP servers (remote APIs)
(or DeepAgents) e.g., math, github, search, ...
DeepMCPAgent는 크게 세 가지 계층으로 나눌 수 있습니다:
- 에이전트 계층: LangChain 모델과 LangGraph 기반의 에이전트 루프(DeepAgents 또는 ReAct)를 실행합니다.
- 도구 로딩 계층: MCPToolLoader가 MCP 서버로부터 도구 정보를 받아 BaseTool로 변환합니다.
- FastMCP 클라이언트 계층: 실제 HTTP/SSE 통신을 담당하며, 여러 MCP 서버와 동시에 연결할 수 있습니다.
이 구조 덕분에 에이전트는 새로운 MCP 서버를 붙이는 것만으로 곧바로 다양한 API를 활용할 수 있습니다.
DeepMCPAgent 설치 및 사용법
pip 명령어를 사용하여 PyPI로부터 설치할 수 있습니다:
pip install "deepmcpagent[deep]"
deep 옵션은 DeepAgents를 포함해 더 정교한 에이전트 루프를 사용할 수 있게 합니다. 추가로 dev, docs, examples 같은 extras도 지원합니다.
빠른 테스트를 원한다면 examples/servers/math_server.py를 실행해 로컬 MCP 서버를 띄우고, examples/use_agent.py로 에이전트를 실행하면 됩니다. 이 과정에서 모델은 사용자가 원하는 LangChain 모델로 지정할 수 있습니다.
DeepMCPAgent의 개발 및 보안
DeepMCPAgent는 엄격한 정적 분석과 테스트 환경을 갖추고 있습니다. mypy, ruff, pytest 등이 포함되어 있으며, GitHub Actions를 통해 CI/CD도 지원합니다.
보안 측면에서는 사용자의 API 키나 인증 토큰을 직접 관리하지 않으며, HTTP 헤더 설정을 통해 MCP 서버에 안전하게 전달할 수 있습니다.
라이선스
DeepMCPAgent 프로젝트는 Apache-2.0 라이선스로 공개되어 있으며, 상업적 사용에 제약이 없습니다.
DeepMCPAgent 프로젝트 GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 