콘텐츠로 이동

MCP 서버

BombVault에는 Model Context Protocol(MCP) 서버가 내장되어 있습니다. MCP는 Claude Code와 Claude Desktop 같은 AI 어시스턴트가 외부 도구에 접근할 때 쓰는 프로토콜입니다. 이를 통해 어시스턴트는 백업 상태를 읽을 수 있고, 허용하면 백업을 시작하거나 자신이 시작한 백업을 취소할 수 있습니다. 키를 만들거나 OAuth 로그인을 켜기 전까지는 꺼져 있으며, 그동안 엔드포인트 /mcp는 모든 요청에 404로 응답합니다.

어시스턴트가 할 수 있는 일과 없는 일

도구 하는 일 종류
get_health 버전, 인스턴스 이름, 백업이 실행 중인지, 이 키에 허용된 것 읽기
get_status 도메인별 보호 상태: 마지막 성공 백업, 예상 간격, 검증과 오프사이트 점검, 다음 예약 실행, 앱의 유휴 상태를 기다리는 백업. 컨테이너에는 최신 시작 테스트도 포함 읽기
get_coverage BombVault가 보호하는 것과 보호하지 않는 것, 각각의 이유 읽기
list_items 보호되는 모든 컨테이너, VM, 폴더 세트, 플래시 드라이브, 앱 설정. 일정, 백업 시 멈추는 것, 마지막 백업과 걸린 시간 포함. 데이터베이스 컨테이너는 마지막 덤프도 보여 줍니다. ZFS 데이터 세트도 마지막 점검 결과와 함께 보여 줍니다. 각 항목에는 마지막 복원 검사가, 컨테이너에는 마지막 시작 테스트 또는 테스트할 수 없는 이유가 함께 표시됩니다. 마지막 백업 이후 다른 설정으로 다시 만들어진 컨테이너는 바뀐 내용을 보여 줍니다 읽기
list_runs 실행 기록, 최신순. 도메인, 항목, 상태, 종류, 시간으로 거를 수 있음. 한 가지 때문에 느려진 백업은 그 원인을 알려 줍니다 읽기
list_restore_points 한 항목의 기본 저장소에 있는 복원 지점, 컨테이너라면 데이터베이스 덤프도. ZFS 데이터 세트는 백업마다 복원 지점이 하나이고, 그 아래 모든 데이터 세트의 스냅숏이 들어 있습니다 읽기
get_activity 지금 실행 중인 것, 단계와 진행률 포함 읽기
get_storage_stats 한 도메인의 기본 저장소 크기 기록과 주간 증가량, 그리고 각 저장소가 있는 디스크나 원격 위치의 사용·여유·전체 공간 읽기
get_size_breakdown 컨테이너, VM, 폴더 세트의 최신 백업에서 공간을 차지하는 폴더와 파일, 그리고 그중 마지막 백업이 추가한 양 읽기
list_anomalies BombVault가 백업에서 알아챈 이상 징후. 상태, 심각도, 도메인으로 거를 수 있고 열려 있는 것의 요약 포함 읽기
get_anomaly 그중 하나와 확인할 때 남긴 메모 읽기
start_backup 한 항목을 바로 백업합니다 시작
start_domain_backup 한 도메인의 보호 대상 항목을 모두 백업합니다 시작
start_backup_everything 전체 백업 한 바퀴를 실행합니다 시작
cancel_backup 이 키가 시작한 실행 중인 백업을 취소합니다 취소

다음은 웹 인터페이스에 남습니다: 모든 종류의 복원(데이터베이스 덤프의 다운로드, 저장, 가져오기 포함), 백업 삭제, prune, unlock, 점검과 훈련, 오프사이트 복제, 설정, 자격 증명과 MCP 키, 그리고 일정이나 웹 인터페이스 또는 다른 키가 시작한 백업의 취소. 이상 징후를 확인하거나 예상된 것으로 표시하는 일도 마찬가지로 이상 징후 페이지에서 합니다. 이유는 도구의 응답에 서버에서 온 이름과 오류 메시지가 들어 있고, 그중 어느 것에든 어시스턴트를 조종하려고 쓴 글이 섞여 있을 수 있기 때문입니다. 그런 글에 넘어간 어시스턴트가 할 수 있는 일은 최악의 경우에도 아래 제한 안에서 백업을 시작하거나 자신이 시작한 백업을 취소하는 것뿐입니다.

항목의 기본 저장소가 다른 곳(S3, REST, SFTP, rclone)에 있으면 list_restore_points가 그곳에 연결하므로 호출에 시간이 걸릴 수 있습니다. 오프사이트 사본은 MCP로 나열할 수 없습니다. 이상 징후 검사가 무엇을 보는지는 기능에, ZFS 항목이 데이터세트마다 스냅샷을 하나씩 두는 방식은 ZFS 데이터세트에 설명되어 있습니다.

시작한 백업이 하는 일

어시스턴트의 백업은 웹 인터페이스가 시작하는 백업과 같습니다. 실행 중인 컨테이너는 백업이 끝날 때까지 멈추며, 함께 멈추도록 설정된 컨테이너도 같이 멈춥니다. "graceful" 방식의 VM은 종료되었다가 다시 시작됩니다. ZFS 데이터 세트는 스냅숏을 찍는 동안 그 데이터 세트에 설정된 컨테이너를 멈춥니다. 폴더 세트, 플래시 드라이브, 설정은 계속 동작합니다. 그다음 BombVault는 보존 정책을 적용하고 오프사이트 저장소로 복사할 수 있습니다. list_items는 항목이 무엇을 멈추는지와 마지막 백업이 얼마나 걸렸는지를 어시스턴트에게 알려 주고, 도구 설명은 무언가를 시작하기 전에 이를 사용자에게 말하라고 요청합니다.

백업은 서비스를 멈추고 오래된 복원 지점을 밀어내므로, MCP를 통한 시작에는 제한이 있습니다:

  • 키마다 시간당 12번의 백업 시작.
  • 같은 항목, 같은 도메인, 전체 백업의 MCP 시작 사이에는 15분.
  • 같은 항목의 MCP 시작은 24시간에 최대 4번.
  • 보존 가드. 도메인이 정해진 개수의 복원 지점을 보존할 때(일간, 주간, 월간 규칙 없이 "최근 N개 보존"만 있는 경우, 로컬이든 오프사이트 대상이든), 새 백업이 생길 때마다 가장 오래된 것이 밀려납니다. 이때 BombVault는 최근 N-1개의 성공한 백업이 모두 MCP로 시작된 항목에 대해 MCP 시작을 거부합니다. 그래서 보존되는 묶음에는 일정이나 사용자가 만든 복원 지점이 언제나 적어도 하나 남습니다. "최근 1개 보존"에서는 어시스턴트가 그 항목을 전혀 백업할 수 없습니다. 다음 예약 백업이 다시 자리를 만듭니다. 연간 규칙만 있으면 "최근 1개 보존"과 같이 취급합니다. 올해의 복원 지점을 하나만 남기기 때문입니다.

도메인이나 전체 백업을 시작하면 제한에 걸린 항목은 빼고 응답에서 그 이름을 알려 줍니다. 이 제한들은 웹 인터페이스와 일정에는 적용되지 않습니다. 시간당 한도는 메모리에 있으므로 BombVault를 다시 시작하면 초기화됩니다.

API와 Home Assistant를 통한 시작은 항목별 제한과 보존 보호에서 MCP를 통한 시작과 함께 계산됩니다.

켜기

  1. 설정, 연동, MCP 서버를 열고 사용하는 클라이언트의 버튼을 누르세요. 목록에 없는 클라이언트는 다른 클라이언트로 연결합니다.
  2. 키에서 새 키와 제안된 이름(클라이언트 이름)을 그대로 두거나, 키를 어디에 쓰는지 알 수 있는 이름을 입력하세요. 예를 들어 "노트북의 Claude Code"처럼요. 클라이언트마다 키를 하나씩 두면 다른 키를 건드리지 않고 하나만 취소할 수 있습니다. 기존 키는 전에 만든 키를 클라이언트에 줍니다.
  3. 백업을 시작할 수 있어야 하는 키에는 백업 시작 허용을 켜세요. 끄면 키는 읽기만 할 수 있습니다. 나중에 키 타일에서 바꿀 수 있고, 바뀐 설정은 다시 연결하지 않아도 어시스턴트의 다음 요청부터 적용됩니다.
  4. 키 만들기를 누르세요. 키는 한 번만 표시됩니다. BombVault는 지문만 보관하므로 다시 보여 줄 수 없으니 지금 복사하세요. 클라이언트가 키를 쓰기 전에 대화 상자를 닫으면, 복사했다고 확인할 때까지 카드에 키가 계속 표시됩니다.

로그인 비밀번호가 없으면 웹 인터페이스 자체가 네트워크의 모든 사람에게 열려 있고, 열 수 있는 사람은 누구나 키도 만들 수 있습니다. 카드에도 그렇게 표시됩니다. 공개된 것처럼 보이는 이름(예: 리버스 프록시 뒤의 bombvault.example.com)으로 BombVault를 열었고 로그인 비밀번호가 설정되지 않았다면, 그 주소에서는 키를 만들거나 교체할 수 없습니다. 인터넷의 어떤 웹 페이지도 여러분의 브라우저가 키를 만들게 할 수 없도록 하기 위해서입니다. 로그인 비밀번호를 설정하거나, IP 주소 또는 tower, tower.local 같은 로컬 이름으로 BombVault를 여세요.

키와 키별 로그

카드에서 각 키는 자기 타일을 가집니다. 타일에는 키 이름, 백업을 시작할 수 있는지 읽기만 하는지, 키의 마지막 네 글자, 만든 시각이나 마지막으로 교체한 시각, 클라이언트가 마지막으로 사용한 시각, 오늘 호출 횟수가 나옵니다. 타일에서 키 이름을 바꾸고, 권한을 바꾸고, 키를 교체하거나 폐기합니다. 폐기한 키는 폐기된 키 목록으로 옮겨지며, 기록의 어떤 실행도 그 키를 가리키지 않게 되면 거기서 영구 삭제할 수 있습니다.

타일의 이름 옆에는 키를 만든 대상 클라이언트의 로고가 표시됩니다. 다른 클라이언트로 만들었거나 카드가 클라이언트를 나열하기 전에 만든 키에는 대신 열쇠 아이콘이 표시됩니다.

타일의 로그를 열면 그 키가 한 일이 보입니다. 먼저 그 키가 시작한 백업이 상태와 함께 나오고, 대시보드 활동 로그의 해당 실행으로 가는 링크가 붙습니다. 그 아래에 호출이 최신순으로 도구와 결과와 함께 나옵니다. 거부된 호출에는 이유가 붙습니다. 키가 읽기 전용이거나, 보존 보호가 백업을 막았거나, 다른 백업이 이미 실행 중이었거나, 항목의 백업이 몇 분 전에 웹 화면 밖에서 시작되었거나, 키가 요청을 너무 많이 보낸 경우입니다. 취소에는 해당 실행으로 가는 링크가 붙습니다.

BombVault는 키마다 기록을 최대 30일 동안 보관합니다. 성공한 시작과 취소는 최신 500건, 이와 별도로 나머지 호출(읽기, 거부, 오류)은 최신 200건입니다. 실행 중인 백업을 계속 조회하거나 거부된 호출을 계속 다시 시도하는 어시스턴트가 있어도 그 백업의 시작이 기록에서 밀려나지 않습니다. 호출마다 도구, 결과, 취소가 가리킨 실행만 저장합니다. 어시스턴트가 보낸 내용과 키, 키의 지문은 절대 저장하지 않습니다. 진단 번들에는 건수만 들어가고, 설정 내보내기에는 빠집니다.

클라이언트 연결

카드에는 이 컴퓨터에서와 클라우드에서 아래에 클라이언트마다 버튼이 있습니다. 버튼을 누르면 세 단계로 된 대화 상자가 열립니다. 키, 그 클라이언트용 구성(카드를 연 주소, 복사 버튼, 구성 위치, BombVault 자체 인증서라면 클라이언트가 그것을 신뢰하는 데 필요한 것), 그리고 클라이언트의 첫 호출 대기입니다. 대화 상자는 키의 마지막 사용을 지켜보다가 그 호출이 오면 초록색으로 바뀝니다.

대화 상자는 키를 어떤 명령줄에도 올리지 않습니다. 클라이언트가 환경 변수(BOMBVAULT_MCP_KEY), 가려진 입력 창 또는 자체 파일에서 키를 읽을 수 있으면 구성은 키를 가리키기만 합니다. 그런 방법이 없는 클라이언트는 키가 구성 파일이나 설정에 들어가며, 대화 상자에도 그렇게 적혀 있습니다. 클라이언트 문서가 모르는 인증서를 어떻게 다루는지 밝히지 않은 경우, 대화 상자는 그 단계를 클라이언트가 BombVault 인증서를 거부할 때 할 일로 적습니다.

클라이언트 설정 방식 키를 가져오는 곳
AnythingLLM 구성 파일 구성 파일
Antigravity 구성 파일 환경 변수
Claude Code 명령 키 파일
Claude Desktop 구성 파일 키 파일
Cline 구성 파일 구성 파일
Codex CLI 구성 파일 환경 변수
Continue 구성 파일 ~/.continue/.env
Copilot CLI 구성 파일 구성 파일
Cursor 구성 파일 환경 변수
Gemini CLI 구성 파일 환경 변수
GitHub Copilot (VS Code) 구성 파일 가려진 입력 창
Goose 구성 파일 환경 변수
Jan 앱 안의 양식 앱 설정
JetBrains (AI Assistant, Junie) 구성 파일 구성 파일
Kimi Code 구성 파일 구성 파일
LM Studio 구성 파일 구성 파일
Mistral Vibe 구성 파일 환경 변수
Msty 앱 안의 양식 앱 설정
n8n 앱 안의 양식 n8n 자격 증명
Open WebUI 앱 안의 양식 앱 설정
opencode 구성 파일 환경 변수
Perplexity (Mac) 앱 안의 양식 키 파일
Qwen Code 구성 파일 환경 변수
Roo Code 구성 파일 환경 변수
Visual Studio 구성 파일 구성 파일
Warp 구성 파일 구성 파일
Windsurf 구성 파일 환경 변수
Zed 구성 파일 구성 파일
Grok 양식, 클라우드 제공업체 서버
Le Chat 양식, 클라우드 제공업체 서버
ChatGPT OAuth 로그인, 클라우드 액세스 토큰, 아래 참고
Claude (claude.ai) OAuth 로그인, 클라우드 액세스 토큰, 아래 참고

아래 섹션에서는 Claude Code와 Claude Desktop 설정을 더 자세히 설명하고, 다른 클라이언트에 필요한 것을 정리합니다.

Claude Code

Claude Code는 mcp-remote를 통해 BombVault에 연결하며, 그 컴퓨터에 Node.js가 필요합니다. 먼저 키만 담은 텍스트 파일을 만들어 다음 한 줄로 저장합니다:

X-API-Key: <your key>

그런 다음 카드의 명령에 그 파일의 경로를 넣어 터미널에서 한 번 실행합니다. 컴퓨터가 신뢰하는 인증서 뒤에서는 다음과 같습니다:

claude mcp add bombvault --scope user -- npx -y mcp-remote@latest https://bombvault.example.com/mcp --header-file "<path of the file with your key>"

BombVault 자체 인증서를 쓰는 경우(TLS와 인증서 참고) 명령은 내려받은 인증서도 Node.js에 알려 줍니다:

claude mcp add bombvault --scope user -e "NODE_EXTRA_CA_CERTS=<path of the downloaded bombvault-cert.pem>" -- npx -y mcp-remote@latest https://192.168.1.10:3443/mcp --header-file "<path of the file with your key>"

연결은 Claude Code 안에서 /mcp로 확인합니다. --scope user를 쓰면 모든 프로젝트에서 BombVault를 쓸 수 있습니다. Claude Code는 키 파일의 경로만 저장하므로, 키는 명령과 셸 기록에도, 프로세스 목록에도 나타나지 않습니다. 파일은 본인만 읽을 수 있는 곳, 그리고 커밋하는 폴더 바깥에 두세요. @latest는 npx가 최신 mcp-remote를 가져오게 합니다. 이것이 없으면 전역으로 설치된 오래된 버전이 대신 쓰이는데, 그 버전은 --header-file을 지원하지 않습니다.

Claude Code용 mcp-remote 인수에 ${BOMBVAULT_MCP_KEY}를 쓰지 마세요. Claude Code는 mcp-remote를 시작하기 전에 이런 참조를 자기 환경의 값으로 바꾸므로, 키가 그 프로세스의 명령줄에 들어갑니다. 그러면 컴퓨터의 다른 프로그램과 사용자가 키를 읽을 수 있습니다.

Node.js가 없어도 Claude Code는 직접 연결할 수 있지만, 컴퓨터가 신뢰하는 인증서 뒤에서만 가능합니다. 프로젝트 폴더에 .mcp.json을 두세요:

{
  "mcpServers": {
    "bombvault": {
      "type": "http",
      "url": "https://bombvault.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${BOMBVAULT_MCP_KEY}"
      }
    }
  }
}

BOMBVAULT_MCP_KEY는 Claude Code가 시작되는 환경에 설정하세요. 예를 들어 ~/.claude/settings.json의 "env"나 셸 프로필에, 프롬프트에 입력하지 말고 텍스트 편집기로 적습니다. 이 경우에는 참조를 써도 안전합니다. Claude Code가 키를 넘겨받을 두 번째 프로세스를 시작하지 않기 때문입니다. BombVault 자체 인증서로는 이 방법이 통하지 않습니다. NODE_EXTRA_CA_CERTS를 설정해도 Claude Code 자체 연결이 그 인증서를 거부합니다. 키가 적힌 .mcp.json은 절대 커밋하지 마세요.

Claude Desktop

Claude Desktop은 mcp-remote를 통해 BombVault에 연결하며, 그 컴퓨터에 Node.js가 필요합니다. 먼저 Claude Code에서 설명한 대로 키를 별도의 텍스트 파일에 한 줄로 저장합니다. Claude Desktop의 Settings, Developer, Edit Config에서 설정 파일을 엽니다. 위치는 Windows에서는 %APPDATA%\Claude\claude_desktop_config.json, macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json입니다. 카드의 항목을 "mcpServers" 안, 이미 있는 서버들 옆에 추가하고 Claude Desktop을 다시 시작합니다:

{
  "mcpServers": {
    "bombvault": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://192.168.1.10:3443/mcp", "--header-file", "<path of the file with your key>"],
      "env": {
        "NODE_EXTRA_CA_CERTS": "<path of the downloaded bombvault-cert.pem>"
      }
    }
  }
}
  • NODE_EXTRA_CA_CERTS는 BombVault 자체 인증서 때문에만 있습니다. 컴퓨터가 이미 신뢰하는 인증서 뒤에서는 빼세요.
  • --allow-http는 일반 http:// 주소일 때만 붙습니다.
  • Windows에서는 C:/Users/sam/bombvault-key.txt처럼 경로를 슬래시로 쓰세요. 백슬래시 하나는 올바른 JSON이 아닙니다. 키 파일 경로에는 공백을 넣지 마세요. Windows의 Claude Desktop은 공백이 있는 경로를 두 조각으로 나눠 npx에 넘깁니다.
  • 구성에는 키 파일만 적히므로 키는 구성에도 프로세스 목록에도 나타나지 않습니다. 파일은 본인만 읽을 수 있는 곳에 두세요.

클라우드의 클라이언트

ChatGPT, claude.ai의 Claude, Grok, Le Chat은 제공업체의 서버에서 BombVault를 호출합니다. 그래서 BombVault는 예를 들어 리버스 프록시 뒤에서, 공개적으로 신뢰되는 인증서로 인터넷에서 접근할 수 있어야 합니다. Le Chat은 자체 서명 인증서를 거부합니다. 프록시의 로그인으로 웹 인터페이스를 보호할 수는 있지만 /mcp는 로그인 없이 BombVault까지 도달해야 합니다. 이 서비스들은 프록시에 로그인할 수 없고, 키나 토큰은 BombVault가 직접 확인합니다. Grok과 Le Chat은 고정 키를 보내며, 버튼으로 다른 클라이언트처럼 설정할 수 있습니다. ChatGPT와, 대부분의 조직에서는 claude.ai의 Claude도, 아래에서 설명하는 OAuth 로그인으로만 연결합니다.

OAuth 로그인

키를 받을 수 없는 클라이언트에게는 BombVault가 직접 OAuth 인증 서버가 됩니다. 클라이언트가 스스로 등록하고 BombVault 페이지로 안내하면, 그곳에서 로그인 비밀번호(설정했다면 2단계 인증도)로 로그인하고 허용합니다. 그러면 클라이언트는 이 BombVault의 MCP 엔드포인트에서만 쓸 수 있는 토큰을 받고, 스스로 갱신합니다.

  1. 설정, 보안에서 로그인 비밀번호를 설정합니다. 비밀번호가 없으면 동의를 받을 사람이 없으므로 BombVault는 로그인을 전혀 제공하지 않습니다.
  2. 브라우저가 신뢰하는 인증서로 https를 통해 인터넷에서 BombVault에 접근할 수 있게 합니다. 보통 리버스 프록시를 씁니다. 클라이언트는 자체 서버에서 /mcp, /oauth/, /.well-known/을 호출하므로, 자체 로그인이 있는 프록시는 이 세 경로를 BombVault까지 통과시켜야 합니다. /oauth/authorize의 동의 페이지는 내 브라우저에서 열리므로 프록시 로그인 뒤에 있어도 됩니다. 프록시를 TRUSTED_PROXY에도 지정하세요(설정 참고). BombVault는 클라이언트 등록을 주소별로 제한하므로, 지정하지 않으면 모든 클라이언트가 프록시에서 오는 것처럼 보입니다.
  3. MCP 카드에서 OAuth 로그인을 켜고 공개 주소에 경로 없는 https 주소를 입력합니다. 예: https://backup.example.com. 모든 토큰은 이 주소에 묶이므로 바꾸면 모든 클라이언트가 다시 로그인해야 합니다.
  4. ChatGPT 또는 Claude 버튼을 누릅니다. 대화 상자에 커넥터 URL(공개 주소 뒤에 /mcp를 붙인 것)과 해당 클라이언트에서 입력할 위치가 표시됩니다. ChatGPT에서는 설정, 앱 및 커넥터, 고급 설정에서 개발자 모드를 켜고 만들기를 선택한 뒤, 커넥터 URL을 MCP 서버 URL로 붙여 넣고 인증으로 OAuth를 고릅니다. claude.ai에서는 설정, 커넥터, 사용자 지정 커넥터 추가를 열고 커넥터 URL을 붙여 넣은 뒤, OAuth 클라이언트 ID와 시크릿은 비워 두고 연결을 선택합니다.
  5. 클라이언트가 동의 페이지를 엽니다. 누가 요청하는지, 응답 후 어디로 돌아가는지, 그리고 처음에는 꺼져 있는 백업 시작 허용 스위치가 표시됩니다. 허용 또는 거부를 선택합니다.

로그인한 각 클라이언트는 키 옆에 타일을 받습니다. 타일에는 마크, 로그, 취소, 백업 시작 허용이 있고, 제한은 키와 같습니다. 취소는 즉시 적용됩니다. 같은 클라이언트가 다시 로그인하면 새 권한이 이전 권한을 대체하고, 30일 동안 아무도 쓰지 않은 권한은 만료됩니다. 10개의 키와 별도로 최대 10개의 클라이언트가 동시에 로그인할 수 있습니다.

동의 페이지는 등록된 클라이언트가 등록한 돌아갈 주소 중 하나를 정확히 지정한 요청만 받습니다. 돌아갈 주소는 https이거나, 내 컴퓨터의 클라이언트라면 임의 포트의 루프백 주소입니다. PKCE(S256)를 쓰는 인증 코드 흐름만 받으며, 응답은 내 세션에 묶이므로 다른 웹사이트가 대신 보낼 수 없습니다. 액세스 토큰은 1시간 동안 유효합니다. 새로 고침 토큰은 쓸 때마다 교체되며, 이미 쓴 토큰이 다시 나타나면 다른 누군가가 사본을 가진 것이므로 BombVault가 권한을 취소합니다. 응답을 받지 못해 마지막 새로 고침을 30초 안에 다시 보낸 클라이언트는 대신 새 토큰을 받습니다. BombVault는 클라이언트 메타데이터를 인터넷에서 가져오지 않으므로, 클라이언트는 동적 클라이언트 등록으로 등록합니다.

다른 클라이언트

Streamable HTTP를 말하는 클라이언트라면 무엇이든 됩니다:

  • URL: 웹 인터페이스 주소에 /mcp를 붙인 것. 예: https://192.168.1.10:3443/mcp.
  • 키는 Authorization: Bearer <key> 또는 X-API-Key: <key>에 넣습니다. 둘 다 보내면 같은 키여야 합니다.
  • POST에 Content-Type: application/json과 Accept: application/json, text/event-stream을 붙입니다.
  • 요청당 JSON-RPC 메시지는 하나입니다. 배치는 거부됩니다.
  • 프로토콜 버전은 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26입니다.

TLS와 인증서

BombVault는 자신이 발급한 인증서로 HTTPS를 제공하며, 처음에 그 인증서에는 localhost, 127.0.0.1, ::1만 들어 있습니다. Claude Code와 mcp-remote는 LAN 주소에서 이를 거부합니다. 대부분의 Unraid 설치에 맞는 순서로 해결 방법을 적으면 다음과 같습니다:

  1. MCP 카드에서 주소 추가. 인증서에 없는 주소로 HTTPS를 통해 카드를 열면 카드가 이를 알리고 이 주소를 인증서에 추가를 제안합니다. 그러면 BombVault가 그 주소를 넣어 인증서를 다시 발급합니다(브라우저는 처음처럼 한 번 더 경고합니다). 이어서 인증서 내려받기를 누르세요. 스니펫이 NODE_EXTRA_CA_CERTS를 내려받은 파일로 설정하므로 클라이언트는 바로 그 인증서를 신뢰합니다. 즉 이전에 내려받은 파일로 설정한 클라이언트는 인증서가 다시 발급되는 순간부터, 이 컴퓨터든 다른 컴퓨터든, 새 파일을 받을 때까지 연결하지 못합니다.
  2. 신뢰할 수 있는 인증서를 가진 리버스 프록시(Nginx Proxy Manager, SWAG, Caddy, Traefik). 클라이언트는 프록시의 인증서를 보므로 더 필요한 것이 없고, 카드도 BombVault 자체 인증서에 대해 경고하지 않습니다.
  3. Tailscale. 컨테이너 앞의 tailscale serve나 Unraid의 Tailscale 연동으로 신뢰할 수 있는 인증서가 붙은 ts.net 이름을 얻습니다.
  4. HTTP_ONLY=true. TLS를 종료하는 프록시 뒤나 완전히 신뢰하는 네트워크에서만 쓰세요. 웹 인터페이스 전체를 일반 HTTP로 바꾸고, 컨테이너 설정 변경이 필요하며, 키를 암호화하지 않고 보냅니다.

NODE_TLS_REJECT_UNAUTHORIZED=0은 절대 설정하지 마세요. 그 Node.js 프로세스가 통신하는 모든 대상에 대해 인증서 검증이 꺼집니다.

리버스 프록시는 Authorization(또는 X-API-Key) 헤더를 그대로 넘겨야 하며(따로 지시하지 않으면 프록시는 그렇게 합니다), /mcp를 버퍼링하거나 다시 쓰면 안 됩니다. BombVault 인증서도 검증하는 Nginx 또는 Nginx Proxy Manager용 location 블록 예시입니다:

location /mcp {
    proxy_pass https://192.168.1.10:3443;
    proxy_ssl_verify on;
    proxy_ssl_trusted_certificate /data/bombvault-cert.pem;
    proxy_ssl_name localhost;
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_set_header Host $host;
}

프록시 뒤에서는 모든 요청이 프록시의 주소를 가집니다. 그래서 잘못 설정된 클라이언트 하나가 틀린 키를 5번 보내면, 그 프록시 뒤의 모든 MCP 클라이언트가 1분 동안 막힙니다. 클라이언트별로 세려면 프록시를 TRUSTED_PROXY에 지정하세요(설정 참고).

보안 모델

  • 활성 키가 없고 OAuth 로그인이 꺼져 있으면 /mcp는 404로 응답합니다.
  • OAuth 로그인은 로그인 비밀번호가 설정되어 있는 동안에만 제공됩니다. 토큰, 코드, 클라이언트 시크릿은 지문으로만 저장되며, 토큰은 발급된 주소에서만 쓸 수 있습니다.
  • 한 주소에서 클라이언트 등록은 시간당 최대 10번이며, BombVault는 아무도 로그인하지 않은 등록 클라이언트를 최대 100개까지, 각각 하루 동안만 보관합니다. 잘못된 코드와 새로 고침 토큰은 잘못된 키와 같은 잠금에 포함됩니다.
  • 설정 백업을 복원하거나 APP_KEY가 바뀌면 권한도 키와 똑같이 처리됩니다. 복원 후에는 모든 클라이언트가 다시 로그인해야 합니다.
  • 예외 주소는 없습니다. localhost, Unraid 호스트, 리버스 프록시, tailscale serve에서 오는 요청도 웹 인터페이스에 로그인 비밀번호가 없을 때조차 다른 요청과 똑같이 키가 필요합니다.
  • 키는 지문으로만 저장되고 한 번만 표시되며, 이름 변경, 교체, 폐기가 가능합니다. 활성 키는 최대 10개이고 각각 백업 시작 허용 스위치가 있습니다.
  • 생성, 교체, 권한 변경, 폐기가 있을 때마다 알림이 꺼져 있지 않으면 요청이 온 주소와 함께 알림 채널로 알림이 갑니다.
  • 주소마다 1분에 틀린 키 5번이면 429. 키마다 1분에 120개 요청, 1시간에 12번의 백업 시작. 여기에 위의 대기 시간과 보존 가드가 더해집니다.
  • 다른 출처(origin)의 브라우저 페이지에서 온 요청은 거부됩니다.
  • 로그인 비밀번호가 설정되지 않은 동안에는 공개된 것처럼 보이는 호스트 이름에서 키를 만들 수 없습니다.
  • 어시스턴트가 시작한 모든 백업과 그에 따른 prune 및 오프사이트 실행은 활동 로그, 오류 패널, 백업 알림에 키 이름과 함께 "MCP 경유"로 표시됩니다.
  • 모든 도구 호출은 키의 ID와 마지막 네 글자(이름은 절대 아님)와 함께 컨테이너 로그에 기록되고 /metrics에서 집계됩니다(bombvault_mcp_requests_total, bombvault_mcp_tool_calls_total, bombvault_mcp_active_keys).
  • 설정 백업을 복원하면 모든 키가 폐기됩니다. 복원한 데이터베이스에는 저장 뒤에 폐기한 키가 들어 있을 수 있기 때문입니다. 그 뒤에 새 키를 만드세요.
  • APP_KEY가 바뀌면(재설치나 다른 컨테이너로 복원) 키는 더 이상 작동하지 않습니다. 카드가 이를 감지해 키를 표시하고, 키 교체로 다시 유효한 비밀을 받을 수 있습니다.
  • 키는 비밀번호처럼 다루세요. 환경 변수, 입력 창, 키 파일 어디에서도 키를 읽을 수 없는 클라이언트는 구성이나 설정에 키를 평문으로 보관하며, 그 대화 상자에도 그렇게 적혀 있습니다. 덜 신뢰하는 컴퓨터에서는 읽기 전용 키를 쓰세요.

기기 밖으로 나가는 것

어시스턴트가 읽는 것은 모두 그 뒤의 AI 제공업체로 갑니다: 항목 이름, 일정, 오류 메시지를 포함한 실행 기록, 복원 지점의 ID와 시각, 데이터베이스 엔진 이름과 덤프 크기, 진행 중인 활동, 저장 공간 수치, 적용 범위와 상태. BombVault는 무엇이든 밖으로 나가기 전에 호스트 경로, 저장소 위치, 호스트 이름, 자격 증명, 훅 명령, 키를 제거합니다.

문제 해결

보이는 것 의미
404 활성 키가 없고 OAuth 로그인이 꺼져 있거나, /api/mcp처럼 경로가 잘못되었습니다. 엔드포인트는 /mcp입니다.
401 키가 없거나, 잘못 입력했거나, 폐기되었거나, 교체되었습니다. 프록시가 Authorization 헤더를 버리고 있을 수 있습니다(X-API-Key를 써 보세요). 카드가 키를 더 이상 유효하지 않다고 표시하면 APP_KEY가 바뀐 것입니다. 키를 교체하세요.
403 다른 출처의 브라우저 페이지에서 온 요청입니다. 데스크톱이나 명령줄 클라이언트를 쓰세요.
GET에 405 정상입니다. 엔드포인트는 POST만 받습니다.
400 "Accept must contain both 'application/json' and 'text/event-stream'" 클라이언트가 Streamable HTTP를 쓰기에는 너무 오래되었습니다. 업데이트하세요.
400 "batch requests are not accepted" 클라이언트가 JSON-RPC 배치를 보내고 있습니다. 요청마다 메시지 하나만 보내세요.
429 이 주소에서 틀린 키가 너무 많거나, 한 키로 1분에 120개를 넘는 요청이 있었습니다. 1분 기다리고 어시스턴트가 반복에 빠지지 않았는지 확인하세요.
"certificate", "self-signed", "unable to verify"가 들어간 오류 클라이언트가 BombVault 인증서를 신뢰하지 않습니다. TLS와 인증서를 참고하세요.
busy 다른 백업이나 유지보수 작업이 그 도메인을 쓰고 있습니다. 끝난 뒤 다시 시도하세요.
cooldown 이 항목, 이 도메인 또는 전체 백업이 15분 안에 웹 화면 밖에서 시작되었습니다.
retention_guard MCP 백업을 한 번 더 하면 "최근 N개 보존" 범위에 MCP가 만든 복원 지점만 남게 되거나, 그 항목이 최근 24시간 동안 이미 MCP로 백업을 4번 받았습니다(실패하거나 취소된 것도 셉니다). 앞의 경우에는 다음 예약 백업이 자리를 만들고, 뒤의 경우에는 그중 가장 오래된 백업으로부터 24시간 뒤에 다시 시작할 수 있습니다. 웹 인터페이스에서는 언제든 시작할 수 있습니다.
rate_limited 이 키는 이번 시간의 시작 12번을 다 썼습니다.
시작 시 not_permitted 읽기 전용 키입니다. 카드에서 백업 시작 허용을 켜세요. 다시 연결할 필요는 없습니다. 취소 시라면 그 실행을 이 키가 시작하지 않았다는 뜻입니다.
domain_off 그 종류의 백업이 설정에서 꺼져 있습니다.
not_found BombVault가 그 항목을 보호하지 않습니다. 먼저 웹 인터페이스에서 추가하세요. MCP는 설정을 만들지 않습니다.
클라이언트가 인증 서버를 찾지 못함 OAuth 로그인이 꺼져 있거나, 로그인 비밀번호가 없거나, 프록시가 /.well-known/을 BombVault까지 통과시키지 않습니다.
동의 페이지에 돌아갈 주소가 등록되지 않았다고 표시됨 클라이언트가 등록하지 않은 돌아갈 주소를 보냈습니다. 클라이언트에서 커넥터를 제거하고 다시 추가하세요.
로그인한 클라이언트가 401을 받음 권한이 취소되었거나, 30일 동안 쓰지 않아 만료되었거나, 공개 주소가 바뀌었습니다. 클라이언트가 다시 로그인합니다.

컨테이너에 환경 변수 MCPGODEBUG를 설정하지 마세요. MCP 라이브러리의 동작을 바꾸며, 잘못된 값이 있으면 BombVault는 로그를 한 줄도 쓰기 전에 시작 단계에서 멈춥니다.