byteforce

CPN 한국어 자습서 · Introduction to Model Context Protocol

2 · Hands-on with MCP servers

MCP 프로젝트 설정

Project setup

CLI 문서 챗봇을 직접 만들며 MCP를 익힙니다. 메모리에만 존재하는 가짜 문서 모음을 다루고, 작은 MCP 클라이언트가 우리가 만든 커스텀 MCP 서버에 연결합니다. 지금 서버에는 도구가 둘 — 문서 읽기와 수정. 시작 코드(CLIproject.zip)를 받아 .env에 API 키를 넣고 uv run main.py로 띄웁니다.

전체 내레이션영상 나레이션 한국어 번역 (전체)›

Stephen Grider · Anthropic 기술 스태프

MCP의 몇 가지 측면을 더 잘 이해하기 위해, 이제 우리만의 CLI 기반 챗봇을 직접 구현하기 시작합니다. 이렇게 하면 Claude와 서버가 실제로 어떻게 함께 동작하는지 더 잘 알 수 있습니다. 이번 영상에서는 프로젝트 설정을 조금 하고, 우리가 정확히 무엇을 만들지 이해를 돕고자 합니다. 지금은 높은 수준에서 큰 그림만 잡으면 됩니다.

앞서 말했듯 CLI 기반 챗봇입니다. 사용자가 문서 모음을 다룰 수 있게 합니다. 이 문서들은 가짜이며, 메모리에만 저장됩니다. 그리고 우리가 만든 커스텀 MCP 서버에 연결하는 작은 MCP 클라이언트를 만듭니다. 지금 이 서버 안에는 도구가 두 개 구현됩니다 — 하나는 문서 내용을 읽는 도구, 하나는 문서 내용을 수정하는 도구입니다. 문서는 전부 가짜라서 메모리에만 유지됩니다. 그게 전부입니다.

더 나아가기 전에, 이 전체 과정에서 꼭 이해하길 바라는 아주 중요한 점이 하나 있습니다. 보통 실제 프로젝트에서는 클라이언트 또는 MCP 서버 중 하나만 구현합니다. 예를 들어 우리가 만든 어떤 서비스를 개발자들이 쓸 수 있도록, MCP 서버만 만들어 세상에 배포할 수 있습니다. 반대로, 다른 엔지니어가 이미 구현해 둔 외부 MCP 서버에 연결하려고 MCP 클라이언트만 만드는 프로젝트일 수도 있습니다.

그런데 이 프로젝트에서는 클라이언트와 서버를 둘 다 만듭니다. 한 프로젝트 안에 둘을 같이 두는 이유는 순전히, 이 둘이 실제로 어떻게 맞물려 동작하는지 더 잘 이해하기 위해서입니다. 자, 이 면책 안내를 끝냈으니 설정을 조금 진행해 봅시다.

이 영상에 첨부된 CLIproject.zip 파일을 찾으면, 그 안에 프로젝트 시작 코드가 들어 있습니다. 그 zip 파일을 내려받아 압축을 풀고, 코드 에디터로 프로젝트 디렉터리를 엽니다. 저는 시간을 아끼려고 이미 그렇게 해 두었습니다. 프로젝트 안의 readme.md 파일을 꼭 살펴보길 권합니다. 여기에 설정 안내를 적어 두었습니다 — 프로젝트 안의 .env 파일에 API 키를 넣는 과정과, uv를 쓰거나 쓰지 않고 의존성을 설치하는 과정을 안내합니다.

이 설정을 모두 마치면 곧바로 시작 프로젝트를 실행할 수 있습니다. 터미널에서 프로젝트 디렉터리 안에 있는지 확인합니다. 저는 프로젝트를 MCP라고 불렀고, 그 안에 여러 프로젝트 파일과 폴더가 들어 있습니다. uv를 쓴다면 uv run main.py로 실행합니다. uv를 쓰지 않는다면 그냥 python main.py가 됩니다. 저는 uv를 쓰므로 uv run main.py를 실행합니다.

실행하면 채팅 프롬프트가 나타나야 합니다. "1 더하기 1은?"이라고 물으면 꽤 빠르게 응답이 보일 것입니다. 설정은 이것으로 끝입니다. 이제 이 애플리케이션에 새 기능을 더하는 데 집중할 수 있습니다.

이 장에서 배우는 것What you'll learn

약 4분
1

CLI 문서 챗봇을 만들며 MCP를 직접 구현

2

문서는 메모리의 가짜 dict — 디스크에 안 남음

3

MCP 클라이언트가 우리 커스텀 서버에 연결

4

지금 서버 도구 둘 — 문서 read · edit

5

학습용으로 클라/서버 둘 다 — 실무는 보통 하나

6

.env 키 → uv run main.py → "1+1?" 확인

먼저 짚고 갈 용어
CLI 챗봇
터미널(명령줄)에서 동작하는 채팅 앱. 여기선 문서를 읽고 고치는 도구를 갖춘다.
메모리 docs
파일이 아니라 코드 안 dict로만 존재하는 가짜 문서. 프로그램이 끝나면 사라진다.
클라이언트 vs 서버
실무에선 보통 둘 중 하나만 만든다. 이 프로젝트는 학습용으로 둘 다 한곳에 둔다.
uv
빠른 Python 패키지 매니저. uv run main.py로 실행(uv 없으면 python main.py).

무엇을 만드나

A CLI document chatbot

터미널에서 동작하는 문서 챗봇을 직접 구현합니다. 사용자는 문서 모음을 다루고, 작은 MCP 클라이언트가 우리가 만든 커스텀 MCP 서버에 연결합니다.

문서는 전부 가짜이며 메모리에만 존재합니다 — 코드 안의 dict로만 있다가 프로그램이 끝나면 사라집니다. 지금 서버 안에는 도구가 둘 — 문서 내용을 읽는 도구 하나, 내용을 수정하는 도구 하나입니다.

프로젝트 구조 · 파일을 누르면 역할이 보입니다 
mcp_project/
  mcp_server.py      # FastMCP 서버 + 도구
  mcp_client.py      # MCPClient 클래스
  core/              # 이미 구현된 CLI
       claude.py
       cli.py
       cli_chat.py
       tools.py
  main.py            # 진입점
  .env               # API 키
  pyproject.toml     # 의존성
R

read_doc_contents

문서 하나의 내용을 읽어 문자열로 돌려줍니다.

인자 · doc_id

E

edit_document

문서 안의 한 문자열을 새 문자열로 바꿔(찾아 치환) 수정합니다.

인자 · doc_id, old_str, new_str

실행uv run main.py·물어보기1 + 1 = ?→2

지금 서버 도구는 둘뿐입니다 — 읽기와 수정. 이후 레슨에서 인스펙터, 클라이언트, 리소스, 프롬프트를 하나씩 붙여 나갑니다.

중요 · 클라이언트와 서버를 둘 다

Both, for learning

꼭 짚을 점이 있습니다. 보통 실제 프로젝트에서는 클라이언트 또는 서버 중 하나만 구현합니다.

왜 그런가

우리가 만든 서비스를 개발자들이 쓰도록 MCP 서버만 만들어 배포하거나, 이미 누군가 만든 외부 MCP 서버에 연결하려고 MCP 클라이언트만 만드는 식입니다.

그런데 이 프로젝트는 둘이 어떻게 맞물려 동작하는지 제대로 이해하기 위해, 한 프로젝트 안에서 클라이언트와 서버를 둘 다 만듭니다. 순전히 학습 목적입니다.

한눈에
  • mcp_server.py — FastMCP 서버와 도구(다음 레슨에서 작성).
  • mcp_client.py — 서버에 연결하는 MCPClient 클래스.
  • core/ · main.py — 이미 구현된 CLI와 진입점.

설정하고 실행하기

Setup & run

이 영상에 첨부된 CLIproject.zip을 내려받아 압축을 풀고, 코드 에디터로 그 디렉터리를 엽니다. 안의 readme.md에 설정 안내가 들어 있습니다.

설정 단계
  • CLIproject.zip 다운로드 → 압축 해제 → 에디터로 열기.
  • readme.md대로 .env에 API 키 넣기.
  • 의존성 설치 — uv로 하거나, uv 없이 설치.

설정을 마치면 터미널에서 프로젝트 디렉터리 안에 있는지 확인하고 실행합니다. uv를 쓰면 uv run main.py, uv를 쓰지 않으면 python main.py입니다.

실행하면 채팅 프롬프트가 나타납니다. "1 더하기 1은?"이라고 물어 응답이 빠르게 돌아오면 설정이 끝난 것입니다. 이제 이 앱에 새 기능을 더하는 데 집중하면 됩니다.

확인 신호

채팅 프롬프트가 뜨고 "1+1?"에 2가 곧바로 오면 시작 코드가 정상 동작합니다.

정리 & 점검

Recap & check
핵심 정리
  • CLI 문서 챗봇을 직접 만들며 MCP를 익힌다. 문서는 메모리 dict(가짜).
  • MCP 클라이언트가 우리 커스텀 서버에 연결. 서버 도구는 지금 둘 — read·edit.
  • 실무는 보통 클라/서버 하나만, 이 프로젝트는 학습용으로 둘 다.
  • .env에 키 → uv run main.py(또는 python main.py) → "1+1?"로 확인.

Q1이 프로젝트의 문서는 어디에 저장되나요?

Q2실무에서는 보통 무엇을 만드나요?

Q3설정 후 프로젝트를 실행하는 명령은?