고급 확장: MCP, ACP, API 서버, Web UI

Hermes를 처음 쓸 때는 보통 CLI에서 시작합니다. 터미널에 말을 걸고, 파일을 읽히고, 명령을 실행시키는 흐름이 가장 직접적이기 때문입니다. 그런데 조금만 익숙해지면 이런 생각이 듭니다.

"이걸 터미널 안에만 두기엔 아깝다."

바로 여기서 Hermes의 확장성이 빛납니다. Hermes는 단순한 CLI 프로그램이 아니라, 외부 도구를 붙이고, 에디터 안으로 들어가고, 다른 앱의 백엔드가 되고, 웹 프론트엔드와 연결될 수 있는 에이전트 런타임입니다.¹²³

이 장에서는 네 가지 축을 정리합니다.

• MCP: Hermes가 바깥 도구를 더 많이 쓰게 만드는 확장

• ACP: Hermes를 에디터 안에서 코딩 에이전트처럼 쓰는 방식

• API 서버: Hermes를 OpenAI 호환 백엔드로 노출하는 방식

• Web UI: 브라우저에서 Hermes를 더 쉽게 쓰는 표면

핵심은 기능 이름을 외우는 데 있지 않습니다. Hermes를 하나의 앱이 아니라 기반 시스템으로 보는 관점을 익히는 데 있습니다.

이미지 출처: Hermes Agent Developer Guide: Setup & Self-Improving AI | Lushbinary

먼저 전체 그림부터 보자

비슷해 보이지만 역할은 분명히 다릅니다.

짧게 비유하면 이렇습니다.

• MCP는 Hermes의 손을 늘리는 기술입니다.

• ACP는 Hermes를 IDE 안으로 데려오는 기술입니다.

• API 서버는 Hermes를 다른 앱이 부르는 서버로 만드는 기술입니다.

• Web UI는 그 서버 위에 올리는 창문입니다.

MCP: Hermes가 원래 모르던 도구를 쓰게 만들기

MCP는 Model Context Protocol입니다. 이름은 딱딱하지만, 실전 감각은 의외로 단순합니다. Hermes가 기본 내장 도구만으로는 부족할 때, 외부 도구 서버를 표준 방식으로 연결해 기능 범위를 넓히는 것입니다.¹

예를 들어 이런 상황이 MCP와 잘 맞습니다.

• Google Sheets, Notion, GitHub, 사내 API 같은 외부 서비스 연동

• 공용 브라우저 자동화 서버 연결

• 팀이 함께 쓰는 데이터베이스 또는 검색 계층 연결

• Hermes 기본 도구로는 다루기 어려운 특수 시스템 붙이기

공식 문서는 ~/.hermes/config.yaml의 mcp_servers 아래에 MCP 서버를 선언하는 방식을 안내합니다.¹

예를 들면 이런 식입니다.

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

또는 원격 URL 기반 서버도 가능합니다.

mcp_servers:
  composio:
    url: "https://connect.composio.dev/mcp"
    headers:
      x-consumer-api-key: "YOUR_COMPOSIO_API_KEY"
    connect_timeout: 60
    timeout: 180

여기서 중요한 실전 원칙은 하나입니다.

많이 붙이는 것이 능사가 아닙니다.

초보자일수록 "연결할 수 있다면 다 붙여 두자"는 유혹을 받기 쉽습니다. 하지만 도구가 너무 많아지면 Hermes도 선택 비용이 커지고, 사용자도 무엇을 기대해야 할지 흐려집니다. 실제로는 목적이 분명한 도구 하나를 정확히 붙이는 편이 훨씬 낫습니다.

예를 들어 문서 자동화가 목적이라면 문서 계열 MCP 하나, 브라우저 자동화가 목적이라면 브라우저 계열 MCP 하나로 시작하는 편이 좋습니다.

또 하나 기억할 점이 있습니다. 기본 도구로 충분한데 굳이 MCP를 추가할 필요는 없습니다. 확장은 필요할 때만 붙여야 빛납니다. Hermes는 도구가 많아서 좋은 것이 아니라, 필요한 도구를 상황에 맞게 쓸 수 있어서 좋은 시스템입니다.

ACP: Hermes를 에디터 안에서 쓰는 가장 자연스러운 방법

ACP는 Agent Client Protocol입니다. MCP가 Hermes의 손을 늘린다면, ACP는 Hermes의 자리를 바꿉니다. CLI 바깥, 즉 에디터 안으로 들어가게 만드는 것이죠.²

공식 문서 기준으로 Hermes는 ACP 서버로 실행될 수 있고, ACP 호환 에디터는 이를 통해 다음 같은 정보를 자연스럽게 UI에 렌더링할 수 있습니다.²

• 채팅 메시지

• 도구 활동

• 파일 diff

• 터미널 명령

• 승인 프롬프트

• 스트리밍 응답

즉, ACP는 Hermes를 "독립 실행형 CLI"가 아니라 에디터 네이티브 코딩 에이전트처럼 느끼게 만듭니다.

ACP에서 Hermes가 제공하는 것

공식 문서에 따르면 ACP 모드의 Hermes는 hermes-acp라는 큐레이션된 도구셋을 사용합니다.²

포함되는 대표 도구는 다음과 같습니다.

• 파일 도구: read_file, write_file, patch, search_files

• 터미널 도구: terminal, process

• 웹/브라우저 도구

• 메모리, 세션 검색, 스킬

• execute_code, delegate_task

• 비전

반대로 에디터 UX와 잘 맞지 않는 것, 예를 들어 메시징 전달이나 cron 관리 같은 기능은 일부러 제외됩니다.²

이 구성이 꽤 합리적입니다. 코딩 에이전트로 쓰는 동안 굳이 Slack 전달이나 스케줄링 관리가 에디터 안에 바로 노출될 필요는 없기 때문입니다.

ACP 설치와 실행

ACP는 일반 설치 위에 extra를 추가하는 방식입니다.²

pip install -e '.[acp]'

실행은 셋 중 아무 방식이나 가능합니다.

hermes acp

hermes-acp

python -m acp_adapter

여기서 알아둘 점은, ACP는 별도 설정 체계를 만들지 않습니다. CLI와 같은 설정을 그대로 사용합니다.²

• ~/.hermes/.env

• ~/.hermes/config.yaml

• ~/.hermes/skills/

• ~/.hermes/state.db

즉, CLI에서 이미 모델과 인증을 다 맞춰 두었다면 ACP에서도 그대로 이어집니다. 이 점이 꽤 편합니다. 도구를 바꾸는 것이지, 에이전트를 새로 만드는 것이 아니기 때문입니다.

VS Code, Zed, JetBrains 연결 감각

공식 문서가 보여 주는 연결 흐름은 단순합니다.²

VS Code

ACP 클라이언트 확장을 설치한 뒤, acp_registry/ 경로를 가리키게 설정합니다.

{
  "acpClient.agents": [
    {
      "name": "hermes-agent",
      "registryDir": "/path/to/hermes-agent/acp_registry"
    }
  ]
}

Zed

{
  "agent_servers": {
    "hermes-agent": {
      "type": "custom",
      "command": "hermes",
      "args": ["acp"]
    }
  }
}

JetBrains

ACP 호환 플러그인에서 acp_registry/agent.json이 있는 레지스트리 경로를 잡아 주는 방식으로 이해하면 됩니다.²

실전에서는 "에디터에 안 보인다"는 문제가 자주 나오는데, 대부분은 세 가지입니다.²

• acp_registry/ 경로를 잘못 가리킴

• Hermes가 PATH에 없음

• ACP extra 설치를 안 함

즉, ACP 문제는 대개 기능보다 경로와 설치 상태에서 먼저 찾는 편이 맞습니다.

ACP 승인 흐름은 더 단순하지만, 더 가볍게 보면 안 된다

ACP 모드에서도 위험한 터미널 명령은 승인 대상으로 올라올 수 있습니다. 공식 문서 기준으로 에디터 쪽 승인 옵션은 대체로 다음 셋입니다.²

• allow once

• allow always

• deny

여기서 타임아웃이나 오류가 나면 거부로 처리됩니다. 이건 꽤 좋은 기본값입니다. 편집기가 예뻐졌다고 해서 Hermes가 만지는 대상이 가벼워지는 것은 아니기 때문입니다. 여전히 실제 파일과 실제 셸입니다.

즉, ACP는 CLI보다 편한 표면일 뿐, 보안 감각까지 자동으로 대신해 주지는 않습니다.

API 서버: Hermes를 다른 앱이 부르는 두뇌로 만들기

이제 시점을 바꿔 보겠습니다. 지금까지는 "내가 Hermes를 어디서 쓰나?"가 중심이었다면, API 서버는 "다른 앱이 Hermes를 어떻게 부르나?"가 중심입니다.

공식 문서 기준으로 Hermes의 API 서버는 OpenAI 호환 HTTP 엔드포인트를 제공합니다.³ 그래서 Open WebUI, LobeChat, LibreChat, NextChat, ChatBox 같은 프론트엔드가 Hermes를 OpenAI 백엔드처럼 연결할 수 있습니다.

쉽게 말해, Hermes를 호환 가능한 서버 역할로 바꾸는 기능입니다.

API 서버 빠른 시작

설정은 현재 공식 기준으로 환경 변수에서 합니다. 이 부분이 중요합니다. 아직 config.yaml로 API 서버를 설정하는 방식은 공식적으로 지원되지 않습니다.³

~/.hermes/.env에 이렇게 넣습니다.

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev

그다음 게이트웨이를 실행합니다.

hermes gateway

정상적으로 뜨면 이런 메시지를 보게 됩니다.³

[API Server] API server listening on http://127.0.0.1:8642

이 점도 실전에서 자주 헷갈립니다. API 서버는 별도 독립 앱이라기보다, 게이트웨이 프로세스와 함께 뜨는 구성으로 이해하는 편이 정확합니다.

두 가지 핵심 엔드포인트

1. POST /v1/chat/completions

가장 익숙한 OpenAI Chat Completions 형식입니다. 무상태 방식이므로, 대화 전체를 요청마다 messages 배열에 넣어 보내야 합니다.³

curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer change-me-local-dev" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hermes-agent",
    "messages": [
      {"role": "user", "content": "현재 프로젝트 파일을 요약해줘"}
    ]
  }'

2. POST /v1/responses

Responses API 형식입니다. previous_response_id를 통해 서버 쪽 대화 상태를 이어 갈 수 있습니다.³

즉, 클라이언트가 매번 전체 대화를 다 들고 다니지 않아도, Hermes 쪽이 도구 호출과 결과를 포함한 체인을 저장해 둘 수 있습니다.

이 차이는 꽤 실용적입니다. 단순 채팅 프론트엔드라면 Chat Completions로도 충분하지만, 더 에이전트다운 상태 보존이 필요하면 Responses API가 어울립니다.

시스템 프롬프트는 덮어쓰는 게 아니라 얹힌다

이 부분은 Hermes API 서버의 중요한 특징입니다. 프론트엔드가 system 메시지나 instructions를 보내도, Hermes는 그것을 자기 핵심 시스템 프롬프트 위에 얹는 방식으로 처리합니다.³

즉, 프론트엔드에서 "당신은 파이썬 전문가처럼 답하라" 같은 지시를 보내더라도 Hermes의 도구, 메모리, 스킬 구조는 그대로 유지됩니다.

이 덕분에 각 프론트엔드마다 약간 다른 말투나 역할을 주면서도, 같은 Hermes 인스턴스를 공유할 수 있습니다.

API 서버 보안: 정말 중요하다

이건 조금 진지하게 봐야 합니다. 공식 문서도 강하게 경고합니다. API 서버는 단순 텍스트 채팅 백엔드가 아니라, Hermes의 전체 도구셋에 접근하는 창구입니다.³

즉, 여기에 연결된 프론트엔드는 경우에 따라 다음까지 건드릴 수 있습니다.

• 터미널

• 파일 조작

• 웹 검색

• 메모리

• 스킬

그래서 기본 바인드 주소가 127.0.0.1인 것은 아주 의도적입니다.³

실전 원칙은 이렇게 정리하면 됩니다.

• 가능하면 로컬에서만 열어 둔다

• 외부에 열어야 한다면 강한 API_SERVER_KEY를 쓴다

• 0.0.0.0으로 열 때는 방화벽과 리버스 프록시를 함께 둔다

• 브라우저 직접 호출이 꼭 필요할 때만 API_SERVER_CORS_ORIGINS를 좁게 연다

특히 Open WebUI 연동처럼 서버-대-서버 연결이라면, 보통 CORS를 열 필요가 없습니다.³⁴

Open WebUI: 가장 대중적인 웹 프론트엔드

Web UI 쪽에서 공식적으로 가장 선명한 조합은 Hermes API 서버 + Open WebUI입니다.³⁴

Open WebUI는 가장 널리 쓰이는 셀프호스트형 AI 채팅 프론트엔드 가운데 하나이고, Hermes는 그 뒤에서 실제 에이전트 역할을 맡습니다.

아키텍처는 단순합니다.

• Open WebUI가 OpenAI 호환 요청을 보냄

• Hermes API 서버가 받음

• Hermes가 도구를 쓰고 작업을 수행함

• 최종 응답과 진행 표시를 Open WebUI로 돌려줌

즉, Open WebUI는 화면, Hermes는 실제 두뇌와 손발입니다.

Open WebUI 연결 예시

공식 가이드와 Open WebUI 연동 문서는 대체로 이런 식을 안내합니다.⁴⁵

docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
  -e OPENAI_API_KEY=your-secret-key \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

이후 http://localhost:3000에 접속하면 모델 목록에서 보통 현재 Hermes 프로필 이름, 또는 기본 프로필이면 hermes-agent를 볼 수 있습니다.³⁴

실전에서 가장 자주 틀리는 부분도 명확합니다.

URL 끝의 /v1를 빼먹는 것입니다.⁴⁵

연결 테스트는 통과했는데 모델이 안 보인다면, 가장 먼저 이 부분부터 의심하는 편이 좋습니다.

Open WebUI와 Hermes의 역할 분담

Open WebUI를 붙이면 좋아지는 점은 단순히 "브라우저에서도 된다"가 아닙니다.

• 대화 목록 관리가 쉬워진다

• 사용자 계정과 권한 관리가 쉬워진다

• 비기술 사용자에게 데모하기 편해진다

• 팀원에게 넘기기 쉬운 표면이 생긴다

반면 중요한 점도 있습니다. Hermes의 도구 사용과 상태 관리는 여전히 Hermes 쪽 책임입니다. Open WebUI는 프론트엔드일 뿐, 에이전트의 성격 자체를 바꾸는 것은 아닙니다.

즉, Web UI가 예뻐졌다고 해서 Hermes가 가벼운 챗봇이 되는 것은 아닙니다. 여전히 실제 일을 하는 에이전트입니다.

"Web UI"를 이해하는 현실적인 방법

여기서 독자가 가장 헷갈리기 쉬운 지점이 있습니다. "Hermes 전용 웹 UI가 공식으로 따로 있나?"라는 질문입니다.

이 장에서는 안전하게 이렇게 이해하는 편이 좋습니다.

1. 공식적으로 가장 분명한 웹 접근 방식은 API 서버 + Open WebUI 조합입니다.³⁴

2. 그 밖에 커뮤니티가 만든 별도 Hermes Web UI 프로젝트들이 존재합니다.⁶

3. 하지만 커뮤니티 Web UI는 품질과 유지보수 상태가 제각각이므로, 실전에서는 먼저 Open WebUI 조합부터 익히는 편이 안정적입니다.

즉, "Web UI"는 하나의 단일 제품명이라기보다, Hermes를 브라우저에서 다루는 여러 표면의 묶음으로 보는 것이 현실적입니다.

언제 무엇을 고르면 좋을까

이제 조합 관점으로 정리해 보겠습니다.

여기서 중요한 건 "하나만 골라야 한다"가 아니라, 서로 다른 층을 조합하는 것입니다.

예를 들어 이런 구성이 가능합니다.

• 코딩할 때는 VS Code에서 ACP 사용

• 웹에서는 Open WebUI로 대화 기록 확인

• 문서/외부 서비스는 MCP로 연결

• 팀별 인스턴스는 프로필로 분리

이렇게 되면 Hermes는 정말로 "CLI 앱 하나"가 아니라 여러 표면을 가진 개인용 에이전트 플랫폼처럼 느껴집니다.

자주 막히는 지점

고급 확장에서는 기능보다 경로와 연결점이 더 자주 문제를 만듭니다. 특히 아래 네 가지를 먼저 점검하면 좋습니다.

• ACP가 안 보이면 acp_registry/ 경로와 ACP extra 설치 여부 확인²

• API 서버가 안 붙으면 게이트웨이 실행 여부와 API_SERVER_ENABLED=true 확인³

• Open WebUI에서 모델이 안 보이면 URL 끝의 /v1 확인⁴⁵

• MCP가 조용히 실패하면 인증 헤더, 환경변수, 타임아웃 확인¹

기본 진단 명령도 여전히 유효합니다.

hermes doctor
hermes status

로그를 보고 싶다면 공식 명령은 hermes logs입니다.

hermes logs
hermes logs gateway -n 100

즉, 고급 확장은 신비한 마법이라기보다, 연결 구조를 잘 이해한 사람에게 더 큰 자유를 주는 레이어라고 보는 편이 맞습니다.

마무리

이 장의 핵심은 기능 이름을 외우는 데 있지 않습니다. Hermes를 바라보는 관점을 넓히는 데 있습니다.

CLI만 보면 Hermes는 훌륭한 터미널 에이전트입니다. 하지만 MCP를 붙이면 외부 도구를 쓰는 시스템이 되고, ACP를 붙이면 에디터 안의 코딩 에이전트가 되며, API 서버를 열면 다른 앱이 부르는 백엔드가 되고, Open WebUI를 붙이면 브라우저에서 접근 가능한 작업 표면이 됩니다.¹²³⁴

즉, CLI는 시작점일 뿐입니다.

Hermes의 진짜 확장성은, 같은 에이전트를 여러 도구와 화면과 워크플로 속으로 자연스럽게 연결할 수 있다는 데 있습니다.

참고

¹AI Providers | Hermes Agent

²ACP Editor Integration | Hermes Agent

³API Server | Hermes Agent

⁴Open WebUI | Hermes Agent

⁵Hermes Agent / Open WebUI

⁶GitHub - nesquena/hermes-webui