{/* Trang này được tạo tự động từ SKILL.md của kỹ năng bởi website/scripts/generate-skill-docs.py. Chỉnh sửa nguồn SKILL.md, không phải trang này. */}

MCP bản địa

Máy khách MCP: kết nối máy chủ, công cụ đăng ký (stdio/HTTP).

Siêu dữ liệu kỹ năng


Nguồn	Đi kèm (được cài đặt theo mặc định)
Đường dẫn

skills/MCP/native-MCP ` | | Phiên bản |

MCP

, `Tools

, Integrations | | Kỹ năng liên quan | XPROTECTX21XPROTECTX |

Tham khảo: đầy đủ SKILL.md

thông tin

Sau đây là định nghĩa kỹ năng đầy đủ mà Hermes tải khi kỹ năng này được kích hoạt. Đây là những gì tác nhân coi là hướng dẫn khi kỹ năng được kích hoạt.

Máy khách MCP gốc

Đại lý Hermes có ứng dụng khách MCP tích hợp sẵn, kết nối với máy chủ MCP khi khởi động, khám phá các công cụ của họ và cung cấp chúng dưới dạng công cụ hạng nhất mà đại lý có thể gọi trực tiếp. Không cần CLI cầu nối -- các công cụ từ máy chủ MCP xuất hiện cùng với các công cụ tích hợp sẵn như `terminal

, `read_file

, v.v.

Khi nào nên sử dụng

Sử dụng điều này bất cứ khi nào bạn muốn:

Kết nối với máy chủ MCP và sử dụng các công cụ của họ từ bên trong Đại lý Hermes
Thêm các khả năng bên ngoài (truy cập hệ thống tệp, GitHub, cơ sở dữ liệu, API) thông qua MCP
Chạy các máy chủ MCP dựa trên stdio cục bộ (npx, uvx hoặc bất kỳ lệnh nào)
Kết nối với máy chủ MCP HTTP/StreamableHTTP từ xa
Có các công cụ MCP được tự động phát hiện và có sẵn trong mọi cuộc trò chuyện

Đối với các lệnh gọi công cụ MCP đặc biệt, một lần từ terminal mà không cần định cấu hình bất kỳ thứ gì, thay vào đó hãy xem kỹ năng `MCPorter

Điều kiện tiên quyết

gói Python MCP -- phần phụ thuộc tùy chọn; cài đặt với `pip install MCP

. Nếu chưa được cài đặt, hỗ trợ MCP sẽ bị tắt âm thầm.

Node.js -- bắt buộc đối với máy chủ MCP dựa trên npx (hầu hết các máy chủ cộng đồng)
uv -- bắt buộc đối với máy chủ MCP dựa trên uvx (máy chủ dựa trên Python)

Cài đặt SDK MCP:

pip install MCP

# or, if using uv:
uv pip install MCP

`

## Bắt đầu nhanh

Thêm máy chủ MCP vào 

~/.Hermes/config.yaml
` theo khóa 
`MCP_servers

:

``` yaml
MCP_servers:
  time:
    command: "uvx"
    args: ["MCP-server-time"]

`
``Khởi động lại đại lý Hermes. Khi khởi động nó sẽ:

1. Kết nối với máy chủ
2. Khám phá các công cụ có sẵn
3. Đăng ký chúng với tiền tố 
`MCP_time_*

4. Đưa chúng vào tất cả các bộ công cụ nền tảng

Sau đó, bạn có thể sử dụng các công cụ một cách tự nhiên -- chỉ cần yêu cầu nhân viên cung cấp thời gian hiện tại.

## Tham khảo cấu hình

Mỗi mục trong 
`MCP_servers
` là tên máy chủ được ánh xạ tới cấu hình của nó. Có hai loại truyền tải: **stdio** (dựa trên lệnh) và **HTTP** (dựa trên url).

### Stdio Transport (lệnh + args)

``` yaml
MCP_servers:
  server_name:
    command: "npx"             # (required) executable to run
    args: ["-y", "pkg-name"]   # (optional) command arguments, default: []
    env:                       # (optional) environment variables for the subprocess
      SOME_API_KEY: "value"
    timeout: 120               # (optional) per-tool-call timeout in seconds, default: 120
    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60

`

### Truyền tải HTTP (url)

`YAML
MCP_servers:
  server_name:
    url: "https://my-server.example.com/MCP"   # (required) server URL
    headers:                                     # (optional) HTTP headers
      Authorization: "Bearer sk-..."
    timeout: 180               # (optional) per-tool-call timeout in seconds, default: 120
    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60

`

### Tất cả các tùy chọn cấu hình

| Tùy chọn | Loại | Mặc định | Mô tả |
|-------------------|--------|---------|---------------------------------------------------|
| 
`command
` | chuỗi | -- | Có thể thực thi để chạy (bắt buộc phải vận chuyển stdio) |
| 
`args
` | danh sách |

[]
` | Đối số được truyền cho lệnh |
| 
`env
` | chính tả |

\&#123;&#125;
` | Các biến môi trường bổ sung cho quy trình con |
| 
`url
` | chuỗi | -- | URL máy chủ (bắt buộc phải truyền tải HTTP) |
| 
`headers
` | chính tả |

\&#123;&#125;
` | Tiêu đề HTTP được gửi với mọi yêu cầu |
| 
`timeout
` | int |

120
` | Thời gian chờ cho mỗi lệnh gọi công cụ tính bằng giây |
| 
`connect_timeout
` | int |

60
` | Hết thời gian chờ cho kết nối và khám phá ban đầu |

Lưu ý: Cấu hình máy chủ phải có 
`command
` (stdio) hoặc 
`url
` (HTTP), không phải cả hai.

## Nó hoạt động như thế nào`###Khám phá khởi nghiệp

Khi Tác nhân Hermes khởi động, 
`discover_MCP_tools()
` được gọi trong quá trình khởi tạo công cụ:
1. Đọc 
`MCP_servers
` từ 

~/.Hermes/config.yaml

`
2. Đối với mỗi máy chủ, tạo ra một kết nối trong vòng lặp sự kiện nền chuyên dụng
3. Khởi tạo phiên MCP và gọi 
`list_tools()
` để khám phá các công cụ có sẵn
4. Đăng ký từng công cụ trong sổ đăng ký công cụ Hermes

### Quy ước đặt tên công cụ

Các công cụ MCP được đăng ký với mẫu đặt tên:

`
MCP_\&#123;server_name&#125;_\&#123;tool_name&#125;

`
``Dấu gạch ngang và dấu chấm trong tên được thay thế bằng dấu gạch dưới để tương thích với API LLM.Ví dụ:
- Máy chủ 
`filesystem

, công cụ 
`read_file
` → 
`MCP_filesystem_read_file

- Máy chủ 
`GitHub

, công cụ 
`list-issues
` → 
`MCP_GitHub_list_issues

- Máy chủ 
`my-API

, công cụ 
`fetch.data
` → 
`MCP_my_API_fetch_data

### Tự động tiêm

Sau khi phát hiện, các công cụ MCP sẽ tự động được đưa vào tất cả các bộ công cụ nền tảng 
`Hermes-*
` (CLI, Discord, Telegram, v.v.). Điều này có nghĩa là các công cụ MCP có sẵn trong mọi cuộc hội thoại mà không cần bất kỳ cấu hình bổ sung nào.

### Vòng đời kết nối
- Mỗi máy chủ chạy như một Tác vụ asyncio tồn tại lâu dài trong một luồng nền nền
- Các kết nối tồn tại trong suốt thời gian tồn tại của quá trình tác nhân
- Nếu kết nối bị rớt, việc kết nối lại tự động với thời gian chờ theo cấp số nhân sẽ bắt đầu (tối đa 5 lần thử lại, thời gian chờ tối đa là 60 giây)
- Khi tắt tác nhân, tất cả các kết nối đều được đóng lại một cách duyên dáng

### Sự bất lực``discover_MCP_tools()
` là bình thường -- gọi nó nhiều lần chỉ kết nối với các máy chủ chưa được kết nối. Máy chủ bị lỗi sẽ được thử lại trong các cuộc gọi tiếp theo.

## Các loại hình vận chuyển

### Vận chuyển Stdio

Phương tiện di chuyển phổ biến nhất. Hermes khởi chạy máy chủ MCP dưới dạng một quy trình con và liên lạc qua stdin/stdout.

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

`
``Quy trình con kế thừa môi trường **được lọc** (xem phần Bảo mật bên dưới) cộng với bất kỳ biến nào bạn chỉ định trong 
`env

.

### Truyền tải HTTP / StreamableHTTP

Đối với máy chủ MCP từ xa hoặc chia sẻ. Yêu cầu gói 
`MCP
` để bao gồm hỗ trợ máy khách HTTP (
`MCP.CLIent.streamable_http

).

`YAML
MCP_servers:
  remote_API:
    url: "https://MCP.example.com/MCP"
    headers:
      Authorization: "Bearer sk-..."

`
``Nếu hỗ trợ HTTP không có sẵn trong phiên bản 
`MCP
` đã cài đặt của bạn, máy chủ sẽ gặp lỗi với ImportError và các máy chủ khác sẽ tiếp tục bình thường.

## Bảo mật

### Lọc biến môi trường

Đối với máy chủ stdio, Hermes KHÔNG chuyển môi trường shell đầy đủ của bạn sang các quy trình con MCP. Chỉ các biến cơ sở an toàn mới được kế thừa:
- 
`PATH

, 
`HOME

, 
`USER

, 
`LANG

, 
`LC_ALL

, 
`TERM

, 
`SHELL

, 
`TMPDIR

`
- Bất kỳ biến 
`XDG_*
``Tất cả các biến môi trường khác (khóa API, mã thông báo, bí mật) đều bị loại trừ trừ khi bạn thêm chúng một cách rõ ràng thông qua khóa cấu hình 
`env

. Điều này ngăn chặn việc vô tình rò rỉ thông tin xác thực đến các máy chủ MCP không đáng tin cậy.

``` yaml
MCP_servers:
  GitHub:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-GitHub"]
    env:

      # Only this token is passed to the subprocess
      GitHub_PERSONAL_ACCESS_TOKEN: "ghp_..."

`

### Tước thông tin xác thực trong thông báo lỗi

Nếu lệnh gọi công cụ MCP không thành công thì mọi mẫu giống thông tin xác thực trong thông báo lỗi sẽ tự động được loại bỏ trước khi hiển thị cho LLM. Điều này bao gồm:
- GitHub PAT (
`ghp_...

)
- Phím kiểu OpenAI (
`sk-...

)
- Mã thông báo mang
- Các mẫu chung 
`token=

, 
`key=

, 
`API_KEY=

, 
`password=

, 
`secret=

## Khắc phục sự cố

### "MCP SDK không khả dụng -- bỏ qua khám phá công cụ MCP"

Gói Python 
`MCP
` chưa được cài đặt. Cài đặt nó:

``` bash
pip install MCP

`

### "Không có máy chủ MCP nào được định cấu hình"

Không có khóa 
`MCP_servers
` trong 

~/.Hermes/config.yaml
` hoặc khóa này trống. Thêm ít nhất một máy chủ.

### "Không thể kết nối với máy chủ MCP 'X'"

Nguyên nhân phổ biến:

- **Không tìm thấy lệnh**: Tệp nhị phân 
`command
` không có trên PATH. Đảm bảo 
`npx

, 
`uvx
` hoặc lệnh liên quan đã được cài đặt.
- **Không tìm thấy gói**: Đối với máy chủ npx, gói npm có thể không tồn tại hoặc có thể cần 

-y
` trong đối số để tự động cài đặt.
- **Hết thời gian**: Máy chủ mất quá nhiều thời gian để khởi động. Tăng 
`connect_timeout

.
- **Xung đột cổng**: Đối với máy chủ HTTP, URL có thể không truy cập được.

### "Máy chủ MCP 'X' yêu cầu truyền tải HTTP nhưng MCP.CLIent.streamable_http không khả dụng"

Phiên bản gói 
`MCP
` của bạn không bao gồm hỗ trợ ứng dụng khách HTTP. Nâng cấp:

``` bash
pip install --upgrade MCP

`

### Công cụ không xuất hiện
- Kiểm tra xem máy chủ có được liệt kê trong 
`MCP_servers
` (không phải 
`MCP
` hoặc 
`servers

)

- Đảm bảo thụt lề YAML là chính xác
- Xem nhật ký khởi động của Đại lý Hermes để biết thông báo kết nối
- Tên công cụ có tiền tố 
`MCP_\&#123;server&#125;_\&#123;tool&#125;
` -- hãy tìm mẫu đó

### Kết nối liên tục bị rớt

Máy khách thử lại tối đa 5 lần với thời gian chờ theo cấp số nhân (1 giây, 2 giây, 4 giây, 8 giây, 16 giây, giới hạn ở mức 60 giây). Nếu máy chủ về cơ bản là không thể truy cập được, nó sẽ ngừng hoạt động sau 5 lần thử. Kiểm tra quá trình máy chủ và kết nối mạng.

## Ví dụ

### Máy chủ thời gian (uvx)

``` yaml
MCP_servers:
  time:
    command: "uvx"
    args: ["MCP-server-time"]

`
``Đăng ký các công cụ như 
`MCP_time_get_current_time

.

### Máy chủ hệ thống tập tin (npx)

`YAML
MCP_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
    timeout: 30

`
`Đăng ký các công cụ như 
`MCP_filesystem_read_file

, 
`MCP_filesystem_write_file

, 
`MCP_filesystem_list_directory

.

### Máy chủ GitHub có xác thực

`YAML
MCP_servers:
  GitHub:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-GitHub"]
    env:
      GitHub_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
    timeout: 60

`
``Đăng ký các công cụ như 
`MCP_GitHub_list_issues

, 
`MCP_GitHub_create_pull_request

, v.v.

### Máy chủ HTTP từ xa

`YAML
MCP_servers:
  company_API:
    url: "https://MCP.mycompany.com/v1/MCP"
    headers:
      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
      X-Team-Id: "engineering"
    timeout: 180
    connect_timeout: 30

`

### Nhiều máy chủ

`YAML
MCP_servers:
  time:
    command: "uvx"
    args: ["MCP-server-time"]

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

GitHub:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-GitHub"]
    env:
      GitHub_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"`company_API:
    url: "https://MCP.internal.company.com/MCP"
    headers:
      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
    timeout: 300

`
``Tất cả các công cụ từ tất cả các máy chủ đều được đăng ký và khả dụng đồng thời. Các công cụ của mỗi máy chủ đều có tiền tố tên của nó để tránh xung đột.

## Lấy mẫu (Yêu cầu LLM do máy chủ khởi tạo)

Hermes hỗ trợ khả năng 
`sampling/createMessage
` của MCP - máy chủ MCP có thể yêu cầu hoàn thành LLM thông qua tác nhân trong quá trình thực thi công cụ. Điều này cho phép các quy trình làm việc của tác nhân trong vòng lặp (phân tích dữ liệu, tạo nội dung, ra quyết định).

Lấy mẫu được **bật theo mặc định**. Cấu hình mỗi máy chủ:

`YAML
MCP_servers:
  my_server:
    command: "npx"
    args: ["-y", "my-MCP-server"]
    sampling:
      enabled: true           # default: true
      model: "Gemini-3-flash" # model override (optional)
      max_tokens_cap: 4096    # max tokens per request
      timeout: 30             # LLM call timeout (seconds)
      max_rpm: 10             # max requests per minute
      allowed_models: []      # model whitelist (empty = all)
      max_tool_rounds: 5      # tool loop limit (0 = disable)
      log_level: "info"       # audit verbosity

`
``Máy chủ cũng có thể đưa 
`tools
` vào các yêu cầu lấy mẫu cho quy trình công việc được tăng cường công cụ nhiều lượt. Cấu hình 
`max_tool_rounds
` ngăn chặn các vòng lặp công cụ vô hạn. Số liệu kiểm tra trên mỗi máy chủ (yêu cầu, lỗi, mã thông báo, số lần sử dụng công cụ) được theo dõi thông qua 
`get_MCP_status()

.

Vô hiệu hóa việc lấy mẫu đối với các máy chủ không đáng tin cậy bằng 
`sampling: &#123; enabled: false &#125;

.

## Ghi chú
- Các công cụ MCP được gọi một cách đồng bộ theo quan điểm của tác nhân nhưng chạy không đồng bộ trên vòng lặp sự kiện nền chuyên dụng

- Kết quả công cụ được trả về dưới dạng JSON với 

\&#123;"result": "..."&#125;
` hoặc 

\&#123;"error": "..."&#125;

- Ứng dụng khách MCP gốc độc lập với 
`MCPorter
` -- bạn có thể sử dụng đồng thời cả hai
- Kết nối máy chủ liên tục và được chia sẻ trên tất cả các cuộc hội thoại trong cùng một quy trình tác nhân
- Việc thêm hoặc xóa máy chủ yêu cầu khởi động lại tác nhân (hiện tại không tải lại nóng)

Siêu dữ liệu kỹ năng​

Tham khảo: đầy đủ SKILL.md​

Máy khách MCP gốc

Khi nào nên sử dụng​

Điều kiện tiên quyết​

Siêu dữ liệu kỹ năng

Tham khảo: đầy đủ SKILL.md

Khi nào nên sử dụng

Điều kiện tiên quyết