Matthewoong Lesson 03 — MCP 연결하기
학습자가 끝나면 MCP가 무엇인지 이해하고, 무료 MCP 1개를 본인 환경에 연결해 첫 호출까지 시연할 수 있다.
이 스킬은 대화형 강의입니다. 단순히 MCP를 대신 설치해주는 게 아니라, 학습자가 한 청크씩 따라오며 어떤 MCP를 선택할지 스스로 결정하고 직접 손으로 연결하도록 옆에서 가이드합니다.
0. 시작하기 전에 — 반드시 따라야 할 공통 규칙
| 문서 | 언제 참조하나 |
|---|---|
_shared/teaching-protocol.md |
이론 lesson을 청크 단위로 진행할 때마다 |
_shared/guided-practice-protocol.md |
이론이 끝나고 가이드 실습 모드로 전환할 때 |
_shared/learner-profile-schema.md |
학습자 프로필을 읽고 갱신할 때 |
_shared/style-guide.md |
출력 톤·도구 비종속 표기·OS 분기·동적 예시 |
_shared/menu-template.md |
첫 진입 / 메뉴 / 트랙 분기 |
위 규칙이 모든 강의 출력의 기본입니다.
1. 진입 시 행동
- 학습자 프로필 확인 —
_shared/learner-profile.json없으면 menu-template.md의 첫 진입 흐름 먼저. - 이 강의 진도 확인 —
progress["03-mcp"].status값에 따라 분기 (not_started/in_progress/completed/skipped). - 선행 강의 권장 안내 — 1·2강이 미수강이면 한 번 안내 후 학습자 결정.
- 첫 인사 —
{{name}}님 호명 + 30분 분량 + 한 청크씩 진행. - 이론 lesson 진입 —
lesson/01-*.md부터 순서대로. 청크 헤더📘 [Lesson 3 · 청크 X/Y]. - 이론 마지막 청크 종료 후 → 가이드 실습 진입 (옵션 ≥3개라
practice/options/사용). - 실습 종료 후 → 진도 갱신 + 다음 강의(4강) 안내.
2. 진도 갱신 + draft 키 명세
| 시점 | 갱신 |
|---|---|
| 3강 첫 진입 | progress["03-mcp"].status = "in_progress", current_chunk = 1, last_visited_at |
| 청크 통과 | current_chunk += 1 |
| 청크 5 답변 | draft.chosen_mcp = <학습자가 고른 MCP 이름> |
| 청크 6 답변 | draft.install_steps = <설치 단계 메모> |
| 가이드 실습 진입 시 | draft 정리해서 학습자에게 보여줌 (4-0절) |
| 가이드 실습 호출 성공 | draft.test_call = <호출 결과 요약> |
| 실습 통과 | practice_status = "done", status = "completed", completed_at |
| 학습자 lesson/실습 스킵 | 1·2강 패턴 동일 (status/practice_status 분리 마킹) |
| 모든 갱신 시 | updated_at = 오늘 날짜 |
3강이 사용하는 draft 키
| 키 | 채워지는 시점 | 형식 | 비고 |
|---|---|---|---|
chosen_mcp |
청크 5 | string | filesystem / memory / 자유 입력 |
install_steps |
청크 6 | string | 설치 흐름 메모 |
test_call |
가이드 실습 6단계 | string | 첫 호출 결과 |
3. 이론 lesson 흐름
이론 청크는 lesson/01-*.md부터 lesson/08-*.md까지 8개 파일로 분리. 청크 출력 규칙은 _shared/teaching-protocol.md 따름.
3강에서 왜 한 청크씩 가는가
MCP는 외부 시스템과 에이전트를 잇는 다리라 개념이 추상적입니다. 한 번에 다 보여주면 어떤 MCP를 골라야 할지, 안전한지, 어떻게 호출하는지 흐릿하게 흘러가버려요. 한 청크씩 질문 → 결정 → 다음으로 가야 학습자가 본인 환경에 맞는 MCP를 자기 손으로 고르고 연결할 수 있습니다.
4. 가이드 실습 — 3개 옵션 (practice/options/)
옵션이 3개라 practice/options/ 폴더로 분리합니다. 학습자가 선택한 옵션 파일만 에이전트가 로드.
4-0. 진입 시 draft 정리 (필수)
🎉 이론 끝! 이제 진짜 MCP를 연결해볼 시간이에요.
이론 때 적어주신 내용을 정리해 보여드릴게요.
📝 고른 MCP: <draft.chosen_mcp>
📝 설치 단계 메모: <draft.install_steps>
이걸 토대로 실제로 연결해볼게요. 다시 적으실 필요 없어요.
수정하고 싶은 항목이 있으시면 "MCP 변경", "설치 단계 수정"처럼 말씀해주세요.
비어 있는 키는 "(아직 안 적으셨어요)" 표시 + 실습 중 같이 채움.
4-1. 옵션 제시
어떤 MCP를 연결해보시겠어요?
(1) filesystem MCP — 폴더 안 파일을 에이전트가 읽고 쓰기
(가장 직관적 — 처음이라면 추천)
(2) memory MCP — 대화 기억을 장기 보관
(대화 사이 컨텍스트가 끊어질 때 유용)
(3) 다른 MCP — {{name}}님이 직접 입력
(특정 도구 연결을 원하시면)
번호로 답해주세요.
각 옵션 선택 시 practice/options/<id>.md 로드.
4-2. 가이드 실습 흐름 (각 옵션 공통, 7단계)
_shared/guided-practice-protocol.md의 7단계를 따름:
- 옵션 선택 (위)
- 사전 점검 — Node.js / Python / Docker 등 필요한 런타임 (학습자 OS 맞춤)
- 비용 안내 — MCP 자체 무료지만 호출 시 LLM 비용이 별도 발생 (간단 안내 + 자유 스킵)
- 설치 명령어 (학습자 OS 맞춤)
- 결과 받기
- 첫 호출 시연 —
draft.test_call채움 - 검증 + 마무리
4-3. 검증 기준
| 항목 | 통과 기준 |
|---|---|
| 설치 성공 | 명령어 실행 후 에러 없음 |
| 에이전트 인식 | 에이전트가 MCP를 인식하고 호출 가능 |
| 첫 호출 동작 | 학습자가 트리거로 호출했을 때 기대 결과 반환 |
3개 중 2개 이상 통과 시 ✅. 부족한 항목은 명확히 명시하고, 어떻게 채울지 안내(1강 패턴).
4-4. 트러블슈팅
자주 있는 에러 (권한·네트워크·설정 누락 등)는 옵션별 practice/options/<id>.md 안에 옵션 전용 트러블슈팅 섹션으로 정리.
5. 자리표시자 처리
{{example:concept-name}} — 도메인 동적 예시
학습자 domain에 맞춘 1~2문장 예시 생성. 사실관계·코드·명령어는 자리표시자로 만들지 않음.
{{os:darwin}} ... {{/os}} / {{os:win32}} ... {{/os}} — OS 분기
학습자 OS에 해당 블록만 출력.
{{name}}, {{domain}} — 단순 치환
6. 도구 비종속
본문에서 "Claude가" / "Codex가" 같은 도구명 노출 X. "에이전트가"로 통칭. 도구별 MCP 등록 방식 차이는 부록 박스로.
7. 종료 시 행동
- 진도 갱신 (
status = completed,practice_status결정). - MCP가 어디에 등록됐고, 어떻게 호출되는지 한 번 더 안내.
- 다음 강의 안내 — 4강(prompt-engineering).
8. 강의 작성자 메타 (학습자에게 출력 X)
- 트랙: 기초 (basic) 3강
- 선행 조건: 01-agents-md, 02-skills (권장)
- 분량: 약 30분
- 외부 자료 의존: 학습자가 선택한 MCP 서버 패키지
- 학습 목표:
- MCP의 역할과 동작 원리를 한 문장으로 설명할 수 있다
- 본인 환경에 무료 MCP 1개를 직접 연결해본다
- 트리거 호출로 그 MCP가 동작하는 것을 확인했다
- 다음 강의: 04-prompt-engineering
9. 빠른 자기 점검
- 학습자 프로필을 읽었는가
- 첫 줄에
📘 [Lesson 3 · 청크 X/Y]헤더가 있는가 - 한 청크만 출력했는가
- 끝에 ❓/🛠/🔀 중 하나가 있는가
- 자리표시자를 모두 채웠는가
- 도구명을 본문에 노출하지 않았는가
- 학습자가 시도하기 전에 답을 보여주지 않았는가
- 청크 통과 시
progress["03-mcp"]를 갱신했는가 - 비용 안내가 필요한 시점에 간단 안내 + 자유 스킵을 제공했는가