본문으로 건너뛰기

Hermes와 함께 MCP 사용

anchor alias​

Hermes와 함께 MCP 사용

이 가이드는 일상적인 작업 흐름에서 Hermes Agent와 함께 MCP를 실제로 사용하는 방법을 보여줍니다.

기능 페이지에서 MCP가 무엇인지 설명한다면 이 가이드는 MCP에서 빠르고 안전하게 가치를 얻는 방법에 대한 것입니다.

언제 MCP를 사용해야 합니까?​

다음과 같은 경우 MCP를 사용하세요.

  • 도구가 이미 MCP 형식으로 존재하며 기본 Hermes 도구를 빌드하고 싶지 않습니다.
  • Hermes가 깨끗한 RPC 계층을 통해 로컬 또는 원격 시스템에 대해 작동하기를 원합니다.
  • 세밀한 서버별 노출 제어를 원하는 경우
  • Hermes 코어를 수정하지 않고 Hermes를 내부 API, 데이터베이스 또는 회사 시스템에 연결하려는 경우

다음과 같은 경우에는 MCP를 사용하지 마십시오.

  • 내장된 Hermes 도구는 이미 문제를 잘 해결하고 있습니다.
  • 서버는 거대하고 위험한 도구 표면을 노출하고 이를 필터링할 준비가 되어 있지 않습니다.
  • 매우 좁은 통합 하나만 필요하며 기본 도구가 더 간단하고 안전합니다.

정신 모델​

MCP를 어댑터 계층으로 생각하세요.

  • Hermes는 에이전트으로 남아 있습니다.
  • MCP 서버 기여 도구
  • Hermes는 시작 시 또는 다시 로드할 때 해당 도구를 발견합니다.
  • 모델은 일반 도구처럼 사용할 수 있습니다
  • 각 서버가 얼마나 표시되는지 제어할 수 있습니다.

마지막 부분이 중요합니다. 좋은 MCP 사용은 단순히 "모든 것을 연결"하는 일이 아닙니다. 핵심은 "가장 작은 유용한 표면으로 올바른 것을 연결하는 것"입니다.

1단계: MCP 지원 설치​

표준 설치 스크립트를 사용하여 Hermes를 설치한 경우 MCP 지원이 이미 포함되어 있습니다(설치 프로그램은 uv pip install -e ".[all]"을 실행합니다).

추가 항목 없이 설치했고 MCP를 별도로 추가해야 하는 경우:

cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"

npm 기반 서버의 경우 Node.js 및 npx을 사용할 수 있는지 확인하세요.

많은 Python MCP 서버의 경우 uvx이 좋은 기본값입니다.

2단계: 먼저 서버 하나 추가​

안전한 단일 서버로 시작하세요.

예: 하나의 프로젝트 디렉토리에만 파일 시스템 액세스.

mcp_servers:
project_fs:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]

그런 다음 Hermes를 시작하세요.

hermes chat

이제 구체적인 질문을 해보세요.

Inspect this project and summarize the repo layout.

3단계: MCP가 로드되었는지 확인​

다음과 같은 몇 가지 방법으로 MCP를 확인할 수 있습니다.

  • Hermes 배너/상태는 구성 시 MCP 통합을 표시해야 합니다.
  • Hermes에게 어떤 도구를 사용할 수 있는지 물어보세요.
  • 구성 변경 후 /reload-mcp 사용
  • 서버 연결에 실패하면 로그를 확인하세요.

실용적인 테스트 프롬프트:

Tell me which MCP-backed tools are available right now.

4단계: 즉시 필터링 시작​

서버가 많은 도구를 노출하는 경우 나중에까지 기다리지 마십시오.

예: 원하는 것만 허용 목록에 추가하세요.​

mcp_servers:
github:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
tools:
include: [list_issues, create_issue, search_code]

이는 일반적으로 민감한 시스템에 가장 적합한 기본값입니다.

WSL2: WSL의 Hermes를 Windows Chrome에 연결​

다음과 같은 경우의 실제 설정은 다음과 같습니다.

  • Hermes는 WSL2 내에서 실행됩니다.
  • 제어하려는 브라우저는 Windows에서 정상적으로 로그인된 Chrome입니다.
  • /browser connect은 WSL에서 어색하거나 신뢰할 수 없습니다.

이 설정에서 Hermes는 Chrome에 직접 연결하지 않습니다. 대신에:

  • Hermes는 WSL에서 운영됩니다.
  • Hermes는 로컬 stdio MCP 서버를 시작합니다.
  • 해당 MCP 서버는 Windows 상호 운용성(cmd.exe 또는 powershell.exe)을 통해 시작됩니다.
  • MCP 서버가 라이브 Windows Chrome 세션에 연결됩니다.

정신적 모델:

Hermes (WSL) -> MCP stdio bridge -> Windows Chrome

이 모드가 유용한 이유​

  • 실제 Windows 브라우저 프로필, 쿠키 및 로그인은 그대로 유지됩니다.
  • Hermes는 지원되는 Unix 환경(WSL2)을 유지합니다.
  • 브라우저 컨트롤은 Hermes 핵심 브라우저 전송에 의존하는 대신 MCP 도구로 노출됩니다.

chrome-devtools-mcp을 사용하세요.

Windows Chrome에 이미 chrome://inspect/#remote-debugging에서 실시간 원격 디버깅이 활성화되어 있는 경우 WSL에서 다음과 같이 추가하세요.

hermes mcp add chrome-devtools-win --command cmd.exe --args /c npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics

서버를 저장한 후:

hermes mcp test chrome-devtools-win

그런 다음 새로운 Hermes 세션을 시작하거나 다음을 실행하세요.

/reload-mcp

일반적인 프롬프트​

일단 로드되면 Hermes는 MCP 접두사가 붙은 브라우저 도구를 직접 사용할 수 있습니다. 예를 들어:

调用 MCP 工具 mcp_chrome_devtools_win_list_pages,列出当前浏览器标签页。

/browser connect이 잘못된 도구인 경우​

Hermes가 WSL에서 실행되고 Chrome이 Windows에서 실행되는 경우 Chrome이 열려 있고 디버그 가능하더라도 /browser connect이 실패할 수 있습니다.

일반적인 이유:

  • WSL은 Chrome이 Windows 도구에 노출하는 것과 동일한 호스트-로컬 엔드포인트에 연결할 수 없습니다.
  • 최신 Chrome 라이브 디버깅 흐름은 기존 ws://localhost:9222과 동일하지 않습니다.
  • 브라우저는 chrome-devtools-mcp과 같은 Windows 측 도우미에서 연결하기가 더 쉽습니다.

이러한 경우 동일한 환경 설정을 위해 /browser connect을 유지하고 WSL-Windows 브라우저 브리징을 위해 MCP를 사용합니다.

알려진 함정​

  • MCP를 통해 Windows stdio 실행 파일을 사용할 때 /mnt/c/Users/<you> 또는 /mnt/c/workspace/...과 같은 Windows 마운트 경로에서 Hermes를 시작합니다.
  • /root 또는 /home/...에서 Hermes를 시작하면 Windows는 MCP 서버가 시작되기 전에 UNC 현재 디렉터리 경고를 내보낼 수 있습니다.
  • 페이지를 열거하는 동안 chrome-devtools-mcp --autoConnect 시간이 초과되면 Chrome에서 배경/고정된 탭을 줄이고 다시 시도하세요.

예: 위험한 행위를 블랙리스트에 추가​

mcp_servers:
stripe:
url: "https://mcp.stripe.com"
headers:
Authorization: "Bearer ***"
tools:
exclude: [delete_customer, refund_payment]

예: 유틸리티 래퍼도 비활성화합니다.​

mcp_servers:
docs:
url: "https://mcp.docs.example.com"
tools:
prompts: false
resources: false

필터링은 실제로 어떤 영향을 미치나요?​

Hermes에는 MCP 노출 기능에는 두 가지 범주가 있습니다.

  1. 서버 네이티브 MCP 도구
  • 다음으로 필터링:
    • tools.include
    • tools.exclude
  1. Hermes가 추가된 유틸리티 래퍼
  • 다음으로 필터링:
    • tools.resources
    • tools.prompts

볼 수 있는 유틸리티 래퍼​

자원:

  • list_resources
  • read_resource

프롬프트:

  • list_prompts
  • get_prompt

이러한 래퍼는 다음과 같은 경우에만 나타납니다.

  • 사용자의 구성에서 이를 허용하고
  • MCP 서버 세션은 실제로 이러한 기능을 지원합니다

따라서 Hermes는 서버가 없는 경우 서버에 리소스/프롬프트가 있는 척하지 않습니다.

일반적인 패턴​

패턴 1: 로컬 프로젝트 도우미​

Hermes가 제한된 작업 공간에 대해 추론하도록 하려면 repo-local 파일 시스템 또는 git 서버에 MCP를 사용하세요.

mcp_servers:
fs:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]

git:
command: "uvx"
args: ["mcp-server-git", "--repository", "/home/user/project"]

좋은 메시지:

Review the project structure and identify where configuration lives.
````text
Check the local git state and summarize what changed recently.

패턴 2: GitHub 분류 도우미​

mcp_servers:
github:
command: "npx"
args: ["-y", "@model컨텍스트protocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
tools:
include: [list_issues, create_issue, update_issue, search_code]
prompts: false
resources: false

좋은 메시지:

List open issues about MCP, cluster them by theme, and draft a high-quality issue for the most common bug.
````text
Search the repo for uses of _discover_and_register_server and explain how MCP tools are registered.

패턴 3: 내부 API 도우미​

mcp_servers:
internal_api:
url: "https://mcp.internal.example.com"
headers:
Authorization: "Bearer ***"
tools:
include: [list_customers, get_customer, list_invoices]
resources: false
prompts: false

좋은 메시지:

Look up customer ACME Corp and summarize recent invoice activity.

엄격한 화이트리스트가 제외 목록보다 훨씬 나은 곳입니다.

패턴 4: 문서/지식 서버​

일부 MCP 서버는 직접적인 행동보다는 공유 지식 자산에 더 가까운 프롬프트나 리소스를 노출합니다.

mcp_servers:
docs:
url: "https://mcp.docs.example.com"
tools:
prompts: true
resources: true

좋은 메시지:

List available MCP resources from the docs server, then read the onboarding guide and summarize it.
````text
List prompts exposed by the docs server and tell me which ones would help with incident response.

튜토리얼: 필터링을 사용한 엔드투엔드 설정​

다음은 실제적인 진행 상황입니다.

1단계: 엄격한 화이트리스트로 GitHub MCP 추가​

mcp_servers:
github:
command: "npx"
args: ["-y", "@model컨텍스트protocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
tools:
include: [list_issues, create_issue, search_code]
prompts: false
resources: false

Hermes를 시작하고 다음과 같이 질문하세요.

Search the codebase for references to MCP and summarize the main integration points.

2단계: 필요할 때만 확장​

나중에 문제 업데이트도 필요한 경우:

tools:
include: [list_issues, create_issue, update_issue, search_code]

그런 다음 다시 로드하세요.

/reload-mcp

3단계: 다른 정책을 사용하여 두 번째 서버 추가​

mcp_servers:
github:
command: "npx"
args: ["-y", "@model컨텍스트protocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "***"
tools:
include: [list_issues, create_issue, update_issue, search_code]
prompts: false
resources: false

filesystem:
command: "npx"
args: ["-y", "@model컨텍스트protocol/server-filesystem", "/home/user/project"]

이제 Hermes는 이를 결합할 수 있습니다.

Inspect the local project files, then create a GitHub issue summarizing the bug you find.

MCP가 강력해지는 곳이 바로 Hermes 코어를 변경하지 않는 다중 시스템 워크플로우입니다.

안전한 사용 권장 사항​

위험한 시스템에 대한 허용 목록을 선호합니다.​

금전적, 고객 대면 또는 파괴적인 모든 경우:

  • tools.include 사용
  • 가능한 가장 작은 세트부터 시작하세요

사용하지 않는 유틸리티 비활성화​

서버에서 제공하는 리소스/프롬프트를 검색하는 모델을 원하지 않으면 다음을 끄십시오.

tools:
resources: false
prompts: false

서버 범위를 좁게 유지​

예:

  • 전체 홈 디렉터리가 아닌 하나의 프로젝트 디렉터리에 뿌리를 둔 파일 시스템 서버
  • 하나의 저장소를 가리키는 git 서버
  • 기본적으로 읽기가 많은 도구가 노출되는 내부 API 서버

구성 변경 후 다시 로드​

/reload-mcp

변경 후 다음을 수행하세요.

  • 포함/제외 목록
  • 활성화된 플래그
  • 리소스/프롬프트 토글
  • 인증 헤더 / 환경

증상별 문제 해결​

"서버가 연결되었지만 예상했던 도구가 없습니다."​

가능한 원인:

  • tools.include으로 필터링됨
  • tools.exclude에 의해 제외됨
  • resources: false 또는 prompts: false을 통해 비활성화된 유틸리티 래퍼
  • 서버는 실제로 리소스/프롬프트를 지원하지 않습니다.

"서버가 구성되었지만 아무것도 로드되지 않습니다"​

확인:

  • enabled: false이 구성에 남아 있지 않습니다.
  • 명령/런타임이 존재합니다(npx, uvx 등).
  • HTTP 엔드포인트에 연결할 수 있습니다.
  • 인증 환경 또는 헤더가 정확합니다.

"MCP 서버가 광고하는 것보다 적은 수의 도구가 표시되는 이유는 무엇입니까?"​

Hermes는 이제 서버별 정책과 기능 인식 등록을 존중하기 때문입니다. 이는 예상된 것이며 일반적으로 바람직합니다.

"구성을 삭제하지 않고 MCP 서버를 어떻게 제거합니까?"​

사용:

enabled: false

이는 구성을 유지하지만 연결 및 등록을 방지합니다.

대부분의 사용자에게 적합한 첫 번째 서버:

  • 파일 시스템
  • 자식
  • GitHub
  • MCP 서버 가져오기/문서화
  • 하나의 좁은 내부 API

별로 좋지 않은 첫 번째 서버:

  • 파괴적인 행동이 많고 필터링이 없는 거대한 비즈니스 시스템
  • 제한할 만큼 잘 이해하지 못하는 것