MCP (모델 컨텍스트 프로토콜)

anchor alias

MCP (모델 컨텍스트 프로토콜)

MCP는 헤르메스 에이전트가 외부 도구 서버에 연결하므로 에이전트는 헤르메스 자체를 살 수있는 도구를 사용할 수 있습니다. - GitHub, 데이터베이스, 파일 시스템, 브라우저 스택, 내부 API 등.

이미 다른 곳에서 존재하는 도구를 사용하려면 Hermes를 원하면 MCP는 일반적으로 가장 깨끗한 방법입니다.

MCP가 제공하는 것

• 네이티브 헤르메스 툴을 작성하지 않고 외부 도구 생태계에 액세스
• 로컬 stdio 서버와 같은 구성에서 원격 HTTP MCP 서버
• 자동 도구 발견 및 시작에 등록
• MCP 리소스를 위한 유틸리티 래퍼 및 서버 지원 시 신속한
• per-server filtering 그래서 당신은 실제로 헤르메스를보고 싶은 MCP 도구 만 노출 할 수 있습니다

빠른 시작

1. MCP 지원 설치 (표준 설치 스크립트를 사용하는 경우 이미 포함됨):

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

2. MCP 서버를 ~/.hermes/config.yaml에 추가하십시오:

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

3. 시작 Hermes:

hermes chat

4. MCP 백업 기능을 사용하는 Hermes에게 문의하십시오.

예를 들면:

List the files in /home/user/projects and summarize the repo structure.

Hermes는 MCP 서버의 도구를 발견하고 다른 도구와 같이 사용합니다.

MCP 서버의 두 종류

Stdio 서버

Stdio 서버는 로컬 하위 프로세스로 실행하고 stdin/stdout에 대해 이야기합니다.

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"

stdio 서버를 사용할 때:

• 서버는 로컬로 설치됩니다
• 현지 자원에 대한 낮은 비용 액세스를 원합니다
• command, args, args, env를 보여 주는 MCP 서버 문서는 다음과 같습니다

HTTP 서버

HTTP MCP 서버는 원격 엔드포인트 Hermes가 직접 연결됩니다.

mcp_servers:
  remote_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer ***"

HTTP 서버를 사용할 때:

• MCP 서버는 다른 곳에서 호스팅됩니다
• 당신의 조직은 내부 MCP 엔드포인트를 노출
• 당신은 원하지 않는다 Hermes는 해당 통합을 위한 로컬 서브프로세싱

기본 설정 참조

Hermes는 ~/.hermes/config.yaml에서 MCP 구성을 읽습니다. mcp_servers.

공통 키

이름 *	제품정보	이름 *
command에 대해서	이름 *	stdio MCP 서버 실행
args에 대해서	이름 *	stdio 서버용 Arguments
env에 대해서	뚱 베어	stdio 서버로 전달되는 환경변수
url에 대해서	이름 *	HTTP MCP 엔드포인트
headers에 대해서	뚱 베어	원격 서버에 대한 HTTP 헤더
timeout에 대해서	이름 *	도구 호출 timeout
connect_timeout에 대해서	이름 *	초기 연결 timeout
enabled에 대해서	한국어	false이면 Hermes는 서버가 완전히 건너갑니다
tools에 대해서	뚱 베어	Per-server 도구 필터링 및 유틸리티 정책

Minimal stdio 예제

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

Minimal HTTP 예제

mcp_servers:
  company_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"

Hermes가 MCP 도구를 등록하는 방법

Hermes prefixes MCP 도구 그래서 그들은 내장 된 이름과 충돌하지 않습니다:

mcp_<server_name>_<tool_name>

예제:

계정 관리	MCP 도구	이름 *
filesystem에 대해서	read_file에 대해서	mcp_filesystem_read_file에 대해서
github에 대해서	create-issue에 대해서	mcp_github_create_issue에 대해서
my-api에 대해서	query.data에 대해서	mcp_my_api_query_data에 대해서

연습에서, 당신은 일반적으로 접두사 이름을 수동으로 호출 할 필요가 없습니다 - 헤르메스는 도구를보고 정상적인 이유 중 선택.

MCP 유틸리티 도구

지원될 때, Hermes는 또한 MCP 자원과 신속한 주변의 유틸리티 도구를 등록합니다:

• list_resources에 대해서
• read_resource에 대해서
• list_prompts에 대해서
• get_prompt에 대해서

예를 들어 동일한 접두사 패턴을 가진 서버 당 등록됩니다

• mcp_github_list_resources에 대해서
• mcp_github_get_prompt에 대해서

주요 특징

이 유틸리티 도구는 이제 기능 인식입니다:

• Hermes는 MCP 세션이 실제로 리소스 운영을 지원하는 경우에만 리소스 유틸리티를 등록합니다
• Hermes는 MCP 세션이 실제로 신속한 작업을 지원하는 경우에만 신속한 유틸리티를 등록합니다

그래서 호출 가능한 도구를 노출 하는 서버 하지만 리소스/prompts는 그 여분의 래퍼를 얻을 하지 않습니다.

Per-server 필터링

각 MCP 서버가 Hermes에 기여하는 도구를 제어 할 수 있으며 도구 네임스페이스의 미세한 관리가 가능합니다.

서버가 완전히 비활성화

mcp_servers:
  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false
``enabled: false`이면 Hermes는 서버가 완전히 건너서 연결을 시도하지 않습니다.

### Whitelist 서버 도구 \{#whitelist-server-tools}

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

MCP 서버 도구 만 등록됩니다.

Blacklist 서버 도구

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    tools:
      exclude: [delete_customer]

모든 서버 도구는 제외된 것을 제외하고 등록됩니다.

주의사항

둘 다 존재하는 경우에:

tools:
  include: [create_issue]
  exclude: [create_issue, delete_issue]
``include` 승리.

### Filter 유틸리티 도구도 \{#whitelist-server-tools}

또한 Hermes-added 유틸리티 래퍼를 분리 할 수 있습니다

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

즉:

• tools.resources: false 비활성화 list_resources 및 read_resource
• tools.prompts: false 비활성화 list_prompts 및 get_prompt

전체 예제

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

  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer]
      resources: false

  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

모든 것이 제거되면 어떻게됩니까?

config 필터가 모든 호출 가능한 도구 및 비활성화 또는 omits 모든 지원 유틸리티를 제거하면 Hermes는 그 서버에 대한 빈 실행 시간 MCP 도구 모음을 만들지 않습니다.

그것은 도구 목록을 깨끗하게 유지.

Runtime 동작

발견 시간

Hermes는 MCP 서버를 시작으로 발견하고 정상적인 도구 레지스트리에 도구를 등록합니다.

동적 툴 디스커버리

MCP 서버는 통지할 수 있습니다 notifications/tools/list_changed 알림을 전송하여 실행시에 사용할 수 있는 도구가 변경될 때 헤르메스. Hermes가 이 알림을 받으면 서버의 도구 목록과 레지스트리 업데이트가 자동으로 다시 불러옵니다. 수동 /reload-mcp가 필요 없습니다.

이 기능은 MCP 서버에 유용합니다. 즉, 새로운 데이터베이스 스키마가 로드될 때 도구를 추가하는 서버 또는 서비스가 오프라인으로 진행될 때 도구를 제거합니다.

새로 고침은 같은 서버에서 빠른 화재 알림을 통해 중복을 제거하지 않습니다. Prompt 및 리소스 변경 알림 (prompts/list_changed, resources/list_changed)는 아직 행동하지 않습니다.

관련 상품

MCP 구성을 변경하는 경우, 사용:

/reload-mcp

config에서 MCP 서버를 다시로드하고 사용 가능한 도구 목록을 새로 고침합니다. 런타임 도구가 서버 자체에 의해 푸시를 변경하려면 위의 Dynamic Tool Discovery를 참조하십시오.

회사 소개

각 구성 MCP 서버는 적어도 하나의 등록 도구에 기여할 때 런타임 툴릿을 만듭니다

mcp-<server>

MCP 서버가 툴킷 수준에 대한 이유를 쉽게 만듭니다.

보안 모델

Stdio env 필터링

stdio 서버의 경우, Hermes는 블라인드가 풀 쉘 환경을 전달하지 않습니다.

env 를 명시적으로 구성하고 안전한 기본으로 전달합니다. 이것은 사고 비밀 누설을 감소시킵니다.

Config 수준 노출 통제

새로운 거르는 지원은 또한 안전 통제입니다:

• 당신이보고 싶지 않은 위험한 도구
• 민감한 서버에 대한 최소한의 백리스트 만 노출
• disable resource/prompt 래퍼 당신이 그 표면 노출을 원하지 않을 때

예제 사용 사례

GitHub 서버와 최소 문제 관리 표면

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

그것을 좋아합니다:

Show me open issues labeled bug, then draft a new issue for the flaky MCP reconnection behavior.

stripe 서버 와 위험한 작업 제거

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

그것을 좋아합니다:

Look up the last 10 failed payments and summarize common failure reasons.

단일 프로젝트 루트의 Filesystem 서버

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

그것을 좋아합니다:

Inspect the project root and explain the directory layout.

문제 해결

MCP 서버 연결하지 않음

체크인:

# Verify MCP deps are installed (already included in standard install)
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"

node --version
npx --version

그런 다음 구성을 확인하고 Hermes를 다시 시작합니다.

표시하지 않는 도구

가능한 원인:

• 서버가 연결하지 못했습니다
• 발견 실패
• 당신의 필터 설정 제외 도구
• 유틸리티 기능은 그 서버에 존재하지 않습니다
• 서버는 enabled: false로 비활성화됩니다

당신이 의도적으로 거르는 경우에, 이것은 예상됩니다.

왜 자원이나 신속한 유틸리티가 나타나지 않았습니까?

Hermes는 이제는 모두 true일 때 그 래퍼만 등록합니다

1. config를 사용하면
2. 서버 세션은 실제로 기능을 지원합니다

이것은 의도적이고 정직한 도구 목록을 유지합니다.

사이트맵 샘플링 지원

MCP 서버는 sampling/createMessage 프로토콜을 통해 Hermes에서 LLM inference를 요청할 수 있습니다. 이 MCP 서버를 요청할 수 있습니다. Hermes는 대신 텍스트를 생성 할 수 있습니다. LLM 기능을 필요로하는 서버에 유용하지만 자신의 모델 액세스가 없습니다.

샘플링은 ** 모든 MCP 서버에 대한 기본**에 의해 활성화됩니다 (MCP SDK가 지원되면). sampling 키 아래에서 서버 구성:

mcp_servers:
  my_server:
    command: "my-mcp-server"
    sampling:
      enabled: true            # Enable sampling (default: true)
      model: "openai/gpt-4o"  # Override model for sampling requests (optional)
      max_tokens_cap: 4096     # Max tokens per sampling response (default: 4096)
      timeout: 30              # Timeout in seconds per request (default: 30)
      max_rpm: 10              # Rate limit: max requests per minute (default: 10)
      max_tool_rounds: 5       # Max tool-use rounds in sampling loops (default: 5)
      allowed_models:        # Allowlist of model names the server may request (empty = any)
      log_level: "info"        # Audit log level: debug, info, or warning (default: info)

샘플링 핸들러에는 슬라이딩 창 속도 제한기, per-request timeouts 및 도구 루프 깊이 제한이 포함되어있어 런웨이 사용을 방지합니다. Metrics (request count, errors, 사용된 토큰)는 서버 인스턴스 당 추적됩니다.

특정 서버에 대한 샘플링을 비활성화하려면:

mcp_servers:
  untrusted_server:
    url: "https://mcp.example.com"
    sampling:
      enabled: false

Hermes를 MCP 서버로 실행

**에 연결 ** MCP 서버, 헤르메스도 ** 수 ** MCP 서버. MCP-capable Agent (Claude Code, Cursor, Codex, 또는 MCP 클라이언트)는 Hermes의 메시징 기능을 사용하여 - 목록 대화, 메시지 기록을 읽고 모든 연결된 플랫폼에서 메시지를 보냅니다.

이것을 사용할 때

• Claude Code, Cursor 또는 다른 코딩 에이전트가 Hermes를 통해 Telegram/Discord/Slack 메시지를 전송하고 읽을 수 있습니다
• 한 번에 Hermes의 연결된 메시징 플랫폼의 모든 교량을 연결하는 단일 MCP 서버를 원합니다
• 이미 연결된 플랫폼과 Hermes Gateway를 실행했습니다

빠른 시작

hermes mcp serve

이것은 stdio MCP 서버를 시작합니다. MCP 클라이언트(not you)는 프로세스 수명주기를 관리합니다.

MCP 클라이언트 구성

MCP 클라이언트 구성에 Hermes를 추가합니다. 예를 들어, Claude Code의 ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp", "serve"]
    }
  }
}

또는 특정 위치에 Hermes를 설치하면:

{
  "mcpServers": {
    "hermes": {
      "command": "/home/user/.hermes/hermes-agent/venv/bin/hermes",
      "args": ["mcp", "serve"]
    }
  }
}

사용 가능한 도구

MCP 서버는 OpenClaw의 채널 브리지 표면과 Hermes-specific 채널 브라우저와 일치하는 10 도구를 노출시킵니다

제품 정보	이름 *
conversations_list에 대해서	Active messaging 대화 목록. 플랫폼에 의해 필터 또는 이름으로 검색.
conversation_get에 대해서	세션 키로 한 대화에 대한 자세한 정보를 얻으십시오.
messages_read에 대해서	대화에 대한 최근 메시지 내역을 읽으십시오.
attachments_fetch에 대해서	특정 메시지에서 non-text 첨부 파일 (images, media)을 추출합니다.
events_poll에 대해서	커서 위치 이후 새로운 대화 이벤트에 대한 투표.
events_wait에 대해서	Long-poll / 블록은 다음 이벤트가 도착 때까지 (실제 시간).
messages_send에 대해서	플랫폼(예: telegram:123456, discord:#general)을 통해 메시지를 보내십시오.
channels_list에 대해서	모든 플랫폼에서 사용할 수 있는 메시징 대상 목록.
permissions_list_open에 대해서	이 브리지 세션에서 관찰 된 승인 요청 목록.
permissions_respond에 대해서	승인 요청을 허용하거나 거부 할 수 있습니다.

이벤트 시스템

MCP 서버는 새로운 메시지에 대한 Hermes의 세션 데이터베이스를 조사하는 라이브 이벤트 브리지를 포함합니다. 이 MCP 클라이언트는 들어오는 대화의 실시간 인식을 제공합니다:

# Poll for new events (non-blocking)
events_poll(after_cursor=0)

# Wait for next event (blocks up to timeout)
events_wait(after_cursor=42, timeout_ms=30000)

이벤트 유형: message, approval_requested, approval_resolved

이벤트 큐는 in-memory이며 다리가 연결될 때 시작합니다. 이전 메시지는 messages_read을 통해 사용할 수 있습니다.

제품 설명

hermes mcp serve              # Normal mode
hermes mcp serve --verbose    # Debug logging on stderr

어떻게 작동하나요

MCP 서버는 Hermes의 세션 저장소 (~/.hermes/sessions/sessions.json 및 SQLite 데이터베이스)에서 직접 대화 데이터를 읽습니다. 배경 스레드는 새로운 메시지에 대한 데이터베이스를 조사하고 in-memory 이벤트 큐를 유지합니다. 메시지를 보낼 경우, 그것은 같은 send_message 인프라를 Hermes 에이전트 자체로 사용합니다.

게이트웨이는 읽힌 작업을 위해 실행할 필요가 없습니다 (듣기 대화, 독서 역사, 투표 이벤트). DOES는 플랫폼 어댑터가 활성 연결을 필요로하기 때문에 작업에 대해 실행해야합니다.

현재 제한

• Stdio 운송 만 (HTTP MCP 운송 없음)
• mtime-optimized DB polling을 통해 ~200ms 간격으로 진행 (파일이 변경 될 때 스키 작업)
• 아니 claude/channel 푸시 알림 프로토콜 아직
• Text-only sends(미디어/태치먼트 전송 ...)에 대하여

관련 문서

• 헤르메스 사용
• CLI 명령
• 슬래시 명령
• [FAQ]