헤르메스 MCP 가이드 (개념부터 Bright Data 연결, Codex 양방향까지)

이 가이드는 강의 3.3(MCP 이해하기)과 3.4(MCP 실전)를 따라 하며 입력할 명령과 프롬프트를 한곳에 모은 실습 가이드입니다. 흐름은 이렇게 갑니다.

1. MCP 개념을 잡고 마켓플레이스를 둘러봅니다. (강의 3.3)
2. 데이터 수집 외주사 Bright Data에 가입해 무료 크레딧을 받습니다.
3. 대시보드에서 원격(HTTP)과 로컬(stdio) 두 방식으로 붙입니다.
4. 설치했는데 안 보일 때 만나는 두 가지 함정(게이트웨이, 프로필 격리)을 통과합니다.
5. 사용 가이드 스킬을 한 겹 얹습니다.
6. 슬랙에서 일반 요청, 진짜 브라우저, Bright Data 순으로 비교해 효과를 확인합니다.
7. 헤르메스를 Codex의 도구로 내주고, 업무 보고까지 받아봅니다.

💡 사전 요구사항: 이전 강의(멀티 프로필)에서 1호 직원 Oliver를 채용·셋업했다고 가정합니다. 또한 헤르메스 에이전트 설치 및 첫 실행 가이드, 헤르메스 슬랙 메신저 연결 가이드, Codex CLI 설치 및 헤드리스 인증 가이드를 먼저 마치셔야 합니다.

개념 한 줄 정리 (강의 3.3)

MCP(Model Context Protocol)는 AI와 외부 도구를 잇는 표준 규격입니다. 충전기 규격이 USB-C 하나로 통일되며 불편이 사라졌듯, 도구와 에이전트가 MCP라는 규격 안에서 만나면 서로를 위해 따로 개발할 필요가 없습니다. 구조는 셋으로 나뉩니다. 호스트는 회사 전체, 클라이언트는 외주사 전담 연락 담당, 서버는 일을 맡아주는 외주사입니다. 통신은 JSON-RPC 2.0이라는 약속된 문서 규격으로 하고, 서버가 내 컴퓨터에 있으면 로컬(stdio), 인터넷 너머에 있으면 원격(HTTP)입니다.

스킬과 CLI 조합을 이미 배웠는데 MCP가 왜 또 필요한지 궁금하실 수 있어요. CLI는 강력하지만 내 컴퓨터에 설치해야 하고 환경에 종속됩니다. 원격 MCP는 설치 없이 클라이언트 설정만 해주면 모든 리소스가 서버 쪽에서 소비됩니다. 예전에는 MCP가 도구 목록을 처음부터 전부 노출해 컨텍스트를 낭비하는 약점이 있었는데, 헤르메스는 MCP에도 점진적 공개를 적용해 이 약점을 보완했습니다. 그래서 케이스에 따라 스킬+CLI와 MCP를 가려 쓰시면 됩니다.

외주사는 어디서 찾나: 마켓플레이스

연결할 MCP는 마켓플레이스에서 찾습니다. 강의에서 둘러본 세 곳입니다.

• mcp.so: 2만 개가 넘는 MCP가 등록된 열린 장터입니다. 오늘 쓸 Bright Data MCP도 여기서 검색합니다.
• Smithery: 등록 수가 많고, MCP 호스팅 서비스까지 함께 합니다.
• mcprepository.com: 4만 건에 달하는 MCP가 등재되어 있습니다.

⚠️ MCP도 보안 리스크가 있을 수 있습니다. 잘 점검하고 쓰셔야 해요. 사람이 판단하는 보안 이야기는 6단계(스킬 보안 스캔)에서 한 번 더 만납니다.

여기까지가 개념 편입니다. 이제 강의 3.4를 따라 실전으로 갑니다.

1단계. Bright Data 가입과 무료 크레딧

Bright Data는 에이전트가 데이터 분석에 쓸 웹 데이터를 수집해 주는 인프라 서비스입니다. 핵심은 Web Unlocker인데, 캡차와 봇 차단을 우회해서 일반 요청으로는 막히는 사이트도 정식으로 가져옵니다. 스킬+CLI로도, MCP로도 쓸 수 있는 서비스라 오늘 실습 대상으로 골랐습니다.

수강생분들을 위해 20달러 무료 크레딧이 준비되어 있어요. 아래 링크로 가입하시고 프로모 코드를 적용하세요.

• 가입 링크: get.brightdata.com/x3bjcs
• 프로모 코드: dantelabs

가입 절차는 화면 순서대로 따라오시면 됩니다.

1. 가입 링크로 들어가 무료 체험 시작을 누르고, 회사 이메일 또는 소셜 로그인으로 가입합니다.
2. 결제 수단을 추가합니다. 무료 크레딧을 받기 위한 절차일 뿐, 청구되지 않으니 안심하셔도 됩니다.
3. 발급된 API 키를 복사해 잘 보관합니다.
4. "무료 체험 기간을 연장하세요"에서 결제 수단 등록을 마치면 무료 등급이 활성화됩니다.
5. 프로모션 코드 적용 메뉴에 dantelabs를 넣으면 20달러 크레딧이 추가됩니다.

마지막으로 Web Unlocker 존을 만들어 둡니다. API 메뉴에서 웹 잠금 해제 API(Web Unlocker API)를 선택하고, 이름은 기본값 web_unlocker1 그대로 두고 API 추가를 누르세요. 우리는 이 API를 직접 호출하지 않고 MCP를 통해 쓸 거라, 만들어 두기만 하면 됩니다.

⚠️ API 토큰과 존 이름은 본인 계정의 것입니다. 비밀번호처럼 다뤄주세요.

2단계. 공식 repo에서 연결 방식 확인

외주사가 어떻게 연결되는지는 늘 공식 문서에 적혀 있습니다. mcp.so에서 Bright Data를 검색해 공식 MCP의 Visit Server를 누르면 공식 저장소로 이동합니다.

• github.com/brightdata/brightdata-mcp

설치 방법이 두 가지 나와 있어요. HTTP 방식으로 연결하는 URL 주소 하나, 그리고 내 시스템에 npx로 받아 설치하는 로컬 방식 하나. 강의 3.3에서 배운 원격 MCP와 로컬 MCP의 딱 알맞은 예시입니다. 우리는 둘 다 해봅니다.

3단계. 대시보드에서 두 방식으로 붙이기

CLI로도 붙일 수 있지만, 대시보드의 폼으로 추가하는 게 가장 편하고 실수가 없습니다.

hermes dashboard

브라우저에서 대시보드가 열리면 사이드패널에서 MCP 탭을 누르고 Add Server 버튼을 누릅니다.

원격(HTTP) 방식으로 연결

Add Server 폼에서 이름을 적고(brightdata 추천), 연결 방식을 HTTP로 고른 뒤 아래 주소를 넣습니다. 토큰만 본인 것으로 바꿔주세요.

https://mcp.brightdata.com/mcp?token=본인_토큰

저장 후 항목의 번개 모양 버튼을 눌러 테스트하세요. 초록색으로 도구 리스트가 뜨면 성공입니다.

설치할 게 없죠. 인터넷 너머의 외주사에 전화선 하나 연결한 겁니다.

로컬(stdio) 방식으로 연결

이번에는 같은 Bright Data를 로컬 방식으로 붙여봅니다. 방금 만든 HTTP 항목을 지우고, 다시 Add Server를 눌러 방식을 stdio로 고릅니다. 공식 문서의 JSON 표기를 폼에 하나씩 매핑해 넣으면 됩니다.

• command: npx
• args: @brightdata/mcp
• env: API_TOKEN=본인_토큰

env는 JSON처럼 콜론과 따옴표로 쓰지 않고, equal로 잇는 평문 형식입니다. 다시 번개 모양으로 테스트하면 Search Engine, Scrape as Markdown, Search Engine Batch, Scrape Batch, Discover 등 기본 도구 다섯 개가 보입니다.

💡 자격증명 이름이 API_TOKEN이라는 점만 기억하세요. 다른 이름으로 주면 인식하지 못합니다.

💡 더 많은 도구가 필요하면 Pro Mode가 있습니다. env에 PRO_MODE=true를 한 줄 더 넣으면 틱톡, 구글 맵, 구글 쇼핑, 유튜브 같은 전문 크롤러까지 60가지가 넘는 도구가 추가됩니다. 수업은 기본 모드로 진행합니다.

실습을 마치면 어느 한 방식만 남기면 됩니다. 강의에서는 원격(HTTP) 방식으로 최종 등록했습니다. 폼으로 넣은 값은 프로필 설정 파일에 이렇게 저장됩니다.

mcp_servers:
  brightdata:
    command: npx
    args:
      - "@brightdata/mcp"
    env:
      API_TOKEN: ec1d…e414
    enabled: true

4단계. 함정 하나: 설치했는데 목록에 안 보여요 (게이트웨이)

설치가 잘 됐는지 터미널에서 확인해 봅니다.

hermes mcp list

그런데 분명히 대시보드에서 설치했는데 목록이 안 보일 수 있습니다. 강의에서도 그대로 재현된 장면이에요. 먼저 게이트웨이 상태부터 봅니다.

hermes gateway list

앞으로 자주 입력할 명령어입니다. 지난 강의에서 채용한 신입들의 게이트웨이가 시작 전이라면, 두 가지 방법이 있습니다.

hermes -p oliver gateway run
hermes -p oliver gateway install

• gateway run: 포그라운드에서 임시로 돌립니다. 터미널을 닫으면 같이 꺼집니다.
• gateway install: 시스템 서비스로 등록해 백그라운드에서 계속 돌립니다. WSL 사용자는 시스템 서비스로 설치하라는 경고가 뜨는데, 안내대로 엔터를 눌러 설치하면 WSL을 껐다 켜도 게이트웨이가 유지됩니다.

나머지 직원들도 같은 방식으로 install 해주세요. hermes gateway list에서 전 직원이 실행 중으로 보이면 성공입니다.

5단계. 함정 둘: MCP는 프로필별로 격리됩니다 (대시보드 주인)

게이트웨이를 살렸는데도 Oliver의 MCP 목록이 비어 있다면, 대시보드의 주인을 확인할 차례입니다. 대시보드 상단의 프로필 표시를 보세요. active는 oliver인데 괄호로 다른 이름(예: sophie)이 붙어 있다면, 이 대시보드를 띄운 주체가 그 프로필이라는 뜻입니다. 이 상태에서 MCP를 설치하면 oliver가 아니라 그 프로필에게 설치됩니다.

해결은 대시보드를 해당 프로필로 다시 띄우는 겁니다. 대시보드를 띄운 세션에서 종료하고, 이렇게 다시 실행하세요.

hermes dashboard -p oliver

새로 고침하면 oliver가 정상적으로 active가 됩니다. 이 상태에서 3단계의 Add Server를 다시 진행하면 모든 설정이 Oliver 중심으로 설치됩니다.

💡 이번 장면의 교훈은 하나입니다. MCP도 프로필별로 완전히 격리되므로, 직원마다 따로 설치해야 합니다. 현재 구조상 조금 아쉬운 부분인데, 당분간은 대시보드를 해당 프로필로 띄워 작업해 주세요.

6단계. 스킬로 한 겹 더: brightdata-guide 설치

MCP만 단독으로 쓰지 않고, 그 도구를 잘 쓰도록 안내하는 가이드 스킬을 함께 얹는 패턴을 권합니다. 먼저 허브에서 검색해 봅니다.

hermes skills search "bright data" --source skills-sh

검색 결과에 Bright Data 공식 MCP 스킬이 보입니다. 그런데 강의에서 이 공식 스킬을 설치해 보면, 헤르메스의 보안 스캔이 정책 위배 항목을 찾아 설치를 거절합니다. 공식 스킬인데도요. --force로 강제할 수 있지만, 그 전에 hermes skills inspect로 내용을 직접 확인하고 판단해야 합니다. 여기부터는 사람이 판단하는 보안 영역이에요.

우리는 더 안전한 길로 갑니다. 단테가 보안 문제가 없도록 재구성해 공개한 가이드 스킬을 설치합니다.

hermes -p oliver skills install skills-sh/dandacompany/dante-skills/brightdata-guide

이번에는 보안 스캔이 SAFE로 통과합니다. y를 눌러 설치를 마치세요.

설치한 스킬이 로드되도록 게이트웨이를 재시작합니다. 대시보드의 재시작 버튼을 누르거나 터미널에서 실행하세요.

hermes -p oliver gateway restart

스킬 목록에서 brightdata-guide가 검색되고 MCP도 연결되어 있으면 준비 완료입니다.

7단계. 슬랙에서 비교 실험: 점점 센 방법으로 긁어보기

이 도구가 진짜 효과가 있는지, 슬랙에서 Oliver를 불러 직접 확인합니다. 핵심은 방법을 점점 세게 올리는 것입니다. 일반 요청, 진짜 브라우저, Bright Data 순서로요. MAGMA는 패션 브랜드 회사니까, 조사 대상도 패션 브랜드 사이트로 갑니다.

먼저 워밍업으로 해외 브랜드 세 곳(StockX, SSENSE, lululemon)을 일반 요청으로 긁어봅니다.

@Oliver 아래 세 페이지를 Bright Data 도구는 쓰지 말고, 일반 HTTP 요청으로 가져와봐. 사이트별로 HTTP 상태 코드와 무엇에 막혔는지 표로 정리해줘.
- StockX 신상 페이지
- SSENSE 남성 신상 페이지
- lululemon 남성 카테고리 페이지

강의 실측에서는 StockX와 lululemon이 403으로 막혔고(Cloudflare 봇 차단), SSENSE는 통과했습니다. 다음은 같은 세 페이지를 진짜 브라우저로 열어봅니다.

@Oliver 같은 세 페이지를 이번엔 네 브라우저 도구(헤드리스 크롬)로 직접 열어서, 페이지 제목과 본문 첫머리가 보이는지 아니면 사람 확인/접근 거부 화면이 뜨는지 보고해줘. Bright Data는 아직 쓰지 마.

Oliver가 puppeteer 같은 헤드리스 브라우저 라이브러리를 띄워 시도하고, 이 정도 사이트들은 진짜 크롬만으로 통과합니다. 차단이 "그냥 요청이냐" 수준인 사이트라서요. 그럼 진짜 어려운 상대로 갑니다. 국내 쿠팡입니다.

@Oliver 쿠팡 남자 자켓 검색 페이지의 상품 정보를 Bright Data 없이 헤드리스 크롬으로 스크랩 시도해줘. 무한 스크롤과 페이지네이션까지 확장해서 대량으로 모아보고, 다른 방법은 쓰지 말고 결과를 보고해줘.
- https://www.coupang.com/np/search?q=자켓

강의 실측에서는 첫 페이지 단일 로드까지는 성공했지만, 대량 확장 단계에서 스무 번 넘게 반복 시도하다가 access denied로 막혔습니다. 쿠팡 같은 사이트의 봇 차단이 이런 식이에요. 이제 도구를 바꿉니다.

@Oliver 같은 쿠팡 검색 페이지를 이번엔 Bright Data scrape_as_markdown으로 가져와줘. 본문이 몇 자나 추출됐는지, 상품명과 가격이 잡히는지, 앞의 두 방법(일반 요청, 헤드리스 브라우저)과 비교한 표로 정리해줘.

스레드를 보면 가이드 스킬이 먼저 로드되고, 스킬이 MCP 도구를 순서대로 부르는 걸 볼 수 있습니다. 우리가 의도한 그대로죠. 결과는 완전 성공입니다. Bright Data는 residential IP를 회전하며 시도하기 때문에, 막혀도 다시 우회해서 가져옵니다. 상품명과 가격이 잡힌 비교표가 나오면 성공입니다.

💡 봇 차단은 시점과 접속 지역(IP)에 따라 결과가 달라질 수 있습니다. 모든 사이트가 막히는 것도 아니에요. 일반 방식이 통과해 버리면 차단이 더 강한 다른 사이트로 바꿔 시도해 보세요. 네이버 쇼핑처럼 한두 번은 되다가 반복 수집부터 막히는 곳도 좋은 실험 대상입니다.

8단계. 노출: 헤르메스를 Codex의 도구로

지금까지는 우리가 외주사를 쓰는 쪽이었죠. 이번에는 반대로, 헤르메스가 MCP 서버가 되고 Codex가 클라이언트가 됩니다. 헤르메스를 서버로 띄우는 명령은 hermes mcp serve 하나입니다. 실행하면 아무것도 출력되지 않는데, 그게 정상이에요. 서버가 조용히 듣고 있는 상태입니다.

Codex에는 이 서버를 도구로 등록합니다. 문법이 헤르메스와 거의 동일해요.

codex mcp add hermes -- hermes mcp serve
codex mcp list

목록에 hermes가 enabled로 보이면 성공입니다. 이제 codex로 들어가서 /mcp를 치면 hermes의 도구 목록이 보입니다. 메시지 보내기, 이벤트 대기, 폴링, 대화 목록 가져오기 같은 도구들이에요.

가볍게 하나 써봅니다.

헤르메스의 대화 목록을 가져와 줘. hermes를 사용해.

도구 사용 허용을 물으면 allow for this session을 누르세요. 대화 목록이 출력되면 양방향 연결이 확인된 겁니다.

9단계. 업무 보고 핸드오프: Codex가 헤르메스로 보고

이 연결의 가장 실용적인 쓰임새는 업무 보고입니다. Codex에서 작업한 결과를 헤르메스의 메시지 전송 기능으로 보내면, 여러분의 슬랙으로 도착합니다. Codex에서 이렇게 요청해 보세요.

쿠팡의 남성복 카테고리 상품 리스트를 확인해서 상품 정보를 조사하고, 조사한 결과를 헤르메스의 메시지 센드 기능으로 보고서로 전송해줘.

한 가지 미리 말씀드리면, Codex에는 Bright Data를 붙이지 않았기 때문에 수집 자체는 빈약하거나 실패할 수 있습니다. 강의에서도 브라우저 없이 시도하다 수집은 실패했어요. 그래서 에이전트에게 데이터 수집 도구가 중요하다는 게 한 번 더 확인되는 셈이고, 여기서 볼 것은 전송입니다. 전송을 허용하면 success가 뜨고, 슬랙 기본 채널에 Oliver의 보고가 도착합니다.

외부 에이전트로 작업하다가 헤르메스 쪽으로 핸드오프하는 패턴입니다. 작업하던 내용을 헤르메스로 넘겨서 슬랙 앱으로 받아보실 수 있어요.

자주 만나는 문제

• hermes mcp list에 설치한 MCP가 안 보여요. 두 가지를 차례로 확인하세요. 먼저 hermes gateway list로 해당 프로필의 게이트웨이가 실행 중인지(4단계), 다음으로 대시보드를 띄운 주인이 그 프로필이 맞는지(5단계)입니다.
• 로컬 방식에서 인증 오류가 나요. env 이름이 API_TOKEN인지 확인하세요. 다른 이름은 인식하지 못합니다.
• 도구를 붙였는데 Oliver가 못 쓴다고 해요. 새 세션을 열어야 적용됩니다. 슬랙이라면 게이트웨이를 재시작하세요.
• 공식 스킬 설치가 거절됐어요. 정상 동작입니다. hermes skills inspect로 내용을 확인하고 직접 판단하시거나, 이 가이드처럼 SAFE 통과된 대안 스킬을 쓰세요.
• 비교 실험에서 일반 방식도 성공해요. 사이트 차단 정책은 시점과 네트워크에 따라 달라집니다. 차단이 강한 다른 사이트로 바꿔 시도해 보세요.
• Codex가 hermes 도구를 못 찾아요. codex mcp list에서 hermes가 enabled인지 보고, 아니라면 add 명령을 다시 실행하세요.

마무리

오늘 MCP 개념을 잡고(3.3), Oliver에게 외부 도구를 붙이는 법(소비)과 헤르메스를 다른 도구에 내주는 법(노출)을 모두 익혔습니다(3.4). 도구를 직접 만들지 않아도, 표준에 맞는 외주사를 골라 연결하는 것만으로 직원의 능력이 확장됩니다. 다음 강의에서는 이 도구를 든 Oliver에게 목표를 통째로 맡겨서, 알아서 끝까지 조사하게 만들어 봅니다.

💡 관련 가이드: (부록) Brave Search API를 헤르메스에 연결하기도 함께 보시면 조사 직원의 검색 능력을 한층 보강할 수 있습니다.