RATATOSKRATATOSK
로그인

MCP 서버

이 페이지는 AI 에이전트를 Ratatosk에 연결하는 방법을 설명합니다.

MCP(Model Context Protocol)는 AI 에이전트가 외부 도구를 호출하는 표준 프로토콜입니다. Ratatosk의 MCP 서버를 붙이면 에이전트가 릴리스 change(데이터 이해하기)를 직접 조회하고, 실행 중인 스택과 대조해 업그레이드에 필요한 조치를 정리해 줄 수 있습니다. 서버는 읽기 전용입니다 — 클러스터에 어떤 변경도 가하지 않습니다.

연결 방법은 두 가지이고, 어느 쪽이든 같은 도구 6개를 제공합니다:

구분 호스팅 설치형
시작 URL 하나만 등록, 설치 없음 컨테이너·바이너리를 직접 실행
버전 정보 서버에 전달됨 (처리 중 메모리만 거치고 기록 안 함) check_stack의 버전 비교는 인프라 안에서 수행 — 명시 조회(get_release)는 프로젝트·버전이 요청에 실리지만 로그에는 남지 않음
감사 로그 없음 (의도적으로 꺼져 있음) 필요 시 켤 수 있음 (MCP_AUDIT)
어울리는 경우 바로 써 보기, 개인 사용 프라이버시 요건, 기업 감사 요건, 대량 사용

빠른 시작: 호스팅 엔드포인트

호스팅 엔드포인트는 https://ratatosk.io/mcp 입니다. 무상태(stateless) Streamable HTTP로 동작합니다. Streamable HTTP는 MCP의 표준 HTTP 통신 방식(트랜스포트)이고, 무상태는 세션이 없어 요청 하나하나가 독립적이라는 뜻입니다.

사전 준비

  • 원격 MCP 서버(HTTP)를 지원하는 에이전트 — Claude, Claude Code 등이 해당합니다. 지원 여부는 클라이언트 문서의 remote/HTTP MCP 항목에서 확인하세요. 지원하지 않는 클라이언트라면 아래 설치형(stdio)으로 가세요.

절차

Claude Code에서:

claude mcp add --transport http ratatosk https://ratatosk.io/mcp

**Claude(웹·데스크톱)**에서는 설정의 커넥터(원격 MCP) 추가 화면에 URL https://ratatosk.io/mcp를 입력합니다.

그 밖의 MCP 클라이언트: HTTP 타입 서버로 URL만 등록하면 됩니다. 예를 들어 Claude Code의 .mcp.json 설정 파일 형식이라면 (형식은 클라이언트마다 다릅니다):

{
  "mcpServers": {
    "ratatosk": { "type": "http", "url": "https://ratatosk.io/mcp" }
  }
}

확인

에이전트의 도구 목록에 check_stack 등 6개 도구가 보이면 연결된 것입니다. "cert-manager 최근 릴리스에 보안 이슈 있어?" 같은 질문을 던져 보세요.

클라이언트 없이 엔드포인트만 확인하려면:

curl -s -X POST https://ratatosk.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}'

기대 출력:

event: message
data: {"jsonrpc":"2.0","id":1,"result":{...,"serverInfo":{"name":"ratatosk","version":"0.6.1"}}}

응답은 SSE 프레임(event:/data: 줄)으로 옵니다 — jq 등 JSON 도구에 넘기려면 data: 접두사를 떼어 내세요. serverInfo에 서버 이름과 버전이 담겨 있으면 정상입니다.

알려진 동작과 제한

  • 호스팅 엔드포인트는 호출자당 분당 도구 호출 60회를 허용합니다. 전체가 나눠 쓰는 몫이 아니라 호출자별로 세므로, 한 명이 바쁘다고 나머지가 굶지 않습니다. 넘기면 Retry-After가 붙은 429가 돌아옵니다. 도구 호출 1회가 API 요청 1회는 아닙니다 — check_stack은 컴포넌트 하나당 업스트림 요청 1회를 씁니다. 한도를 도구 호출 단위로 표현한 이유가 그것입니다. 직접 /v1을 호출하면 자기 IP 몫으로 분당 1200회를 받습니다(REST API). 사용량이 많다면 설치형으로 옮기세요.
  • 감사 스트림은 호스팅에서 일부러 꺼 두었고, 앞으로도 켜지 않습니다. 요청 내용을 기록으로 남기지 않는 것이 호스팅 엔드포인트의 운영 방침입니다 — 아래 "프라이버시" 참조.

설치형 (self-hosted)

버전 정보가 인프라를 떠나면 안 되거나, 감사 기록이 필요하거나, 호스팅의 호출자별 도구 호출 한도 대신 내 몫의 요청 한도(IP당 분당 1200회 — 위 "알려진 동작과 제한" 참조)를 쓰고 싶다면 서버를 직접 실행하세요. 소스·전체 설치 가이드는 공개 저장소 github.com/garlicKim21/ratatosk-mcp 입니다.

사전 준비

  • Docker (또는 소스 빌드 시 Go). 쿠버네티스에 배포하려면 Helm.

절차

로컬 에이전트에 stdio로 — stdio는 에이전트가 서버 프로세스를 직접 띄워 표준 입출력으로 통신하는 방식입니다. 바이너리 하나면 됩니다. Claude Code 기준:

claude mcp add ratatosk -- docker run --rm -i ghcr.io/garlickim21/ratatosk-mcp:0.6.1

클러스터 안에 HTTP 서버로: 환경 변수 MCP_HTTP_ADDR을 주면 Streamable HTTP 서버로 동작하고, 클러스터 안의 에이전트는 Service를 통해 접속합니다. MCP_HTTP_STATELESS=1이면 호스팅 엔드포인트와 같은 무상태 모드입니다. Helm 차트가 레포에 있습니다.

kagent 연동: kagent는 쿠버네티스에서 AI 에이전트를 구동하는 오픈소스 프레임워크입니다. Helm 설치에 kagent.enabled=true 하나를 더하면 서버 배포와 kagent 등록, 예제 에이전트 ratatosk-agent까지 한 번에 됩니다. 예제 에이전트는 kagent의 읽기 전용 클러스터 도구로 실행 중인 버전을 스스로 알아냅니다. Helm 없이 쓰는 매니페스트는 저장소의 examples/kagent에 있습니다.

주요 환경 변수는 다음과 같습니다. 전체 목록과 설치 방식별 설정 예시는 저장소의 설치 가이드에 있습니다(영어·한국어·일본어).

변수 기본 뜻
RATATOSK_URL https://ratatosk.io 데이터를 읽어올 API 주소
MCP_HTTP_ADDR (꺼짐) 지정하면 stdio 대신 HTTP 서버로 동작
MCP_HTTP_STATELESS (꺼짐) 1이면 세션 없는 무상태 HTTP
MCP_LOG info 로그 레벨. 운영 로그 줄에는 어느 레벨에서도 요청 인자 값이 남지 않음 (감사 스트림은 별도 옵트인 — 아래 행)
MCP_AUDIT (꺼짐) 감사 스트림. metadata=도구·결과·인자 이름만, full=인자 값 포함

확인

호스팅과 같습니다 — 에이전트의 도구 목록에 6개 도구가 보이면 연결된 것입니다.

도구

도구 하는 일
list_changes change 증분 피드 (프로젝트·가족·층·판정 필터). 커서 폴링 방식 — REST API의 "증분 조회"와 같은 규칙
changes_by_entity 식별자 하나(CVE·CRD·플래그 등)를 건드린 모든 change
get_matter 한 사안이 등장한 릴리스 전부 — 같은 롤업이 갈래마다 다른 권고를 달고 착지합니다
list_projects 추적 프로젝트 전목록. 슬러그는 먼저 여기서 확인
get_release 릴리스 하나: 봉투 + 그 릴리스의 change 전부. 버전 생략 시 최신. 원문 포함 옵션
list_releases 프로젝트의 최근 릴리스 N개 요약 — "X의 최근 릴리스" 질문 전용 도구
check_stack 실행 중인 버전 목록과 change를 대조해 업그레이드 경로의 조치 사항을 층별로 브리핑

도구별 파라미터·예시 호출·실측 응답은 도구 레퍼런스에 있습니다.

프라이버시

실행 중인 버전은 민감한 정보일 수 있습니다. 노출이 적은 순서로:

  1. 설치형 MCP의 check_stack — 버전 비교를 사용자 쪽 MCP 서버 프로세스 안에서 끝냅니다. ratatosk.io로 나가는 것은 프로젝트별 공개 릴리스 데이터 조회뿐이라, 실행 중인 버전 목록이 사용자 인프라를 떠나지 않습니다. 공개 저장소의 코드에서 직접 확인할 수 있습니다. 단, get_release(project, version)처럼 버전을 인자로 받는 도구는 그 버전을 조회 요청 경로에 담습니다 — 조회 대상을 지목하는 값이기 때문입니다. 이 경로 역시 서버 액세스 로그에 기록되기 전에 접두사만 남도록 정규화되므로, 어떤 프로젝트의 어떤 버전을 조회했는지는 남지 않습니다. 다만 이 경로도 앞단의 CDN 구간은 지납니다 — 3번의 CDN 항목과 같은, 통제 밖의 경계입니다. check_stack만 쓰면 그 구간에 나가는 값도 프로젝트 이름뿐입니다.
  2. API로 받아서 직접 비교 — change를 받아 version_rank로 로컬에서 비교합니다. 시스템에 관한 정보는 아무것도 보내지 않습니다 — REST API.
  3. 호스팅 MCP · /v1/upgrade — 서버가 비교를 대신 해 주는 대가로, 보낸 버전이 서버까지 도달합니다. 요청 내용은 처리 중 메모리만 거치고 어떤 로그에도 기록되지 않습니다. 액세스 로그에 남는 것은 호출이 있었다는 사실과 접속 메타데이터뿐입니다. 마스킹된 IP, 국가 코드, 클라이언트 식별 문자열(User-Agent), 요청 크기, 상태 코드 같은 값입니다. 무엇을 조회했는지, 곧 프로젝트·버전·요청 본문·쿼리는 기록되기 전에 제거·정규화되어 남지 않습니다. 로그는 수일 내 순환 삭제됩니다(개인정보처리방침). 요청은 앞단의 CDN(Cloudflare)을 거칩니다 — 그 구간의 접속 메타데이터는 CDN 자체 정책을 따르는, 통제 밖의 경계입니다. 이 경계는 세 단계 모두 같은 CDN을 지나므로 단계 선택으로 피할 수 없습니다 — 다만 1번(설치형 check_stack)은 버전이 요청 자체에 실리지 않아, CDN 구간에도 버전이 지나가지 않습니다. 이 단계는 구조가 아니라 운영 방침에 기대는 것이므로, 그 차이가 요건에 맞지 않으면 1·2번을 쓰세요.

아래 그림은 1번(설치형 check_stack)의 한 사이클입니다:

사용자 인프라AI 에이전트Claude Code · kagent① 스택 전달 · 버전 포함envoy v1.36.8⑤ 브리핑브리핑ratatosk-mcp사용자 환경에서 실행④ 로컬 버전 비교② 프로젝트 이름만envoy③ release changeschanges ×51ratatosk.iochanges 데이터베이스⑥ 브리핑 수신 · 에이전트의 다음 행동critical 1 · 조치 3건→ envoy v1.36.9 업그레이드 권고check_stack에서는 상세 버전 정보가 외부로 나가지 않습니다

설치형 서버의 로그·감사 동작도 같은 원칙입니다:

  • 기본 로그는 수명주기(listening / session ended)뿐이고, 요청별 기록이 없습니다. MCP_LOG=debug로 올려도 실제 값 대신 경로 템플릿 (/v1/releases/{project}/{version})만 기록됩니다.
  • MCP_AUDIT는 기본 꺼짐이며, 꺼져 있으면 감사 이벤트가 한 바이트도 생성되지 않습니다. 감사 기록이 필요하면 설치형에서 metadata 또는 full로 켜세요.

요청 추적은 호스팅·설치형 공통입니다. 호출자가 MCP 요청의 _meta에 traceparent(W3C 표준 분산 추적 헤더)를 실어 보내면, 그 호출이 로그 줄을 남기는 경우(오류, MCP_LOG=debug, 켜 둔 감사 스트림)에 그 줄과 웹 로그 줄에 같은 trace_id가 찍혀 서로 이어집니다. 기본 설정에서 정상 처리된 요청은 MCP 쪽에 로그 줄 자체가 없고, traceparent를 보내지 않으면 아무 상관 정보도 남지 않습니다.

자동 발견

에이전트가 기계적으로 발견할 수 있도록 표준 서버 카드를 게시합니다: /.well-known/mcp/server-card.json

공식 MCP Registry에는 io.github.garlicKim21/ratatosk-mcp 이름으로 등록되어 있습니다. 레지스트리 항목은 설치형 패키지(컨테이너 이미지)를 안내합니다 — 호스팅 엔드포인트는 위 서버 카드로 찾을 수 있습니다. 서버 카드의 name 필드는 io.ratatosk/mcp입니다 — 두 식별자는 같은 서버를 가리킵니다 (레지스트리는 GitHub 네임스페이스, 카드는 도메인 네임스페이스를 씁니다).

문제 해결

  • 도구 목록이 안 보일 때: 등록한 URL이 정확히 https://ratatosk.io/mcp 인지(경로 포함), 설치형이라면 명령이 정상 실행되는지 확인하세요. 위 "확인"의 curl로 엔드포인트 자체를 점검할 수 있습니다.
  • 브라우저로 열면 이 문서가 나올 때: 정상입니다. /mcp를 브라우저로 GET하면 안내를 위해 이 페이지로 리다이렉트합니다. 엔드포인트는 MCP 클라이언트의 POST 요청에만 응답합니다.
  • GET 스트림이 405를 반환할 때: 정상입니다. 호스팅 엔드포인트는 무상태라 서버 주도 SSE 스트림(GET)을 열지 않습니다.
  • 요청 한도(레이트리밋)에 걸릴 때: 호스팅은 공용 버킷이라 내 호출량이 적어도 걸릴 수 있습니다 — 위 "알려진 동작과 제한" 참조. 폴링 주기를 늘리거나 설치형으로 전환하세요.

다음 단계