🤖 MCP (Model Context Protocol) Tutorial
입문자를 위한 체계적인 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 패키지 매니저 (설치 가이드)
설치 단계
- 저장소 클론
git clone https://github.com/teddynote-lab/mcp-tutorial.git
cd mcp-tutorial
- 환경 변수 설정
cp .env.example .env
# .env 파일을 열어 필요한 API 키 입력
- 의존성 설치
# UV를 사용한 가상환경 생성 및 패키지 설치
uv sync
# 가상환경 활성화
source .venv/bin/activate # macOS/Linux
# 또는
.venv\Scripts\activate # Windows
🎓 학습 경로
Part 1: MCP 기본 개념
- MCP 프로토콜 이해
- 기본 아키텍처 학습
Part 2: 기본 MCP 서버 생성
- FastMCP를 활용한 서버 구현
- stdio 전송 방식 이해
Part 3: MultiServerMCPClient 설정
- 다중 서버 관리 방법
- 도구 동적 로드
Part 4: React Agent와 MCP 통합
- LangGraph React Agent 구성
- MCP 도구 바인딩
Part 5: ToolNode와 MCP 통합
- 커스텀 워크플로우 구축
- 세밀한 제어 구현
Part 6: 외부 MCP 서버 활용
- Smithery AI 플랫폼 연동
- 서드파티 도구 통합
Part 7: Dify MCP 서버 연동
- Dify 플랫폼 활용
- 실전 통합 예제
💻 실행 방법
MCP 서버 실행
# 로컬 날씨 서버 (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 Inspector로 테스트
# 브라우저에서 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를 등록해 주세요.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
📖 참고 자료
🎥 학습 리소스
📄 라이선스
이 프로젝트는 교육 목적으로만 사용 가능합니다. 자세한 내용은 LICENSE 파일을 참조하세요.
✨ 제작
Made by TeddyNote LAB
MCP와 LangGraph로 차세대 AI 에이전트를 구축하세요! 🚀
Metadata
Release files for iflow-mcp_teddynote-lab-mcp-tutorial 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_teddynote_lab_mcp_tutorial-0.1.1.tar.gz | 7.2 kB | Without provenance | Details for iflow_mcp_teddynote_lab_mcp_tutorial-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_teddynote_lab_mcp_tutorial-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_teddynote_lab_mcp_tutorial-0.1.1-py3-none-any.whl |
Total release size: 15.9 kB
Release files / iflow_mcp_teddynote_lab_mcp_tutorial-0.1.1.tar.gz
| Download URL | iflow_mcp_teddynote_lab_mcp_tutorial-0.1.1.tar.gz |
|---|---|
| Size | 7.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
99cc8605bf80005beab4273154a7c4e86681d3f54cb7517cb5bcf36e01f3914a
|
|
BLAKE2b-256 checksum How to use checksums |
5bd19ef979198f1aa84fc8fb85185d3fd1905e2f3688324f9ce7426050297137
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_teddynote_lab_mcp_tutorial-0.1.1-py3-none-any.whl
| Download URL | iflow_mcp_teddynote_lab_mcp_tutorial-0.1.1-py3-none-any.whl |
|---|---|
| Size | 8.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5f4d57a923008c5fd588c57556edc2a7ab6044eed3ab25ad7d83d308764fd4ca
|
|
BLAKE2b-256 checksum How to use checksums |
3699c6bb371065a65c5cb89f29c58493c4df2c60f6d20b251081d48a17ee5cfb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_teddynote-lab-mcp-tutorial 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.