RATATOSKRATATOSK
Sign in

MCP server

This page explains how to connect an AI agent to Ratatosk.

MCP (Model Context Protocol) is the standard protocol AI agents use to call external tools. With Ratatosk's MCP server attached, an agent can query release changes (Understanding the data) directly and brief you on what an upgrade requires by matching those changes against the versions you run. The server is read-only — it makes no changes to your cluster.

There are two ways to connect, and both provide the same six tools:

Hosted Self-hosted
Getting started Register one URL, zero install Run the container/binary yourself
Version information Sent to the server (passes through memory during processing; not recorded) check_stack compares versions inside your infrastructure — explicit lookups (get_release) carry project/version in the request, but they are not logged
Audit log None (deliberately off) Can be enabled when needed (MCP_AUDIT)
Good fit Trying it out, personal use Privacy requirements, corporate audit requirements, heavy use

Quick start: the hosted endpoint

The hosted endpoint is https://ratatosk.io/mcp. It uses Streamable HTTP, MCP's standard HTTP transport, in stateless mode — there are no sessions, and every request stands on its own.

Prerequisites

  • An agent that supports remote (HTTP) MCP servers — Claude and Claude Code both do. For other clients, look for "remote" or "HTTP" MCP in their documentation. If your client doesn't support it, use the self-hosted (stdio) route below.

Steps

In Claude Code:

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

In Claude (web and desktop), open settings and add a remote MCP connector with the URL https://ratatosk.io/mcp.

Other MCP clients: register the URL as an HTTP-type server. For example, in Claude Code's .mcp.json config file format (formats vary by client):

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

Verify

You are connected when the agent's tool list shows the six tools, check_stack among them. Try a question like "any security issues in recent cert-manager releases?"

To probe the endpoint without a client:

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"}}}'

Expected output:

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

The response comes as SSE frames (event:/data: lines) — strip the data: prefix before piping into jq or other JSON tools. If serverInfo carries the server name and version, the endpoint is up and answering.

Limits and expected behavior

  • The hosted endpoint allows 60 tool calls per minute per caller, counted per caller rather than pooled, so one busy caller cannot starve the rest. Over the limit you get 429 with Retry-After. Note that one tool call is not one API request — check_stack costs one upstream request per component — which is why the limit is expressed in tool calls. Calling /v1 directly instead gives you 1200 requests per minute against your own IP (REST API). For heavy use, self-host.
  • The hosted endpoint runs with the audit stream off and keeps it off: not recording request contents is deliberate policy, not a default — see "Privacy" below.

Self-hosting the server

Run the server yourself when version information must not leave your infrastructure, when you need audit records, or when you want your own request limit (1200 per minute per IP — see "Limits and expected behavior" above) instead of the hosted endpoint's per-caller tool-call budget. Source and the full install guide are in the public repo github.com/garlicKim21/ratatosk-mcp.

Prerequisites

  • Docker (or Go, to build from source). Helm for Kubernetes deployment.

Steps

stdio for a local agent — stdio means the agent launches the server process itself and talks over standard input/output. A single binary is enough. With Claude Code:

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

As an HTTP server inside a cluster: set the environment variable MCP_HTTP_ADDR and it serves Streamable HTTP; agents inside the cluster reach it through a Service. With MCP_HTTP_STATELESS=1 it runs the same stateless mode as the hosted endpoint. A Helm chart is in the repo.

With kagent: kagent is an open source framework for running AI agents on Kubernetes. Add a single kagent.enabled=true to the Helm install and you get the server deployment, kagent registration, and the example agent ratatosk-agent in a single install. The example agent discovers running versions on its own through kagent's read-only cluster tools. Helm-free manifests are in the repo under examples/kagent.

Key environment variables — the full list and per-setup configuration examples are in the repo install guide (English, Korean, Japanese):

Variable Default Meaning
RATATOSK_URL https://ratatosk.io API address to read data from
MCP_HTTP_ADDR (off) When set, runs as an HTTP server instead of stdio
MCP_HTTP_STATELESS (off) 1 for sessionless, stateless HTTP
MCP_LOG info Log level. Operational log lines never carry request argument values at any level (the audit stream is a separate opt-in — next row)
MCP_AUDIT (off) Audit stream. metadata = tool, outcome, and argument names only; full = argument values included

Verify

Same as hosted — you are connected when the agent's tool list shows the six tools.

Tools

Tool What it does
list_changes Incremental change feed (project/family/bucket/actionability filters). Cursor polling — same rules as "Incremental polling" in the REST API
changes_by_entity Every change touching a single identifier (CVE, CRD, flag, …)
get_matter Every release in which one matter appeared — the same roll-up can land on several branches carrying different advisories
list_projects Every tracked project. Check slugs here first
get_release One release: envelope plus all its changes. Latest when the version is omitted. Option to include the original notes
list_releases Summaries of a project's N most recent releases — the tool for "recent releases of X" questions
check_stack Matches your list of running versions against the changes and briefs the actions along the upgrade path, split by bucket

Per-tool parameters, example calls, and measured responses live in the tools reference.

Privacy

The versions you run can be sensitive information. Listed from least exposure to most:

  1. Self-hosted MCP's check_stack — the version comparison runs inside the MCP server process on your side. All that goes to ratatosk.io is queries for per-project public release data, so your list of running versions never leaves your infrastructure. You can verify this directly in the public repo's code. One caveat: tools that take a version as an argument, like get_release(project, version), put that version in the upstream request path, because naming the release is how you fetch it. Even that path is normalized to a prefix before the server's access log is written, so which project/version was queried is not recorded. That path does cross the CDN, though — the same boundary Ratatosk does not control, described under option 3. Use check_stack only, and nothing but project names crosses it.
  2. Fetch over the API and compare yourself — pull changes and compare locally with version_rank. Nothing about your systems is sent — REST API.
  3. Hosted MCP · /v1/upgrade — the server does the comparison for you, which means the versions you send do reach the server. Request contents pass through memory during processing and are not written to any log. The access log keeps only the record that a call happened and its connection metadata: masked IP, country code, client identifier string (User-Agent), request size, status code, and the like. What was queried (project, version, request body, query string) is stripped and normalized away before logging. Logs rotate out within days (privacy policy). Requests pass through a CDN (Cloudflare) in front — connection metadata on that leg follows the CDN's own policies, a boundary Ratatosk does not control. All three options pass through the same CDN, so choosing an option does not avoid it — but with option 1 (self-hosted check_stack) versions are never in the request at all, so no version crosses the CDN leg either. This option rests on operating policy rather than structure, so if that difference does not meet your requirements, use options 1 or 2.

The diagram below shows one cycle of option 1 — self-hosted check_stack:

YOUR INFRASTRUCTUREAI agentClaude Code · kagent① Stack, versions includedenvoy v1.36.8⑤ Briefingbriefingratatosk-mcpruns on your side④ Local version compare② Project names onlyenvoy③ release changeschanges ×51ratatosk.iochanges database⑥ Briefing received · next stepcritical 1 · 3 action items→ upgrade envoy to v1.36.9check_stack: versions never leave your infrastructure

The self-hosted server's logging and audit behavior follows the same principles:

  • Default logs are lifecycle only (listening / session ended), with no per-request records. Even at MCP_LOG=debug, path templates (/v1/releases/{project}/{version}) are logged instead of actual values.
  • MCP_AUDIT is off by default, and while it is off, nothing is emitted at all. If you need audit records, enable metadata or full on your self-hosted server.

Request tracing works the same way hosted or self-hosted. If the caller puts a traceparent — the W3C distributed-tracing header — in the MCP request's _meta, every log line that call produces carries the same trace_id as the web log line, so the two correlate. Lines are produced on errors, at MCP_LOG=debug, and when the audit stream is on. Under default settings a successfully handled request produces no MCP log line at all, and without a traceparent no correlation information exists.

Auto-discovery

A standard server card is published so agents can discover the server mechanically: /.well-known/mcp/server-card.json

The official MCP Registry lists it as io.github.garlicKim21/ratatosk-mcp. The registry entry points to the self-hosted package (the container image) — the hosted endpoint is discovered through the server card above. The server card's name field is io.ratatosk/mcp — the two identifiers refer to the same server (the registry uses the GitHub namespace; the card uses the domain namespace).

Troubleshooting

  • Tools don't show up: check that the registered URL is exactly https://ratatosk.io/mcp (path included), and for self-hosted, that the command actually runs. The curl under "Verify" above probes the endpoint itself.
  • Opening it in a browser shows this document: normal. A browser GET of /mcp redirects here for guidance. The endpoint only answers POST requests from MCP clients.
  • A GET stream returns 405: normal. The hosted endpoint is stateless and does not open server-initiated SSE streams (GET).
  • Hitting the rate limit: the hosted bucket is shared, so you can hit it even with little traffic of your own — see "Limits and expected behavior" above. Poll less often or switch to self-hosted.

Next steps