Tham khảo cấu hình MCP

Trang này là tài liệu tham khảo nhỏ gọn đi kèm với các tài liệu MCP chính.

Để biết hướng dẫn về khái niệm, hãy xem:

Hình dạng cấu hình gốc

mcp_servers:
  <server_name>:
    command: "..."      

# stdio servers
    args: []
    env: {}

    

# OR
    url: "..."          

# HTTP servers
    headers: {}

    enabled: true
    timeout: 120
    connect_timeout: 60
    tools:
      include: []
      exclude: []
      resources: true
      prompts: true

Khóa máy chủ

Chìa khóa	Loại	Áp dụng cho	Ý nghĩa
`command`	chuỗi	stdio	Có thể thực thi để khởi chạy
`args`	danh sách	stdio	Đối số cho quy trình con
`env`	lập bản đồ	stdio	Môi trường được truyền cho quy trình con
`url`	chuỗi	HTTP	Điểm cuối MCP từ xa
`headers`	lập bản đồ	HTTP	Tiêu đề cho các yêu cầu máy chủ từ xa
`enabled`	bool	cả hai	Bỏ qua hoàn toàn máy chủ khi sai
`timeout`	số	cả hai	Hết thời gian gọi công cụ
`connect_timeout`	số	cả hai	Hết thời gian kết nối ban đầu
`tools`	lập bản đồ	cả hai	Chính sách lọc và công cụ tiện ích
`auth`	chuỗi	HTTP	Phương pháp xác thực. Đặt thành `oauth` để bật OAuth 2.1 với PKCE
`sampling`	lập bản đồ	cả hai	Chính sách yêu cầu LLM do máy chủ khởi tạo (xem hướng dẫn MCP)

`tools` khóa chính sách

Chìa khóa	Loại	Ý nghĩa
`include`	chuỗi hoặc danh sách	Công cụ MCP gốc của máy chủ trong danh sách trắng
`exclude`	chuỗi hoặc danh sách	Danh sách đen các công cụ MCP gốc của máy chủ
`resources`	giống bool	Bật/tắt `list_resources` + `read_resource`
`prompts`	giống bool	Bật/tắt `list_prompts` + `get_prompt`

Lọc ngữ nghĩa

`include`

Nếu include được đặt thì chỉ những công cụ MCP gốc của máy chủ đó mới được đăng ký.

tools:
  include: [create_issue, list_issues]

`exclude`

Nếu exclude được đặt và include không được đặt thì mọi công cụ MCP gốc của máy chủ ngoại trừ những tên đó đều được đăng ký.

tools:
  exclude: [delete_customer]

Quyền ưu tiên

Nếu cả hai đều được đặt, include sẽ thắng.

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

Kết quả:

create_issue vẫn được phép
delete_issue bị bỏ qua vì include được ưu tiên

Chính sách công cụ tiện ích

Hermes có thể đăng ký các trình bao bọc tiện ích này trên mỗi máy chủ MCP:

Tài nguyên:

list_resources
read_resource

Lời nhắc:

list_prompts
get_prompt

Tắt tài nguyên

tools:
  resources: false

Tắt lời nhắc

tools:
  prompts: false

Đăng ký nhận biết khả năng

Ngay cả khi resources: true hoặc prompts: true , Hermes chỉ đăng ký các công cụ tiện ích đó nếu phiên MCP thực sự bộc lộ khả năng tương ứng.

Vì vậy, điều này là bình thường:

bạn kích hoạt lời nhắc
nhưng không có tiện ích nhắc nhở nào xuất hiện
vì máy chủ không hỗ trợ lời nhắc

`enabled: false`

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

Hành vi:

không có nỗ lực kết nối
không có sự khám phá
không đăng ký công cụ
config vẫn được giữ nguyên để sử dụng lại sau này

Hành vi kết quả trống

Nếu quá trình lọc loại bỏ tất cả các công cụ gốc của máy chủ và không có công cụ tiện ích nào được đăng ký, Hermes sẽ không tạo bộ công cụ thời gian chạy MCP trống cho máy chủ đó.

Cấu hình ví dụ

Danh sách cho phép GitHub an toàn

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]
      resources: false
      prompts: false

Danh sách đen sọc

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

Máy chủ tài liệu chỉ có tài nguyên

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      include: []
      resources: true
      prompts: false

Đang tải lại cấu hìnhSau khi thay đổi cấu hình MCP, hãy tải lại máy chủ bằng:

/reload-mcp

Đặt tên công cụ

Các công cụ MCP gốc của máy chủ trở thành:

mcp_<server>_<tool>

Ví dụ:

mcp_github_create_issue
mcp_filesystem_read_file
mcp_my_api_query_data

Các công cụ tiện ích tuân theo cùng một mẫu tiền tố:

mcp_<server>_list_resources
mcp_<server>_read_resource
mcp_<server>_list_prompts
mcp_<server>_get_prompt

Khử trùng tên

Dấu gạch ngang ( - ) và dấu chấm ( . ) trong cả tên máy chủ và tên công cụ đều được thay thế bằng dấu gạch dưới trước khi đăng ký. Điều này đảm bảo tên công cụ là số nhận dạng hợp lệ cho API gọi hàm LLM.

Ví dụ: máy chủ có tên my-api hiển thị công cụ có tên list-items.v2 sẽ trở thành:

mcp_my_api_list_items_v2

Hãy ghi nhớ điều này khi viết bộ lọc include / exclude — sử dụng tên công cụ MCP gốc (có dấu gạch ngang/dấu chấm), chứ không phải phiên bản đã được chọn lọc.

Xác thực OAuth 2.1

Đối với các máy chủ HTTP yêu cầu OAuth, hãy đặt auth: oauth trên mục nhập máy chủ:

mcp_servers:
  protected_api:
    url: "https://mcp.example.com/mcp"
    auth: oauth

Hành vi:

Hermes sử dụng luồng PKCE OAuth 2.1 của MCP SDK (khám phá siêu dữ liệu, đăng ký ứng dụng khách động, trao đổi mã thông báo và làm mới)
Trong lần kết nối đầu tiên, một cửa sổ trình duyệt sẽ mở ra để ủy quyền
Mã thông báo được duy trì ở ~/.hermes/mcp-tokens/<server>.json và được sử dụng lại trong các phiên
Làm mới mã thông báo là tự động; ủy quyền lại chỉ xảy ra khi làm mới không thành công
Chỉ áp dụng cho truyền tải HTTP/StreamableHTTP (máy chủ dựa trên url)

Hình dạng cấu hình gốc

Khóa máy chủ

tools khóa chính sách

Lọc ngữ nghĩa

include​

exclude​

Quyền ưu tiên​

Chính sách công cụ tiện ích

Tắt tài nguyên​

Tắt lời nhắc​

Đăng ký nhận biết khả năng​

enabled: false