입문자를 위한 체계적인 Model Context Protocol 학습 가이드

이 튜토리얼은 Model Context Protocol(MCP) 을 처음 접하는 개발자들을 위한 실습 중심 학습 자료입니다. LangGraph와 MCP를 통합하여 다양한 외부 도구와 서비스를 활용하는 강력한 AI 에이전트를 구축하는 방법을 단계별로 학습합니다.

• MCP의 핵심 개념과 아키텍처 이해
• FastMCP를 활용한 MCP 서버 개발
• LangGraph와 MCP의 효과적인 통합
• 다중 MCP 서버 관리 및 오케스트레이션
• 실전 RAG 시스템 구현

• 표준화된 프로토콜: MCP 표준을 따르는 도구 인터페이스 구현
• 다양한 전송 방식: stdio 및 Streamable HTTP 지원
• 동적 도구 검색: 런타임 도구 자동 검색 및 로드
• 확장 가능한 아키텍처: 여러 MCP 서버 동시 연결 지원
• 실습 중심 학습: Jupyter Notebook을 통한 인터랙티브 학습

mcp-tutorial/
├── 01-LangGraph-MCP-Tutorial.ipynb  # 메인 튜토리얼 노트북
├── server/                           # MCP 서버 구현체
│   ├── mcp_server_local.py         # 로컬 날씨 서비스 (stdio)
│   ├── mcp_server_remote.py        # 원격 시간 서비스 (HTTP)
│   ├── mcp_server_rag.py           # RAG 서비스 (벡터 검색)
│   └── rag/                        # RAG 관련 유틸리티
│       ├── base.py
│       ├── pdf.py
│       └── utils.py
├── assets/                          # 이미지 및 리소스
├── pyproject.toml                   # 프로젝트 설정
└── .env.example                     # 환경 변수 예시

• Python 3.11 이상
• UV 패키지 매니저 (설치 가이드)

1. 저장소 클론

git clone https://github.com/teddynote-lab/mcp-tutorial.git
cd mcp-tutorial

2. 환경 변수 설정

cp .env.example .env
# .env 파일을 열어 필요한 API 키 입력

3. 의존성 설치

# UV를 사용한 가상환경 생성 및 패키지 설치
uv sync

# 가상환경 활성화
source .venv/bin/activate  # macOS/Linux
# 또는
.venv\Scripts\activate  # Windows

• MCP 프로토콜 이해
• 기본 아키텍처 학습

• FastMCP를 활용한 서버 구현
• stdio 전송 방식 이해

• 다중 서버 관리 방법
• 도구 동적 로드

• LangGraph React Agent 구성
• MCP 도구 바인딩

• 커스텀 워크플로우 구축
• 세밀한 제어 구현

• Smithery AI 플랫폼 연동
• 서드파티 도구 통합

• Dify 플랫폼 활용
• 실전 통합 예제

# 로컬 날씨 서버 (stdio)
uv run python server/mcp_server_local.py

# 원격 시간 서버 (HTTP, 포트 8002)
uv run python server/mcp_server_remote.py

# RAG 서버 (문서 검색)
uv run python server/mcp_server_rag.py

# 브라우저에서 MCP 서버 테스트
npx @modelcontextprotocol/inspector

# Jupyter Notebook 실행
jupyter notebook 01-LangGraph-MCP-Tutorial.ipynb

.env 파일에 다음 환경 변수 설정이 필요합니다:

# 필수
OPENAI_API_KEY=your_openai_api_key
TAVILY_API_KEY=your_tavily_api_key

# 선택 (추가 기능)
LANGCHAIN_API_KEY=your_langchain_api_key
CONTEXT7_API_KEY=your_context7_api_key

• LangGraph: AI 에이전트 워크플로우 구축
• FastMCP: MCP 서버 개발 프레임워크
• langchain-mcp-adapters: LangChain-MCP 통합
• FAISS: 벡터 스토리지 (RAG용)
• PyMuPDF: PDF 문서 처리

이 프로젝트는 교육 목적으로 제작되었습니다. 개선 사항이나 버그를 발견하시면 Issue를 등록해 주세요.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

• MCP 공식 문서
• LangGraph 문서
• FastMCP GitHub
• Smithery AI

• 테디노트 YouTube 채널
• RAG 심화 온라인 강의

이 프로젝트는 교육 목적으로만 사용 가능합니다. 자세한 내용은 LICENSE 파일을 참조하세요.

Made by TeddyNote LAB

MCP와 LangGraph로 차세대 AI 에이전트를 구축하세요! 🚀