MCP サーバー

このページでは、AI エージェントを Ratatosk につなぐ方法を説明します。

MCP（Model Context Protocol）は、AI エージェントが外部ツールを呼び出すための標準プロトコルです。Ratatosk の MCP サーバーをつなぐと、エージェントがリリースの change（データを理解する）を直接取得し、稼働中のスタックと突き合わせて、アップグレードで必要になる対応事項をまとめて提示できます。サーバーは読み取り専用です — クラスタには一切の変更を加えません。

接続方法は二つあり、どちらも同じ 6 つのツールを提供します:

区分	ホスト版	セルフホスト
始め方	URL 一つを登録、インストール不要	コンテナ・バイナリを自分で実行
バージョン情報	サーバーに送信される（処理中のメモリを通るだけで記録されない）	`check_stack` のバージョン比較はインフラの内側で実行 — 明示的な取得（`get_release`）はプロジェクト・バージョンがリクエストに載るが、ログには残らない
監査ログ	なし（意図的にオフ）	必要ならオンにできる（`MCP_AUDIT`）
向いている場面	すぐ試す、個人利用	プライバシー要件、企業の監査要件、大量利用

クイックスタート: ホスト版エンドポイント

ホスト版のエンドポイントは https://ratatosk.io/mcp です。ステートレスな 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 回のツール呼び出しを許可します。全体で分け合う枠ではなく呼び出し元ごとに数えるので、誰か 1 人が忙しくても他の利用者が枯渇しません。超えると Retry-After 付きの 429 が返ります。ツール呼び出し 1 回は API リクエスト 1 回ではありません — check_stack はコンポーネント 1 つにつきアップストリームへ 1 リクエストを使います。上限をツール呼び出し単位で表しているのはそのためです。自分で /v1 を呼ぶ場合は、自分の IP の枠として毎分 1200 リクエストが使えます（REST API）。大量に利用する場合はセルフホストに切り替えてください。
監査ストリームはホスト版では無効にしてあり、今後も有効にすることはありません。リクエスト内容を記録に残さないことがホスト版エンドポイントの運用ポリシーです（下の「プライバシー」を参照）。

セルフホスト

次のいずれかに当てはまる場合は、サーバーを自分で実行してください。バージョン情報をインフラの外に出せない場合、監査記録が必要な場合、そしてホスト版の呼び出し元ごとのツール呼び出し上限ではなく自分の分のリクエスト上限（IP あたり毎分 1200 リクエスト — 上の「既知の挙動と制限」を参照）を使いたい場合です。ソースと完全なインストールガイドは公開リポジトリ github.com/garlicKim21/ratatosk-mcp にあります。

前提条件

Docker（ソースからビルドする場合は Go）。Kubernetes にデプロイするなら 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 は Kubernetes で 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 の増分フィード（プロジェクト・family・bucket・actionability で絞り込み）。カーソルポーリング方式 — REST API の「増分取得」と同じルール
`changes_by_entity`	一つの識別子（CVE・CRD・フラグなど）を扱ったすべての change
`get_matter`	一つの事案が登場したリリースすべて — 同じロールアップがブランチごとに違うアドバイザリを伴って着地します
`list_projects`	追跡プロジェクトの全一覧。スラッグはまずここで確認
`get_release`	リリース一件: エンベロープとその change すべて。バージョン省略で最新。原文を含めるオプションあり
`list_releases`	プロジェクトの最新リリース N 件のサマリー — 「X の最近のリリース」という質問専用のツール
`check_stack`	稼働中のバージョン一覧と change を突き合わせ、アップグレード経路の対応事項を層別にブリーフィング

ツールごとのパラメータ・呼び出し例・実測レスポンスはツールリファレンスへ。

プライバシー

稼働中のバージョンは機微な情報になり得ます。露出が少ない順に並べると、次のようになります。

セルフホスト MCP の check_stack — バージョン比較がユーザー側の MCP サーバープロセスの中で実行されます。ratatosk.io に出ていくのはプロジェクトごとの公開リリースデータの取得だけなので、稼働中のバージョン一覧がユーザーのインフラを出ることはありません。公開リポジトリのコードで直接確認できます。ただし、get_release(project, version) のようにバージョンを引数に取るツールは、そのバージョンを取得リクエストのパスに載せます。取得対象を指し示す値だからです。このパスも、サーバーのアクセスログでは記録前にプレフィックスへ正規化されるため、どのプロジェクト・バージョンを取得したかは残りません。なお、この経路も前段の CDN 区間は通ります。これは 3 番で述べる CDN と同じく、管理の外の境界です。check_stack だけを使えば、その区間を通る値もプロジェクト名だけになります。
API で取得して自分で比較 — change を取得し、version_rank でローカルで比較します。システムに関する情報は何も送信しません — REST API。
ホスト版 MCP・/v1/upgrade — サーバーが比較を代行するため、送信したバージョンはサーバーに届きます。リクエスト内容は処理中のメモリを通るだけで、どのログにも記録されません。アクセスログに残るのは、呼び出しがあったという事実と、その接続メタデータだけです。具体的には、マスクされた IP、国コード、クライアント識別文字列（User-Agent）、リクエストサイズ、ステータスコードなどです。何を取得したか（プロジェクト・バージョン・リクエスト本文・クエリ）は、記録前に除去・正規化されるため残りません。ログは数日以内にローテーションで削除されます（プライバシーポリシー）。リクエストは前段の CDN（Cloudflare）を経由します。その区間の接続メタデータは CDN 自身のポリシーに従う、管理の外の境界です。3 つの段階はいずれも同じ CDN を経由するため、この境界は段階の選び方では避けられません。ただし 1 番（セルフホストの check_stack）ではバージョンがリクエスト自体に載らないため、CDN 区間にもバージョンは流れません。この 3 番目の段階は、構造ではなく運用ポリシーによって保証されています。その保証のしかたが要件に合わない場合は、1 または 2 を選んでください。

下の図は、1 のセルフホスト check_stack の 1 サイクルを示したものです:

セルフホストしたサーバーのログと監査も、同じ原則で動きます。

デフォルトのログはライフサイクル（listening / session ended）だけで、リクエストごとの記録はありません。MCP_LOG=debug に上げても、実際の値の代わりにパステンプレート（/v1/releases/{project}/{version}）だけが記録されます。
MCP_AUDIT はデフォルトでオフです。オフの間は、監査イベントは一切生成されません。監査記録が必要なら、セルフホストで metadata または full をオンにしてください。

リクエストのトレースは、ホスト版・セルフホストで共通の仕組みです。呼び出し側が MCP リクエストの _meta に traceparent（W3C 標準の分散トレーシングヘッダー）を載せて送ったとします。その呼び出しがログを残す条件（エラー発生時、MCP_LOG=debug、有効にした監査ストリーム）を満たしていれば、MCP 側のログとウェブ側のログに同じ trace_id が記録され、両者を突き合わせられます。デフォルトの設定では、正常に処理されたリクエストについては MCP 側にログが 1 行も残らず、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）を開きません。
リクエスト上限（レートリミット）にかかるとき: ホスト版は共有バケットのため、自分の呼び出しが少なくても上限に達することがあります — 上の「既知の挙動と制限」を参照。ポーリング間隔を延ばすか、セルフホストに切り替えてください。

次のステップ

ツールが返すデータの構造: データを理解する
MCP なしで HTTP から直接: REST API