MCP (Model Context Protocol)

MCP cho phép Tác nhân Hermes kết nối với các máy chủ công cụ bên ngoài để tác nhân có thể sử dụng các công cụ nằm bên ngoài chính Hermes — GitHub, cơ sở dữ liệu, hệ thống tệp, ngăn xếp trình duyệt, API nội bộ, v.v.

Nếu bạn từng muốn Hermes sử dụng một công cụ đã tồn tại ở một nơi khác, MCP thường là cách rõ ràng nhất để làm điều đó.

MCP mang lại cho bạn những gì

Truy cập vào hệ sinh thái công cụ bên ngoài mà không cần viết công cụ Hermes gốc
Máy chủ stdio cục bộ và máy chủ HTTP MCP từ xa trong cùng một cấu hình
Tự động phát hiện và đăng ký công cụ khi khởi động
Trình bao bọc tiện ích cho tài nguyên MCP và lời nhắc khi được máy chủ hỗ trợ
Lọc trên mỗi máy chủ để bạn chỉ có thể hiển thị các công cụ MCP mà bạn thực sự muốn Hermes xem

Bắt đầu nhanh

Cài đặt hỗ trợ MCP (đã được bao gồm nếu bạn sử dụng tập lệnh cài đặt tiêu chuẩn):

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

Thêm máy chủ MCP vào ~/.hermes/config.yaml :

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

Bắt đầu Hermes:

hermes chat

Yêu cầu Hermes sử dụng khả năng được MCP hỗ trợ.

Ví dụ:

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

Hermes sẽ khám phá các công cụ của máy chủ MCP và sử dụng chúng như mọi công cụ khác.

Hai loại máy chủ MCP

Máy chủ Stdio

Máy chủ Stdio chạy dưới dạng các quy trình con cục bộ và giao tiếp qua stdin/stdout.

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

Sử dụng máy chủ stdio khi:

máy chủ được cài đặt cục bộ
bạn muốn truy cập với độ trễ thấp vào tài nguyên cục bộ
bạn đang theo dõi tài liệu máy chủ MCP hiển thị command , args và env

Máy chủ HTTP

Máy chủ HTTP MCP là điểm cuối từ xa mà Hermes kết nối trực tiếp.

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

Sử dụng máy chủ HTTP khi:

máy chủ MCP được lưu trữ ở nơi khác
tổ chức của bạn hiển thị các điểm cuối MCP nội bộ
bạn không muốn Hermes tạo ra một quy trình con cục bộ cho sự tích hợp đó

Tham khảo cấu hình cơ bản

Hermes đọc cấu hình MCP từ ~/.hermes/config.yaml trong mcp_servers .

Phím chung

Chìa khóa	Loại	Ý nghĩa
`command`	chuỗi	Có thể thực thi cho máy chủ MCP stdio
`args`	danh sách	Đối số cho máy chủ stdio
`env`	lập bản đồ	Biến môi trường được truyền đến máy chủ stdio
`url`	chuỗi	Điểm cuối HTTP MCP
`headers`	lập bản đồ	Tiêu đề HTTP cho máy chủ từ xa
`timeout`	số	Hết thời gian gọi công cụ
`connect_timeout`	số	Hết thời gian kết nối ban đầu
`enabled`	bool	Nếu `false` , Hermes bỏ qua máy chủ hoàn toàn
`tools`	lập bản đồ	Chính sách tiện ích và lọc công cụ trên mỗi máy chủ

Ví dụ về stdio tối thiểu

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

Ví dụ về HTTP tối thiểu

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

Cách Hermes đăng ký công cụ MCP

Hermes đặt tiền tố cho các công cụ MCP để chúng không xung đột với các tên có sẵn:

mcp_<server_name>_<tool_name>

Ví dụ:

Máy chủ	Công cụ MCP	Tên đăng ký
`filesystem`	`read_file`	`mcp_filesystem_read_file`
`github`	`create-issue`	`mcp_github_create_issue`
`my-api`	`query.data`	`mcp_my_api_query_data`

Công cụ tiện ích MCP

Khi được hỗ trợ, Hermes cũng đăng ký các công cụ tiện ích xung quanh tài nguyên MCP và lời nhắc:

list_resources
read_resource
list_prompts
get_prompt

Chúng được đăng ký trên mỗi máy chủ có cùng mẫu tiền tố, ví dụ:

mcp_github_list_resources
mcp_github_get_prompt

Quan trọng

Các công cụ tiện ích này hiện có khả năng nhận biết:

Hermes chỉ đăng ký tiện ích tài nguyên nếu phiên MCP thực sự hỗ trợ hoạt động tài nguyên
Hermes chỉ đăng ký tiện ích nhắc nhở nếu phiên MCP thực sự hỗ trợ thao tác nhắc nhở

Vì vậy, một máy chủ hiển thị các công cụ có thể gọi nhưng không có tài nguyên/lời nhắc sẽ không nhận được các trình bao bọc bổ sung đó.

Lọc trên mỗi máy chủ

Bạn có thể kiểm soát những công cụ mà mỗi máy chủ MCP đóng góp cho Hermes, cho phép quản lý chi tiết không gian tên công cụ của bạn.

Vô hiệu hóa hoàn toàn máy chủ

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

Nếu enabled: false , Hermes hoàn toàn bỏ qua máy chủ và thậm chí không thử kết nối.

Công cụ máy chủ danh sách trắng

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

Chỉ những công cụ máy chủ MCP đó mới được đăng ký.

Công cụ máy chủ danh sách đen

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

Tất cả các công cụ máy chủ đều được đăng ký ngoại trừ những công cụ bị loại trừ.

Quy tắc ưu tiên

Nếu cả hai đều có mặt:

tools:
  include: [create_issue]
  exclude: [create_issue, delete_issue]

include thắng.

Lọc các công cụ tiện ích nữa

Bạn cũng có thể vô hiệu hóa riêng các trình bao bọc tiện ích do Hermes thêm vào:

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

Điều đó có nghĩa là:

tools.resources: false vô hiệu hóa list_resources và read_resource
tools.prompts: false vô hiệu hóa list_prompts và get_prompt

Ví dụ đầy đủ

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

Điều gì xảy ra nếu mọi thứ được lọc ra?

Nếu cấu hình của bạn lọc ra tất cả các công cụ có thể gọi được và vô hiệu hóa hoặc bỏ qua tất cả các tiện ích được hỗ trợ, Hermes sẽ không tạo bộ công cụ MCP thời gian chạy trống cho máy chủ đó.

Điều đó giữ cho danh sách công cụ sạch sẽ.

Hành vi thời gian chạy

Thời gian khám phá

Hermes phát hiện ra các máy chủ MCP khi khởi động và đăng ký các công cụ của họ vào sổ đăng ký công cụ thông thường.

Khám phá công cụ động

Máy chủ MCP có thể thông báo cho Hermes khi các công cụ có sẵn của chúng thay đổi trong thời gian chạy bằng cách gửi thông báo notifications/tools/list_changed. Khi Hermes nhận được thông báo này, nó sẽ tự động tìm nạp lại danh sách công cụ của máy chủ và cập nhật sổ đăng ký — không cần /reload-mcp thủ công.

Điều này hữu ích cho các máy chủ MCP có khả năng thay đổi linh hoạt (ví dụ: máy chủ thêm công cụ khi tải lược đồ cơ sở dữ liệu mới hoặc xóa công cụ khi dịch vụ ngoại tuyến).

Quá trình làm mới được bảo vệ bằng khóa nên các thông báo gửi nhanh từ cùng một máy chủ không gây ra các lần làm mới chồng chéo. Thông báo nhắc nhở và thay đổi tài nguyên ( prompts/list_changed , resources/list_changed ) đã được nhận nhưng chưa được thực hiện.

Đang tải lại

Nếu bạn thay đổi cấu hình MCP, hãy sử dụng:

/reload-mcp

Thao tác này sẽ tải lại máy chủ MCP từ cấu hình và làm mới danh sách công cụ có sẵn. Để biết các thay đổi về công cụ thời gian chạy do chính máy chủ thực hiện, hãy xem Dynamic Tool Discovery ở trên.

Bộ công cụMỗi máy chủ MCP được định cấu hình cũng tạo một bộ công cụ thời gian chạy khi nó đóng góp ít nhất một công cụ đã đăng ký:

mcp-<server>

Điều đó làm cho máy chủ MCP dễ dàng suy luận hơn ở cấp độ bộ công cụ.

Mô hình bảo mật

Lọc môi trường Stdio

Đối với các máy chủ stdio, Hermes không vượt qua môi trường shell đầy đủ của bạn một cách mù quáng.

Chỉ env được định cấu hình rõ ràng cộng với đường cơ sở an toàn mới được thông qua. Điều này làm giảm sự rò rỉ bí mật ngẫu nhiên.

Kiểm soát phơi sáng ở cấp độ cấu hình

Hỗ trợ lọc mới cũng là một biện pháp kiểm soát bảo mật:

vô hiệu hóa các công cụ nguy hiểm mà bạn không muốn mô hình nhìn thấy
chỉ hiển thị danh sách trắng tối thiểu cho máy chủ nhạy cảm
vô hiệu hóa trình bao bọc tài nguyên/lời nhắc khi bạn không muốn bề mặt đó bị lộ

Các trường hợp sử dụng mẫu

Máy chủ GitHub có bề mặt quản lý vấn đề tối thiểu

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

Sử dụng nó như:

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

Máy chủ sọc đã bị loại bỏ các hành động nguy hiểm

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

Sử dụng nó như:

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

Máy chủ hệ thống tập tin cho một dự án gốc

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

Sử dụng nó như:

Inspect the project root and explain the directory layout.

Khắc phục sự cố

Máy chủ MCP không kết nối

Kiểm tra:

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

node --version
npx --version

Sau đó xác minh cấu hình của bạn và khởi động lại Hermes.

Công cụ không xuất hiện

Nguyên nhân có thể:

máy chủ không kết nối được
khám phá thất bại
cấu hình bộ lọc của bạn đã loại trừ các công cụ
khả năng tiện ích không tồn tại trên máy chủ đó
máy chủ bị vô hiệu hóa với enabled: false

Nếu bạn đang cố tình lọc, điều này được mong đợi.

Tại sao tài nguyên hoặc tiện ích nhắc nhở không xuất hiện?

Bởi vì Hermes hiện chỉ đăng ký các trình bao bọc đó khi cả hai đều đúng:

cấu hình của bạn cho phép họ
phiên máy chủ thực sự hỗ trợ khả năng

Điều này là có chủ ý và giữ cho danh sách công cụ luôn trung thực.

Hỗ trợ lấy mẫu MCP

Máy chủ MCP có thể yêu cầu suy luận LLM từ Hermes thông qua giao thức sampling/createMessage. Điều này cho phép máy chủ MCP yêu cầu Hermes thay mặt nó tạo văn bản — hữu ích cho các máy chủ cần khả năng LLM nhưng không có quyền truy cập mô hình của riêng chúng.

Lấy mẫu được bật theo mặc định cho tất cả máy chủ MCP (khi MCP SDK hỗ trợ tính năng này). Định cấu hình trên mỗi máy chủ bằng khóa 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)

Trình xử lý lấy mẫu bao gồm bộ giới hạn tốc độ cửa sổ trượt, thời gian chờ theo yêu cầu và giới hạn độ sâu vòng lặp công cụ để ngăn chặn việc sử dụng quá mức. Số liệu (số lượng yêu cầu, lỗi, mã thông báo được sử dụng) được theo dõi trên mỗi phiên bản máy chủ.

Để tắt tính năng lấy mẫu cho một máy chủ cụ thể:

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

Chạy Hermes với tư cách là máy chủ MCP

Ngoài việc kết nối với máy chủ MCP, Hermes còn có thể là máy chủ MCP. Điều này cho phép các đại lý có khả năng MCP khác (Claude Code, Cursor, Codex hoặc bất kỳ ứng dụng khách MCP nào) sử dụng khả năng nhắn tin của Hermes — liệt kê các cuộc hội thoại, đọc lịch sử tin nhắn và gửi tin nhắn trên tất cả các nền tảng được kết nối của bạn.

Khi nào nên sử dụng cái này- Bạn muốn Claude Code, Cursor hoặc tác nhân mã hóa khác gửi và đọc tin nhắn Telegram/Discord/Slack thông qua Hermes

Bạn muốn có một máy chủ MCP duy nhất kết nối với tất cả các nền tảng nhắn tin được kết nối của Hermes cùng một lúc
Bạn đã có cổng Hermes đang chạy với các nền tảng được kết nối

Bắt đầu nhanh

hermes mcp serve

Điều này khởi động một máy chủ MCP stdio. Máy khách MCP (không phải bạn) quản lý vòng đời của quy trình.

Cấu hình máy khách MCP

Thêm Hermes vào cấu hình máy khách MCP của bạn. Ví dụ: trong ~/.claude/claude_desktop_config.json của Claude Code:

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

Hoặc nếu bạn đã cài đặt Hermes ở một vị trí cụ thể:

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

Công cụ có sẵn

Máy chủ MCP hiển thị 10 công cụ, phù hợp với bề mặt cầu kênh của OpenClaw cộng với trình duyệt kênh dành riêng cho Hermes:

Công cụ	Mô tả
`conversations_list`	Liệt kê các cuộc trò chuyện nhắn tin đang hoạt động. Lọc theo nền tảng hoặc tìm kiếm theo tên.
`conversation_get`	Nhận thông tin chi tiết về một cuộc trò chuyện bằng khóa phiên.
`messages_read`	Đọc lịch sử tin nhắn gần đây cho một cuộc trò chuyện.
`attachments_fetch`	Trích xuất các tệp đính kèm không phải văn bản (hình ảnh, phương tiện) từ một tin nhắn cụ thể.
`events_poll`	Thăm dò các sự kiện hội thoại mới kể từ vị trí con trỏ.
`events_wait`	Thăm dò ý kiến/chặn kéo dài cho đến khi sự kiện tiếp theo đến (gần thời gian thực).
`messages_send`	Gửi tin nhắn qua nền tảng (ví dụ: `telegram:123456` , `discord:#general` ).
`channels_list`	Liệt kê các mục tiêu nhắn tin có sẵn trên tất cả các nền tảng.
`permissions_list_open`	Liệt kê các yêu cầu phê duyệt đang chờ xử lý được quan sát thấy trong phiên cầu nối này.
`permissions_respond`	Cho phép hoặc từ chối yêu cầu phê duyệt đang chờ xử lý.

Hệ thống sự kiện

Máy chủ MCP bao gồm một cầu nối sự kiện trực tiếp thăm dò cơ sở dữ liệu phiên của Hermes để tìm tin nhắn mới. Điều này mang lại cho khách hàng MCP nhận thức gần như theo thời gian thực về các cuộc hội thoại đến:

# 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)

Các loại sự kiện: message , approval_requested , approval_resolved

Hàng đợi sự kiện nằm trong bộ nhớ và bắt đầu khi bridge kết nối. Các tin nhắn cũ hơn có sẵn thông qua messages_read .

Tùy chọn

hermes mcp serve              

# Normal mode
hermes mcp serve --verbose    

# Debug logging on stderr

Cách thức hoạt động

Máy chủ MCP đọc dữ liệu hội thoại trực tiếp từ kho phiên của Hermes ( ~/.hermes/sessions/sessions.json và cơ sở dữ liệu SQLite). Chuỗi nền sẽ thăm dò cơ sở dữ liệu để tìm tin nhắn mới và duy trì hàng đợi sự kiện trong bộ nhớ. Để gửi tin nhắn, nó sử dụng cơ sở hạ tầng send_message giống như chính Hermes Agent.

Cổng KHÔNG cần phải chạy cho các hoạt động đọc (liệt kê các cuộc hội thoại, lịch sử đọc, sự kiện bỏ phiếu). Nó KHÔNG cần phải chạy cho các hoạt động gửi vì bộ điều hợp nền tảng cần có kết nối hoạt động.

Giới hạn hiện tại

Chỉ vận chuyển Stdio (chưa có vận chuyển HTTP MCP)
Kiểm tra vòng sự kiện ở khoảng thời gian ~200 mili giây thông qua kiểm tra vòng cơ sở dữ liệu được tối ưu hóa theo thời gian (bỏ qua hoạt động khi tệp không thay đổi)
Chưa có giao thức thông báo đẩy claude/channel
Chỉ gửi văn bản (không gửi phương tiện/tệp đính kèm qua messages_send )

MCP mang lại cho bạn những gì

Bắt đầu nhanh

Hai loại máy chủ MCP

Máy chủ Stdio​

Máy chủ HTTP​

Tham khảo cấu hình cơ bản

Phím chung​

Ví dụ về stdio tối thiểu​

Ví dụ về HTTP tối thiểu​

Cách Hermes đăng ký công cụ MCP

Công cụ tiện ích MCP

Quan trọng​

Lọc trên mỗi máy chủ

Vô hiệu hóa hoàn toàn máy chủ​

Công cụ máy chủ danh sách trắng​

Công cụ máy chủ danh sách đen​

Quy tắc ưu tiên​

Lọc các công cụ tiện ích nữa​

Ví dụ đầy đủ​

Điều gì xảy ra nếu mọi thứ được lọc ra?

Hành vi thời gian chạy

Thời gian khám phá​

Khám phá công cụ động​

Đang tải lại​

Bộ công cụMỗi máy chủ MCP được định cấu hình cũng tạo một bộ công cụ thời gian chạy khi nó đóng góp ít nhất một công cụ đã đăng ký:​

Mô hình bảo mật

Lọc môi trường Stdio​

Kiểm soát phơi sáng ở cấp độ cấu hình​

Các trường hợp sử dụng mẫu

Máy chủ GitHub có bề mặt quản lý vấn đề tối thiểu​

Máy chủ sọc đã bị loại bỏ các hành động nguy hiểm​

Máy chủ hệ thống tập tin cho một dự án gốc​

Khắc phục sự cố

Máy chủ MCP không kết nối​

Công cụ không xuất hiện​

Tại sao tài nguyên hoặc tiện ích nhắc nhở không xuất hiện?​

Hỗ trợ lấy mẫu MCP

Chạy Hermes với tư cách là máy chủ MCP

Khi nào nên sử dụng cái này- Bạn muốn Claude Code, Cursor hoặc tác nhân mã hóa khác gửi và đọc tin nhắn Telegram/Discord/Slack thông qua Hermes​

Bắt đầu nhanh​

Cấu hình máy khách MCP​

Công cụ có sẵn​

Hệ thống sự kiện​

Tùy chọn​

Cách thức hoạt động​

Giới hạn hiện tại​

Tài liệu liên quan

Máy chủ Stdio

Máy chủ HTTP

Phím chung

Ví dụ về stdio tối thiểu

Ví dụ về HTTP tối thiểu

Quan trọng

Vô hiệu hóa hoàn toàn máy chủ

Công cụ máy chủ danh sách trắng

Công cụ máy chủ danh sách đen

Quy tắc ưu tiên

Lọc các công cụ tiện ích nữa

Ví dụ đầy đủ

Thời gian khám phá

Khám phá công cụ động

Đang tải lại

Bộ công cụMỗi máy chủ MCP được định cấu hình cũng tạo một bộ công cụ thời gian chạy khi nó đóng góp ít nhất một công cụ đã đăng ký:

Lọc môi trường Stdio

Kiểm soát phơi sáng ở cấp độ cấu hình

Máy chủ GitHub có bề mặt quản lý vấn đề tối thiểu

Máy chủ sọc đã bị loại bỏ các hành động nguy hiểm

Máy chủ hệ thống tập tin cho một dự án gốc

Máy chủ MCP không kết nối

Công cụ không xuất hiện

Tại sao tài nguyên hoặc tiện ích nhắc nhở không xuất hiện?

Khi nào nên sử dụng cái này- Bạn muốn Claude Code, Cursor hoặc tác nhân mã hóa khác gửi và đọc tin nhắn Telegram/Discord/Slack thông qua Hermes

Bắt đầu nhanh

Cấu hình máy khách MCP

Công cụ có sẵn

Hệ thống sự kiện

Tùy chọn

Cách thức hoạt động

Giới hạn hiện tại