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:

• MCP (Giao thức bối cảnh mô hình)
• Sử dụng MCP với Hermes

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
lệnh	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
tiêu đề	lập bản đồ	HTTP	Tiêu đề cho các yêu cầu máy chủ từ xa
đã bật	bool	cả hai	Bỏ qua hoàn toàn máy chủ khi sai
hết giờ	số	cả hai	Hết thời gian gọi công cụ
kết nối_thời gian chờ	số	cả hai	Hết thời gian kết nối ban đầu
công cụ	lập bản đồ	cả hai	Chính sách lọc và công cụ tiện ích
xác thực	chuỗi	HTTP	Phương pháp xác thực. Đặt thành oauth để bật OAuth 2.1 với PKCE
lấy mẫu	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)

Khóa chính sách tools

Chìa khóa	Loại	Ý nghĩa
bao gồm	chuỗi hoặc danh sách	Công cụ MCP gốc của máy chủ trong danh sách trắng
loại trừ	chuỗi hoặc danh sách	Danh sách đen các công cụ MCP gốc của máy chủ
tài nguyên	giống bool	Bật/tắt list_resources + read_resource
lời nhắc	giống bool	Bật/tắt list_prompts + get_prompt

Lọc ngữ nghĩa

bao gồm

Nếu include được đặt, 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]

loại trừ

Nếu loại trừ được đặt và bao gồm 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_resource
• đọc_resource

Lời nhắc:

• list_prompt
• 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 promps: true, Hermes chỉ đăng ký những 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

đã bật: sai

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ình

Sau 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 nối (-) 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ột máy chủ có tên my-api hiển thị một công cụ có tên list-items.v2 trở thành:

mcp_my_api_list_items_v2

Hãy ghi nhớ điều này khi viết các bộ lọc include / exclude — sử dụng tên công cụ MCP gốc (có dấu gạch nối/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 lưu giữ ở ~/.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)