MCP 구성 참조

이 페이지는 기본 MCP 문서에 대한 간략한 참조 동반자입니다.

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

루트 구성 모양

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

서버 키

열쇠	유형	적용대상	의미
`command`	문자열	스튜디오	실행하여 실행 가능
`args`	목록	스튜디오	하위 프로세스에 대한 인수
`env`	매핑	스튜디오	하위 프로세스에 환경이 전달됨
`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

스트라이프 블랙리스트

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-21-authentication}

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

```yaml
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 기반 서버)에만 적용됩니다.

루트 구성 모양​

서버 키​

tools 정책 키​

필터링 의미론​

include​

exclude​

우선순위​

유틸리티 도구 정책​

리소스 비활성화​

프롬프트 비활성화​

기능 인식 등록​

enabled: false​

빈 결과 동작​

예시 구성​

안전한 GitHub 허용 목록​

스트라이프 블랙리스트​

리소스 전용 문서 서버​

구성 다시 로드 중​

도구 이름 지정​

이름 위생​