Chuyển tới nội dung chính

Sử dụng MCP với Hermes

Hướng dẫn này cho thấy cách sử dụng MCP thực sự với Đại lý Hermes trong quy trình làm việc hàng ngày.

Nếu trang tính năng giải thích MCP là gì thì hướng dẫn này sẽ nói về cách nhận được giá trị từ MCP một cách nhanh chóng và an toàn.

Khi nào bạn nên sử dụng MCP?​

Sử dụng MCP khi:

  • một công cụ đã tồn tại ở dạng MCP và bạn không muốn xây dựng một công cụ Hermes gốc
  • bạn muốn Hermes hoạt động chống lại hệ thống cục bộ hoặc từ xa thông qua lớp RPC sạch
  • bạn muốn kiểm soát phơi nhiễm chi tiết trên mỗi máy chủ
  • bạn muốn kết nối Hermes với API nội bộ, cơ sở dữ liệu hoặc hệ thống công ty mà không sửa đổi lõi Hermes

Không sử dụng MCP khi:

  • một công cụ Hermes tích hợp đã giải quyết tốt công việc
  • máy chủ hiển thị bề mặt công cụ rất nguy hiểm và bạn chưa sẵn sàng lọc nó
  • bạn chỉ cần một sự tích hợp rất hẹp và một công cụ gốc sẽ đơn giản và an toàn hơn

Mô hình tinh thần​

Hãy coi MCP như một lớp bộ điều hợp:

  • Hermes vẫn là đại lý
  • Máy chủ MCP đóng góp công cụ
  • Hermes phát hiện ra những công cụ đó khi khởi động hoặc tải lại
  • người mẫu có thể sử dụng chúng như những công cụ thông thường
  • bạn kiểm soát mức độ hiển thị của mỗi máy chủ

Đó là phần cuối cùng quan trọng. Việc sử dụng MCP tốt không chỉ là “kết nối mọi thứ”. Đó là “kết nối đúng thứ, với bề mặt hữu ích nhỏ nhất”.

Bước 1: cài đặt hỗ trợ MCP​

Nếu bạn đã cài đặt Hermes với tập lệnh cài đặt tiêu chuẩn, hỗ trợ MCP đã được bao gồm (trình cài đặt chạy `uv pip install -e ".[all]"

).

Nếu bạn đã cài đặt mà không có tính năng bổ sung và cần thêm MCP riêng:

cd ~/.Hermes/Hermes-agent
uv pip install -e ".[MCP]"

`
``Đối với các máy chủ dựa trên npm, hãy đảm bảo có sẵn Node.js và 
`npx

.

Đối với nhiều máy chủ Python MCP, 
`uvx
` là một mặc định tốt.

## Bước 2: thêm 1 server trước

Bắt đầu với một máy chủ an toàn, duy nhất.

Ví dụ: hệ thống tập tin chỉ truy cập vào một thư mục dự án.

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

`
``Sau đó bắt đầu Hermes:

`bash
Hermes chat

`
``Bây giờ hãy hỏi điều gì đó cụ thể:

`text
Inspect this project and summarize the repo layout.

`

## Bước 3: xác minh đã tải MCP

Bạn có thể xác minh MCP theo một số cách:
- Biểu ngữ/trạng thái Hermes sẽ hiển thị tích hợp MCP khi được định cấu hình

- hỏi Hermes những công cụ nào có sẵn
- sử dụng 

/reload-MCP
` sau khi thay đổi cấu hình
- kiểm tra nhật ký nếu máy chủ không kết nối được

Lời nhắc kiểm tra thực tế:

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

`

## Bước 4: bắt đầu lọc ngay

Đừng đợi đến sau này nếu máy chủ hiển thị nhiều công cụ.

### Ví dụ: chỉ đưa vào danh sách trắng những gì bạn muốn

`YAML
MCP_servers:
  GitHub:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-GitHub"]
    env:
      GitHub_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, search_code]

`
``Đây thường là mặc định tốt nhất cho các hệ thống nhạy cảm.

## WSL2: kết nối Hermes trong WSL với Windows Chrome

Đây là thiết lập thực tế khi:
- Hermes chạy bên trong WSL2

- trình duyệt bạn muốn kiểm soát là Chrome đăng nhập thông thường trên Windows
- 

/browser connect
` khó xử lý hoặc không đáng tin cậy từ WSL

Trong thiết lập này, Hermes **không** kết nối trực tiếp với Chrome. Thay vào đó:
- Hermes chạy trong WSL
- Hermes khởi động máy chủ MCP stdio cục bộ
- máy chủ MCP đó được khởi chạy thông qua Windows interop (
`cmd.exe
` hoặc 
`powershell.exe

)
- máy chủ MCP gắn vào phiên Windows Chrome trực tiếp của bạn

Mô hình tinh thần:

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

`

### Tại sao chế độ này lại hữu ích
- bạn giữ hồ sơ trình duyệt Windows thực, cookie và thông tin đăng nhập của mình

- Hermes vẫn ở trong môi trường Unix được hỗ trợ (WSL2)
- kiểm soát trình duyệt được hiển thị dưới dạng công cụ MCP thay vì dựa vào việc vận chuyển trình duyệt lõi của Hermes

### Máy chủ được đề xuất

Sử dụng 
`chrome-devtools-MCP

.

Nếu Windows Chrome của bạn đã bật tính năng gỡ lỗi từ xa trực tiếp từ 
`chrome://inspect/#remote-debugging

, hãy thêm nó như thế này từ WSL:

``` bash
Hermes MCP add chrome-devtools-win --command cmd.exe --args /c npx -y chrome-devtools-MCP@latest --autoConnect --no-usage-statistics

`
``Sau khi lưu máy chủ:

`bash
Hermes MCP test chrome-devtools-win

`
``Sau đó bắt đầu một phiên Hermes mới hoặc chạy:

`text
/reload-MCP

`

### Lời nhắc điển hình

Sau khi tải, Hermes có thể sử dụng trực tiếp các công cụ trình duyệt có tiền tố MCP. Ví dụ:

`text
调用 MCP 工具 MCP_chrome_devtools_win_list_pages，列出当前浏览器标签页。

`

### Khi 

/browser connect
` dùng nhầm tool

Nếu Hermes chạy trong WSL và Chrome chạy trên Windows, 

/browser connect
` có thể bị lỗi ngay cả khi Chrome đang mở và có thể gỡ lỗi.

Những lý do phổ biến:
- WSL không thể tiếp cận cùng điểm cuối máy chủ cục bộ mà Chrome hiển thị cho các công cụ Windows

- Luồng gỡ lỗi trực tiếp trên Chrome mới hơn không giống với 
`ws://localhost:9222
` cổ điển
- trình duyệt dễ dàng đính kèm hơn từ trình trợ giúp phía Windows như 
`chrome-devtools-MCP
``Trong những trường hợp đó, hãy giữ 

/browser connect
` cho các thiết lập trong cùng môi trường và sử dụng MCP để kết nối trình duyệt WSL với Windows.

### Những cạm bẫy đã biết- Khởi động Hermes từ đường dẫn gắn trên Windows như 

/mnt/c/Users/<you
` hoặc 

/mnt/c/workspace/...
` khi sử dụng các tệp thực thi stdio của Windows thông qua MCP.
- Nếu bạn khởi động Hermes từ 

/root
` hoặc 

/home/...

, Windows có thể phát ra cảnh báo thư mục hiện tại 
`UNC
` trước khi máy chủ MCP khởi động.
- Nếu 
`chrome-devtools-MCP --autoConnect
` hết thời gian trong khi liệt kê các trang, hãy giảm các tab chạy nền/bị treo trong Chrome và thử lại.

### Ví dụ: danh sách đen các hành động nguy hiểm

``` yaml
MCP_servers:
  stripe:
    url: "https://MCP.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer, refund_payment]

`

### Ví dụ: tắt cả trình bao bọc tiện ích

`YAML
MCP_servers:
  docs:
    url: "https://MCP.docs.example.com"
    tools:
      prompts: false
      resources: false

`

## Việc lọc thực sự ảnh hưởng đến điều gì?

Có hai loại chức năng tiếp xúc với MCP trong Hermes:
1. Công cụ MCP gốc của máy chủ

- lọc bằng:
  - 
`tools.include

  - 
`tools.exclude

2. Giấy gói tiện ích được thêm vào Hermes
- lọc bằng:
  - 
`tools.resources

  - 
`tools.prompts

### Trình bao bọc tiện ích bạn có thể thấy

Tài nguyên:
- 
`list_resources

- 
`read_resource
``Lời nhắc:
- 
`list_prompts

- 
`get_prompt
``Các trình bao bọc này chỉ xuất hiện nếu:
- cấu hình của bạn cho phép chúng, và
- phiên máy chủ MCP thực sự hỗ trợ những khả năng đó

Vì vậy, Hermes sẽ không giả vờ như máy chủ có tài nguyên/lời nhắc nếu không có.

## Các mẫu phổ biến

### Mẫu 1: trợ lý dự án địa phương

Sử dụng MCP cho hệ thống tệp repo-local hoặc máy chủ git khi bạn muốn Hermes suy luận về không gian làm việc bị giới hạn.

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

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

`
``Lời nhắc tốt:

`text
Review the project structure and identify where configuration lives.

`

`
`text
Check the local git state and summarize what changed recently.

`

### Mẫu 2: Trợ lý phân loại GitHub

`YAML
MCP_servers:
  GitHub:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-GitHub"]
    env:
      GitHub_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      prompts: false
      resources: false

`
``Lời nhắc tốt:

`text
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.

`

### Mẫu 3: trợ lý API nội bộ

`YAML
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

`
``Lời nhắc tốt:

`text
Look up customer ACME Corp and summarize recent invoice activity.

`
``Đây là nơi mà danh sách trắng nghiêm ngặt sẽ tốt hơn nhiều so với danh sách loại trừ.

### Mẫu 4: máy chủ tài liệu/kiến thức

Một số máy chủ MCP hiển thị các lời nhắc hoặc tài nguyên giống như tài sản kiến thức được chia sẻ hơn là hành động trực tiếp.

`YAML
MCP_servers:
  docs:
    url: "https://MCP.docs.example.com"
    tools:
      prompts: true
      resources: true

`
``Lời nhắc tốt:

`text
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.

`

## Hướng dẫn: thiết lập từ đầu đến cuối với tính năng lọc

Đây là một sự tiến triển thực tế.

### Giai đoạn 1: thêm GitHub MCP với danh sách trắng chặt chẽ

`YAML
MCP_servers:
  GitHub:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-GitHub"]
    env:
      GitHub_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, search_code]
      prompts: false
      resources: false

`
``Bắt đầu Hermes và hỏi:

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

`

### Giai đoạn 2: chỉ mở rộng khi cần thiết

Nếu sau này bạn cũng cần cập nhật vấn đề:

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

`
``Sau đó tải lại:

`text
/reload-MCP

`

### Giai đoạn 3: thêm máy chủ thứ 2 với chính sách khác

`YAML
MCP_servers:
  GitHub:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/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", "@modelcontextprotocol/server-filesystem", "/home/user/project"]

`
``Bây giờ Hermes có thể kết hợp chúng:

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

`
``Đó là nơi MCP trở nên mạnh mẽ: quy trình làm việc đa hệ thống mà không thay đổi lõi Hermes.

## Khuyến nghị sử dụng an toàn

### Ưu tiên danh sách cho phép dành cho các hệ thống nguy hiểm

Đối với bất cứ điều gì liên quan đến tài chính, hướng tới khách hàng hoặc mang tính phá hoại:

- sử dụng 
`tools.include

- bắt đầu với bộ nhỏ nhất có thể

### Vô hiệu hóa các tiện ích không sử dụng

Nếu bạn không muốn mô hình duyệt tài nguyên/lời nhắc do máy chủ cung cấp, hãy tắt chúng:

``` yaml
tools:
  resources: false
  prompts: false

`

### Giữ máy chủ trong phạm vi hẹp

Ví dụ:

- máy chủ hệ thống tập tin được root vào một thư mục dự án, không phải toàn bộ thư mục chính của bạn
- máy chủ git trỏ vào một repo
- theo mặc định, máy chủ API nội bộ có hiển thị công cụ đọc nặng

### Tải lại sau khi thay đổi cấu hình

``` text
/reload-MCP

`
``Làm điều này sau khi thay đổi:

- bao gồm/loại trừ danh sách
- cờ kích hoạt
- chuyển đổi tài nguyên/lời nhắc
- tiêu đề xác thực/env

## Khắc phục sự cố theo triệu chứng

### "Máy chủ kết nối nhưng thiếu công cụ tôi mong đợi"

Nguyên nhân có thể:
- được lọc bởi 
`tools.include

- bị loại trừ bởi 
`tools.exclude

- trình bao bọc tiện ích bị vô hiệu hóa thông qua 
`resources: false
` hoặc 
`prompts: false

- máy chủ không thực sự hỗ trợ tài nguyên/lời nhắc

### "Máy chủ đã được cấu hình nhưng không tải gì"

Kiểm tra:
- 
`enabled: false
` không còn trong cấu hình
- tồn tại lệnh/thời gian chạy (
`npx

, 
`uvx

, v.v.)
- Điểm cuối HTTP có thể truy cập được
- auth env hoặc tiêu đề đều chính xác

### "Tại sao tôi thấy ít công cụ hơn so với quảng cáo của máy chủ MCP?"

Bởi vì Hermes hiện tôn trọng chính sách trên mỗi máy chủ và đăng ký nhận biết khả năng của bạn. Đó là điều được mong đợi và thường là mong muốn.

### "Làm cách nào để xóa máy chủ MCP mà không xóa cấu hình?"`sử dụng:

``` yaml
enabled: false

`
``Điều đó giữ cấu hình xung quanh nhưng ngăn cản kết nối và đăng ký.

## Khuyến nghị thiết lập MCP đầu tiên

Máy chủ đầu tiên tốt cho hầu hết người dùng:

- hệ thống tập tin
- git
- GitHub
- tìm nạp / tài liệu máy chủ MCP
- một API nội bộ hẹpMáy chủ đầu tiên không tuyệt vời:
- hệ thống kinh doanh khổng lồ với nhiều hành động phá hoại và không có bộ lọc
- bất cứ điều gì bạn không hiểu rõ để hạn chế

## Tài liệu liên quan
- [MCP (Model Context Protocol)](/docs/user-guide/features/MCP)
- [FAQ](/docs/reference/faq)
- [Slash Commands](/docs/reference/slash-commands)