MCP 설정 레퍼런스
기준일: 2026-07-26
난이도: 중급
공식 기준: MCP Config Reference
개요
Hermes MCP 설정의 키, 필터 의미, 유틸 도구 정책, OAuth 레퍼런스입니다.
핵심 개념
| 키/개념 | 의미 |
|---|---|
mcp_servers |
서버 맵 (이름 → 설정) |
| stdio server | command + args + env |
| HTTP/SSE server | URL 기반 전송 |
tools.include / tools.exclude |
도구 필터 |
enabled: false |
서버 비활성 |
| utility tools | resources/prompts 래퍼 |
| name sanitization | 도구 이름 정규화 |
| OAuth 2.1 | 지원 서버 인증 |
상세
Root config shape
mcp_servers:
server_name:
command: "npx"
args: ["-y", "some-mcp-server"]
# 또는 url: "https://..."
env: {}
tools:
include: []
exclude: []
enabled: true
Server keys
- 전송:
command/args또는 URL env,cwd- TLS 클라이언트 인증서 (mTLS)
- 타임아웃·재시도 (버전에 따라)
Filtering semantics
| 정책 | 동작 |
|---|---|
include only |
화이트리스트 |
exclude only |
블랙리스트 |
| 둘 다 | 공식 우선순위(원문 Precedence) 따름 |
| 비어 있음 | 서버 기본 전부 (위험할 수 있음) |
Utility-tool policy
- resources 비활성
- prompts 비활성
- capability-aware registration — 서버 능력에 따라 등록
enabled: false
설정은 남기고 로드만 끔. 임시 차단에 유용.
Empty result behavior
필터 결과가 비면 서버가 “도구 없음”으로 보이거나 경고 — 원문 동작 확인.
Example configs
Safe GitHub allowlist — 읽기 도구만 include
Stripe blacklist — 결제 확정 액션 exclude
Resource-only docs server — tools 최소화, resources 중심
mTLS — 클라이언트 인증서 경로
Reloading
설정 변경 후 세션 재시작 또는 지원되는 reload 명령.
Tool naming
MCP 도구 이름은 Hermes 쪽에서 sanitize되어 충돌·특수문자 문제를 줄입니다.
OAuth 2.1
지원 서버는 브라우저/디바이스 플로우로 토큰 저장. 토큰 파일 권한 보호.
체크리스트
- 필요한 명령/설정만 골라 로컬에서 확인했다
- 시크릿·토큰 env 이름을 문서와 대조했다
- 버전 차이에 대비해 공식 원문도 북마크했다
다음 단계
기준일: 2026-07-26 — 공식 문서 동기화 코퍼스