AI 서재
책으로 읽는 AI서재
한 권을 고르고, 목차에서 차례대로 읽을 수 있게 정리했습니다.
PDF 다운로드 책
다국어로 읽는 대학생 교양 인공지능
한국어 원문과 외국어 번역을 함께 실은 유학생용 교재입니다. 각 책 소개 페이지에서 PDF를 받을 수 있습니다.
[AI서재] 9장 MCP 연결 서버: 에이전트 확장하기
클로드 코드 완전정복
9장 MCP 연결 서버: 에이전트 확장하기
김경진 변호사
도입
토요일 아침, 케이크를 만들기로 마음먹었습니다. 레시피에는 달걀, 밀가루, 프로스팅이 필요합니다. 달걀은 양계장에서 사야 하고, 밀가루는 제분소에서 사야 하고, 프로스팅은 제과 재료 전문점에서 사야 합니다. 세 군데를 돌아다니며 각각의 주문 방식을 익히고, 각각의 결제 시스템을 통과해야 합니다. 번거롭습니다. 그런데 동네에 슈퍼마켓이 하나 있다면 어떨까요.
한 곳에서 달걀도 사고 밀가루도 사고 프로스팅도 삽니다. 주문 방식도 하나, 결제 시스템도 하나입니다. MCP 연결 서버가 바로 이 슈퍼마켓입니다.
MCP란 무엇인가: 슈퍼마켓 비유
MCP는 모델 컨텍스트 프로토콜(Model Context Protocol)의 약자입니다. 에이전트가 외부 서비스에 접근할 때 사용하는 표준화된 연결 방식입니다.
Gmail을 예로 들어 보겠습니다. Gmail에는 이메일을 보내는 기능이 있고, 읽는 기능이 있고, 검색하는 기능이 있고, 초안을 만드는 기능이 있습니다. 하나의 서비스 안에 여러 가지 도구가 들어 있습니다. Gmail MCP 연결 서버를 클로드 코드에 연결하면, 에이전트는 이 모든 도구를 한꺼번에 사용할 수 있게 됩니다.
"이메일 보내기"를 위해 별도의 스크립트를 짤 필요가 없습니다. "검색하기"를 위해 API 문서를 뒤질 필요도 없습니다. 에이전트가 MCP 연결 서버에 연결되어 있으면, 어떤 도구가 있는지 자동으로 파악하고, 상황에 맞는 도구를 골라서 사용합니다.
슈퍼마켓 비유를 좀 더 확장해 보겠습니다.
- MCP 연결 서버 없이: 달걀이 필요하면 양계장(이메일 전송 API)에 직접 가야 합니다. 밀가루가 필요하면 제분소(웹 웹 정보 수집 API)에 직접 가야 합니다. 각 가게마다 주문서 양식이 다르고, 영업시간이 다르고, 결제 방식이 다릅니다.
- MCP 연결 서버 사용: 슈퍼마켓(Gmail MCP 연결 서버, Firecrawl MCP 연결 서버 등) 하나에 들어가면 필요한 재료를 전부 구할 수 있습니다. 에이전트는 슈퍼마켓의 진열대(도구 목록)를 둘러보고, 필요한 것만 장바구니에 담습니다.
[그림 9-1] 왼쪽에 "MCP 없이"로 에이전트가 개별 API 세 곳에 각각 연결하는 모습, 오른쪽에 "MCP 사용"으로 에이전트가 MCP 연결 서버 하나를 통해 여러 도구에 접근하는 모습을 비교하는 다이어그램]
MCP의 핵심은 표준화입니다. 어떤 서비스든 MCP 규격에 맞춰 서버를 만들어 두면, 클로드 코드는 동일한 방식으로 연결하고 동일한 방식으로 도구를 호출합니다. Gmail이든 Firecrawl이든 Google Calendar든, 연결 방법의 골격이 같습니다.
Firecrawl MCP 연결 서버 설치 실습
이론만으로는 감이 잡히지 않습니다. 실제로 MCP 연결 서버를 하나 설치해 보겠습니다. Firecrawl은 웹사이트의 데이터를 수집하는 서비스입니다. 웹 웹 정보 수집(Web Scraping), 크롤링(Crawling), 검색, 스크린샷 캡처 등 여러 기능을 제공합니다. 이 서비스의 MCP 연결 서버를 클로드 코드에 연결하면, 에이전트가 자유롭게 웹 데이터를 가져올 수 있게 됩니다.
1단계: Firecrawl API 키 발급
Firecrawl 웹사이트(firecrawl.dev)에 접속하여 계정을 만듭니다. 무료 플랜으로 시작하면 500크레딧을 받습니다. 실습하기에 충분한 양입니다. 대시보드에 들어가면 API 키가 표시되어 있습니다. 이 키를 복사해 둡니다.
2단계: .env 파일에 API 키 저장
프로젝트 루트에 .env 파일이 없으면 생성합니다. 이미 있다면 해당 파일을 엽니다. 여기에 API 키를 다음과 같은 형식으로 저장합니다.
FIRECRAWL_API_KEY=fc-xxxxxxxxxxxxxxxxxxxxxxxx왜 .env 파일에 저장합니까? 이유는 다음 절에서 자세히 다루겠지만, 핵심만 말하면 이렇습니다. API 키는 비밀번호와 같습니다. 대화 기록에 직접 입력하면, 그 키가 한 번에 읽는 범위 안에 평문으로 남습니다. .env 파일에 저장하면 에이전트가 필요할 때 파일에서 읽어 오되, 대화 기록 자체에는 키가 노출되지 않습니다.
3단계: MCP 연결 서버 설치 명령 실행
클로드 코드에게 설치를 요청합니다. Firecrawl의 공식 문서에는 클로드 코드 명령줄 방식용 설치 명령어가 안내되어 있습니다. 에이전트에게 이렇게 말합니다.
Firecrawl MCP 서버를 설치하고 싶어. 아래 명령어를 사용해서 설치해 줘.
[Firecrawl 공식 문서에서 복사한 CLI 명령어 붙여넣기]
단, API 키는 직접 넘기지 마. .env 파일에서 읽어 와.에이전트는 명령어를 실행하여 MCP 연결 서버를 프로젝트에 등록합니다. 설치가 완료되면, .env 파일에 저장된 API 키를 참조하도록 설정을 마무리합니다.
4단계: 설치 확인
설치가 끝났으면 /context 명령어를 입력해 봅니다. MCP 도구 항목에 Firecrawl 관련 도구들이 표시되어야 합니다. 웹 웹 정보 수집, 크롤링, 검색 등의 도구가 목록에 나타나면 정상적으로 연결된 것입니다.
[그림 9-2] /context 명령어 실행 결과에서 MCP Tools 섹션에 Firecrawl 도구 목록이 표시된 화면 캡처]
이 시점부터 에이전트는 "이 URL에서 직업 공고를 웹 정보 수집해 줘"라는 자연어 요청을 받으면, Firecrawl MCP 연결 서버의 적절한 도구를 자동으로 선택하여 실행합니다. 어떤 엔드포인트를 호출해야 하는지, 어떤 파라미터를 넘겨야 하는지를 사용자가 알 필요 없습니다.
API 키 보안: .env 파일에 비밀을 저장하는 이유
Firecrawl 설치 과정에서 .env 파일을 언급했습니다. 왜 API 키를 대화창에 직접 입력하면 안 되는지, 좀 더 깊이 살펴보겠습니다.
API 키(API Key)는 외부 서비스에 접근하기 위한 인증 수단입니다. 비밀번호와 본질적으로 같습니다. 이 키가 노출되면 누군가가 내 계정으로 서비스를 사용할 수 있고, 비용이 청구될 수 있습니다.
클로드 코드 대화창에 API 키를 직접 붙여 넣으면 어떤 일이 벌어집니까? 그 키는 대화 기록의 일부가 됩니다. 한 번에 읽는 범위 안에 평문으로 존재합니다. 에이전트가 Bash 명령어를 실행할 때 키를 인자로 전달하면, 실행 로그에도 키가 남을 수 있습니다. 보안 관점에서 바람직하지 않습니다.
.env 파일을 사용하면 이 문제가 완화됩니다. 키는 내 컴퓨터 파일에만 존재합니다. 에이전트는 스크립트 내에서 os.environ 같은 방식으로 환경 변수를 읽어 오고, 키 값 자체는 대화 기록에 남지 않습니다.
여기에 한 가지 안전장치를 더합니다. 프로젝트에 .gitignore 파일을 만들고, .env를 목록에 추가합니다. 이렇게 하면 프로젝트를 깃허브(GitHub) 같은 공개 저장소에 올리더라도 .env 파일은 업로드되지 않습니다. 비밀이 인터넷에 노출되는 사고를 방지할 수 있습니다.
# .gitignore
.env이 두 줄이 보안의 기본 방어선입니다.
[그림 9-3] API 키의 안전한 관리 흐름을 보여주는 다이어그램. ".env 파일 → 환경 변수로 로드 → 스크립트에서 참조" 경로와, "대화창에 직접 입력 → 컨텍스트 기록에 노출" 경로를 비교]
실습 중에 실수로 API 키를 대화창에 입력했다면, 해당 키를 즉시 교체(Rotate)하는 것이 안전합니다. 서비스 대시보드에서 기존 키를 폐기하고 새 키를 발급받아 .env 파일에 저장하면 됩니다.
MCP로 확장되는 에이전트의 행동 반경
Firecrawl 하나를 연결했을 뿐인데, 에이전트가 할 수 있는 일의 범위가 크게 넓어졌습니다. 구직 사이트에서 수백 개의 공고를 웹 정보 수집하여 엑셀 파일로 정리할 수 있습니다. 옐로우 페이지에서 치과 의사 연락처를 수집하여 영업용 리드 목록을 만들 수 있습니다. 경쟁사 웹사이트를 정기적으로 모니터링할 수 있습니다.
하나의 MCP 연결 서버가 하나의 슈퍼마켓이라면, 여러 MCP 연결 서버를 연결하는 것은 여러 슈퍼마켓 회원권을 동시에 보유하는 것과 같습니다. Gmail MCP 연결 서버를 추가하면 이메일 읽기, 보내기, 검색이 가능해집니다. Google Calendar MCP 연결 서버를 추가하면 일정 조회와 생성이 가능해집니다.
이들을 조합하면 "오늘 받은 이메일 중 회의 요청을 찾아서 캘린더에 일정을 추가해 줘"라는 복합적인 요청을 에이전트가 처리할 수 있습니다.
| MCP 서버 | 제공하는 도구(예시) |
|---|---|
| Firecrawl | 웹 스크래핑, 크롤링, 검색, 스크린샷 |
| Gmail | 이메일 보내기, 읽기, 검색, 초안 생성 |
| Google Calendar | 일정 조회, 생성, 수정, 삭제 |
| Notion | 페이지 생성, 데이터베이스 조회, 코멘트 |
| Slack | 메시지 전송, 채널 조회, 파일 업로드 |
[그림 9-4] 에이전트를 중심에 두고, Firecrawl·Gmail·Calendar·Notion 등 여러 MCP 연결 서버가 방사형으로 연결된 다이어그램. 각 서버 옆에 대표 도구 2에서 3개를 작은 아이콘으로 표시]
MCP 연결 서버를 추가할 때마다, 해당 서비스의 API 키를 .env 파일에 저장하고, 설치 명령어를 실행하는 패턴은 동일합니다. 한 번 익힌 절차를 반복할 뿐입니다.
여기서 한 가지 유의할 점이 있습니다. MCP 연결 서버를 연결할수록 한 번에 읽는 범위에서 MCP 도구 정의가 차지하는 비중이 커집니다. 앞 장에서 다룬 /context 명령어로 확인하면, MCP Tools 항목의 모델이 세는 글 조각 소모량이 늘어나 있는 것을 볼 수 있습니다. 에이전트의 손은 많아졌지만, 기억할 수 있는 공간은 줄어든 셈입니다.
필요 없는 MCP 연결 서버를 무분별하게 연결하면, 정작 중요한 대화 내용을 담을 공간이 부족해질 수 있습니다.
MCP 연결 서버의 선택은 프로젝트의 목적에 맞춰야 합니다. 경쟁사 분석을 하는 프로젝트에 Gmail MCP 연결 서버가 필요하지는 않습니다. 이메일 자동화를 하는 프로젝트에 Firecrawl이 꼭 있어야 하는 것도 아닙니다. 필요한 손만 달아 주는 것이 효율적입니다.
에이전트에게 기억(한 번에 읽는 범위)과 지침(claude.md)과 손(MCP 연결 서버)을 갖추어 주었습니다. 이 세 가지가 어우러지면, 에이전트는 비로소 실질적인 업무를 수행할 준비가 됩니다. 이제 이 도구들을 결합하여 실제 프로젝트를 구축하는 과정으로 넘어갑니다.
이 책이 잠시라도 당신 곁에 머물렀다면, 다음 이야기가 세상에 나올 수 있도록 후원해 주세요.
(자발적 후원 부탁 구좌 : 농협 302-1096-0948-81 예금주 : 김경진)