MCP 설정 참조

이 페이지는 기본 MCP 문서와 함께 보는 간단한 참조 문서입니다.

개념적 지침은 다음을 참조하세요.

• MCP(모델 컨텍스트 프로토콜)
• Hermes와 함께 MCP 사용

루트 설정 형태

mcp_servers:
  <server_name>:
    command: "..."      # stdio 서버
    args: 
    env: {}

    # OR
    url: "..."          # HTTP 서버
    headers: {}

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

서버 키

키	유형	적용 대상	의미
command	문자열	stdio	실행할 프로그램
args	목록	stdio	하위 프로세스에 전달할 인수
env	매핑	stdio	하위 프로세스에 전달할 환경 변수
url	문자열	HTTP	원격 MCP 엔드포인트
headers	매핑	HTTP	원격 서버 요청에 대한 헤더
enabled	부울	둘 다	false인 경우 서버를 완전히 건너뜁니다.
timeout	숫자	둘 다	도구 호출 제한 시간
connect_timeout	숫자	둘 다	초기 연결 제한 시간
tools	매핑	둘 다	필터링 및 유틸리티 도구 정책
auth	문자열	HTTP	인증 방법. PKCE 기반 OAuth 2.1을 활성화하려면 oauth로 설정하세요.
sampling	매핑	둘 다	서버가 시작하는 LLM 요청 정책(MCP 가이드 참조)

tools 정책 키

키	유형	의미
include	문자열 또는 목록	허용할 서버 기반 MCP 도구 목록
exclude	문자열 또는 목록	제외할 서버 기반 MCP 도구 목록
resources	부울형	list_resources + read_resource 활성화/비활성화
prompts	부울형	list_prompts + get_prompt 활성화/비활성화

필터링 의미

include

include가 설정된 경우 해당 서버 기반 MCP 도구만 등록됩니다.

tools:
  include: [create_issue, list_issues]

exclude

exclude가 설정되고 include가 설정되지 않은 경우 해당 이름을 제외한 모든 서버 기반 MCP 도구가 등록됩니다.

tools:
  exclude: [delete_customer]

우선순위

둘 다 설정되면 include가 우선합니다.

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

결과:

• create_issue는 계속 허용됩니다.
• delete_issue는 include가 우선 적용되므로 무시됩니다.

유틸리티 도구 정책

Hermes는 MCP 서버별로 다음과 같은 유틸리티 래퍼를 등록할 수 있습니다.

리소스:

• list_resources
• read_resource

프롬프트:

• list_prompts
• get_prompt

리소스 비활성화

tools:
  resources: false

프롬프트 비활성화

tools:
  prompts: false

기능 인식 등록

resources: true 또는 prompts: true인 경우에도 Hermes는 MCP 세션이 실제로 해당 기능을 노출하는 경우에만 해당 유틸리티 도구를 등록합니다.

따라서 다음과 같은 상황은 정상입니다.

• 프롬프트를 활성화했습니다.
• 하지만 프롬프트 유틸리티가 나타나지 않습니다.
• 서버가 프롬프트를 지원하지 않기 때문입니다.

enabled: false

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

동작:

• 연결 시도 없음
• 검색 없음
• 도구 등록 없음
• 나중에 다시 사용할 수 있도록 설정은 그대로 유지됩니다.

빈 결과 동작

필터링으로 인해 모든 서버 기반 도구가 제거되고 유틸리티 도구가 등록되지 않은 경우 Hermes는 해당 서버에 대해 빈 MCP 런타임 툴셋을 생성하지 않습니다.

예시 구성

안전한 GitHub 허용 목록

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

Stripe 차단 목록

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

리소스 전용 문서 서버

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

설정 다시 로드

MCP 설정을 변경한 후 다음을 사용하여 서버를 다시 로드합니다.

/reload-mcp

도구 이름 지정

서버 기반 MCP 도구는 다음과 같습니다.

mcp_<server>_<tool>

예:

• mcp_github_create_issue
• mcp_filesystem_read_file
• mcp_my_api_query_data

유틸리티 도구도 동일한 접두사 패턴을 따릅니다.

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

이름 위생

등록 전에는 서버 이름과 도구 이름 모두의 하이픈(-)과 점(.)이 밑줄로 대체됩니다. 이렇게 하면 도구 이름이 LLM 함수 호출 API에서 유효한 식별자가 됩니다.

예를 들어 list-items.v2라는 도구를 노출하는 my-api 서버는 다음과 같은 이름으로 등록됩니다.

mcp_my_api_list_items_v2

include / exclude 필터를 작성할 때 이 점을 명심하세요. 정리된 이름이 아니라 원래 MCP 도구 이름(하이픈/점 포함)을 사용하세요.

OAuth 2.1 인증

OAuth가 필요한 HTTP 서버의 경우 서버 항목에 auth: oauth를 설정합니다.

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

동작:

• Hermes는 MCP SDK의 OAuth 2.1 PKCE 흐름(메타데이터 검색, 동적 클라이언트 등록, 토큰 교환 및 새로 고침)을 사용합니다.
• 처음 연결하면 인증을 위해 브라우저 창이 열립니다.
• 토큰은 ~/.hermes/mcp-tokens/<server>.json에 유지되며 세션 전체에서 재사용됩니다.
• 토큰 새로 고침은 자동으로 수행됩니다. 재승인은 새로 고침이 실패한 경우에만 발생합니다.
• HTTP/StreamableHTTP 전송(url 기반 서버)에만 적용됩니다.