Hermes Agent MCP 서버: config.yaml에 Sume 추가

Hermes Agent에 MCP 서버를 추가하려면 ~/.hermes/config.yaml의 mcp_servers 아래에 항목을 넣으세요. 로컬 서버라면 command와 args를, 원격 서버라면 url과 headers를 씁니다. Sume 호스팅 MCP 서버라면 url: "https://mcp.sume.com/mcp"에 Sume API 키를 담은 Authorization 헤더를 넣거나, 대신 auth: oauth로 브라우저에서 로그인합니다. Hermes는 시작할 때 서버를 찾으며, 세션 도중의 변경은 /reload-mcp로 반영합니다.

Hermes 쪽 내용은 MCP 가이드와 MCP 설정 레퍼런스에서, Sume 쪽 내용은 MCP OAuth와 API 키, MCP 도구와 게이트, Job과 결과 (영문)에서 가져왔으며, 모두 2026-09-28에 확인했습니다. Sume에는 Hermes Agent 전용 연동이 없습니다. Hermes는 다른 원격 MCP 서버와 똑같이 Sume 원격 MCP 서버에 연결하며, Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명합니다. Hermes는 hermes mcp serve로 직접 MCP 서버 역할도 할 수 있는데, 현재는 stdio 전용 서버입니다. 이 글은 클라이언트 쪽을 다룹니다.

config.yaml에 Sume를 어떻게 추가하나요?

서버 항목 안의 문자열 값은 headers를 포함해 어디서든 ${VAR} 형태로 환경 변수를 참조할 수 있습니다. 이 참조는 활성 프로필의 시크릿 스코프에서 값을 찾고, 없으면 프로세스 환경으로 넘어가므로, SUME_API_KEY는 ~/.hermes/.env에 넣고 키를 YAML 밖에 두세요. 설정되지 않은 변수는 플레이스홀더가 글자 그대로 남습니다.

아래 항목을 저장한 뒤 /reload-mcp를 실행하고, 이어서 서버가 실제로 무엇을 응답했는지 알려 주는 hermes mcp test sume를 실행하세요. 401이나 403은 토큰이나 OAuth 권한 부여가 잘못됐다는 뜻입니다. 그다음 Hermes에게 Sume의 읽기 전용 탐색 도구인 mcp_health와 tools_list를 호출해 달라고 하세요. 다음 섹션에서 설명하듯, 이 항목은 도구도 제한하고 유료 호출은 먼저 묻게 합니다.

mcp_servers:
  sume:
    url: "https://mcp.sume.com/mcp"
    headers:
      Authorization: "Bearer ${SUME_API_KEY}"
    trust: untrusted
    tools:
      include: [mcp_health, tools_list, tools_schema, generate_image, jobs_wait, jobs_result]

API 키와 OAuth 중 무엇을 써야 하나요?

Hermes 문서에 나온 옵션으로는 둘 다 됩니다. headers를 auth: oauth로 바꾸면 Hermes는 MCP SDK의 OAuth 2.1 PKCE 플로를 실행하며, 메타데이터 디스커버리, 클라이언트 식별, 토큰 교환, 갱신까지 처리합니다. Hermes가 Client ID Metadata Document로 자신을 식별하는 것은 서버가 client_id_metadata_document_supported: true를 알릴 때뿐입니다. 현재 Sume 메타데이터는 이 값을 알리지 않고 등록 엔드포인트는 알리므로, Hermes는 동적 클라이언트 등록으로 등록합니다. 첫 로그인은 새 터미널에서 hermes mcp login sume로 실행하세요. 실행 중인 세션 안에서 한 편집은 30초 타임아웃으로 다시 로드되는데, 인터랙티브 플로에는 너무 짧습니다. 반면 hermes mcp login은 5분을 다 기다립니다. Sume 동의 화면에서 Read는 고정 켜짐, Write는 기본 꺼짐이므로, Hermes가 생성까지 해야 한다면 Write를 켜세요.

다만 지금 Sume에서 OAuth를 쓰면 걸리는 점이 있습니다. 현재 코드에서 Sume 토큰은 한 시간 동안 유효하고 Sume는 리프레시 토큰을 발급하지 않으므로, Hermes의 자동 갱신이 쓸 수 있는 것이 없습니다. 대략 한 시간마다 hermes mcp login sume로 다시 로그인해야 한다고 생각하세요. 게이트웨이와 /reload-mcp는 브라우저를 열지 않습니다. 아무도 지켜보지 않는 게이트웨이에는 API 키 헤더가 현실적인 선택입니다. API 키 세션에는 Sume의 전체 호스팅 도구 세트가 보이며, 위 항목이 도구를 좁히는 이유도 이것입니다.

유료 Sume 도구가 실행되기 전에 Hermes가 확인을 요청하나요?

네, 서버를 untrusted로 표시하면 그렇습니다. trust의 기본값은 full입니다. trust: untrusted로 두면 쓰기가 가능한 모든 도구 호출, 즉 readOnlyHint: true 어노테이션이 없는 도구의 호출은 실행 전에 Hermes 승인 인터페이스에서 여러분의 승인을 받아야 합니다. 현재 Sume 서버는 읽기 도구를 readOnlyHint: true로, 쓰기·유료 도구를 false로 표시하므로, jobs_wait와 jobs_result는 묻지 않고 실행되고 generate_image 호출은 매번 여러분을 기다립니다. 이 힌트는 MCP 도구 어노테이션에서 설명합니다.

• tools.include는 목록에 적은 Sume 도구만 등록하며, 정확한 이름이나 glob으로 적습니다. include와 exclude를 둘 다 설정하면 include가 우선합니다. 원래의 MCP 도구 이름을 쓰세요.
• Sume 유료 도구는 호출할 때마다 idempotency_key가 필요합니다. dry_run=true는 제출하지 않고 접수 여부와 비용을 미리 보여 주며, max_spend_usd는 값을 보낸 경우에만 호출의 상한이 됩니다.

긴 Sume Job도 Hermes 타임아웃 안에 들어오나요?

네, 기본값으로 들어옵니다. timeout은 초 단위 도구 호출 타임아웃이며 기본값은 300이고, Sume의 jobs_wait는 호출 한 번을 최대 55초 동안 붙잡습니다. 렌더링이 그보다 길면 에이전트는 같은 id로 jobs_wait를 다시 호출해야 하며, 유료 create는 절대 다시 제출하면 안 됩니다. Hermes는 세션이 리소스와 프롬프트를 지원할 때만 해당 헬퍼를 등록합니다. 현재 Sume 서버는 도구만 선언하므로 이 헬퍼는 나타나지 않습니다.