Developers

Everything Klag exposes to programs rather than people. If you are a person, start with the Quick Start.

The HTTP API

A running Klag serves a small, read-only HTTP surface on HTTP_PORT (default 8888). Klag is self-hosted, so this is your endpoint — there is no hosted Klag service and no API key to request.

Method	Path	Purpose
GET	/healthz	Liveness. Always 200 while the process is up.
GET	/readyz	Readiness. 200 when Kafka is reachable, 503 when it is not.
GET	/metrics	Prometheus scrape endpoint (when METRICS_REPORTER=prometheus).
GET	/version	Klag, Vert.x, and Java versions.
POST	/mcp	MCP endpoint, JSON-RPC 2.0 (when MCP_ENABLED=true). GET returns 405.

OpenAPI 3.1 spec: klag.dev/openapi.json — typed response schemas, unique operation IDs, and the bearer scheme used by MCP_AUTH_TOKEN. Also listed in the API catalog (RFC 9727).

curl -s http://localhost:8888/readyz   # {"status":"UP","kafka":"connected"}
curl -s http://localhost:8888/version  # {"version":"…","vertxVersion":"…","javaVersion":"…"}

Two MCP servers, two jobs

This trips people up, so it is worth being blunt about it:

	Documentation MCP	Klag instance MCP
URL	https://klag.dev/mcp (hosted, always on)	/mcp on your Klag (opt-in)
Answers	Questions about Klag: config, metrics, deployment	Questions about your Kafka consumer groups
Auth	None	MCP_AUTH_TOKEN bearer, when set
Reads	The published docs	Klag’s in-memory snapshot — never Kafka directly

Documentation MCP — https://klag.dev/mcp

Read-only, unauthenticated, Streamable HTTP (JSON-RPC 2.0 over POST). Use it to look up configuration and metrics while installing or operating Klag, without scraping this site.

Tool	Purpose
search_klag_docs	Full-text search across klag.dev; ranked excerpts with URLs.
get_klag_doc	The full markdown of one page.
get_klag_config	Any environment variable: default value and what it does.
get_klag_metric	Any exported metric: meaning and tags.

It also exposes /llms.txt and /llms-full.txt as MCP resources.

Claude Code

claude mcp add --transport http klag-docs https://klag.dev/mcp

mcp.json

{
  "mcpServers": {
    "klag-docs": {
      "type": "http",
      "url": "https://klag.dev/mcp"
    }
  }
}

curl

curl -s https://klag.dev/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_klag_config","arguments":{"name":"KAFKA_CHUNK_COUNT"}}}'

Server card: /.well-known/mcp/server-card.json.

Klag instance MCP

Turn on MCP_ENABLED=true with a metrics reporter configured, and your instance exposes list_consumer_groups, get_consumer_group_lag, find_lagging_groups, and diagnose over the same transport. Full reference: MCP Endpoint.

Agent skills

The Claude Code plugin — /klag:install, /klag:connect, /klag:diagnose — is published both as a plugin and as plain skill markdown any agent can fetch.

/plugin marketplace add themoah/klag
/plugin install klag@klag

Discovery index: /.well-known/agent-skills/index.json (Agent Skills v0.2.0, with a SHA-256 digest per artifact). Walkthrough: Agent setup.

Documentation as data

Resource	What it is
/llms.txt	Summary, quick start, key metrics, and a linked index of every page.
/llms-full.txt	Every page concatenated, for direct ingestion.
/<section>/llms.txt	Scoped index per area — metrics, configuration, integrations, deployment, guides, comparisons.
<any page>.md	The markdown twin of any page — append .md, or send Accept: text/markdown.
/.well-known/ai-catalog.json	Agentic Resource Discovery catalog: every resource on this page, machine-readable.
/.well-known/agent-card.json	A2A agent card.

curl -s https://klag.dev/metrics/lag-velocity.md          # markdown twin
curl -s -H 'Accept: text/markdown' https://klag.dev/      # content negotiation

Source and packaging

SourceApache-2.0, Java 21 on Vert.x.

Container imagethemoah/klag — JVM and native variants.

Helm chartKubernetes deployment, ServiceMonitor included.

Build from sourceGradle, tests, and the GraalVM native image.