Like what you see? ⭐ Star the repo ⭐ to support the project and keep it in the spotlight. See the stargazers →

MCP

This document sketches a Model Context Protocol (MCP) service for KafScale. The goal is to enable safe, structured, agent-friendly operations without embedding MCP into brokers or widening the broker attack surface.

For deployment details and configuration options, see MCP Server.

Goals

  • Provide read-only observability for ops debugging and reporting.
  • Offer a path to mutation tools once broker/admin auth exists.
  • Ship as a separate service (kafscale-mcp), not embedded in brokers.

Non-Goals

  • No direct embedding in the broker process.
  • No unauthenticated mutation tools.
  • No replacement for Kafka protocol or admin APIs.

Architecture

  • Standalone MCP service deployed alongside KafScale.
  • Talks to KafScale via:
    • Metadata store access (read-only).
    • Prometheus metrics scraping.
    • Optional gRPC control plane (future, gated).
  • Deployed as an optional Helm chart and disabled by default.
  • Helm defaults to a dedicated namespace for the MCP service.

Service Shape

  • HTTP endpoint: /mcp using MCP streamable HTTP transport (SSE).
  • Health check: /healthz.
  • Read-only tools only; mutation tools are not registered.

For configuration and environment variables, see MCP Server.

Enable MCP

Enable the service via Helm, then configure auth and endpoints:

mcp:
  enabled: true
  auth:
    token: "<bearer-token>"
  etcdEndpoints:
    - "http://etcd.kafscale.svc:2379"
  metrics:
    brokerMetricsURL: "http://kafscale-broker.kafscale.svc:9093/metrics"

For the full values and environment variable reference, see MCP Server.

Connect a client

Point your MCP-capable client at the /mcp endpoint and include the bearer token if auth is enabled. See MCP Server for examples.

v1 Tool Surface

Read-only tools (default):

  • cluster_status (summary view; similar to console status).
  • cluster_metrics (S3 latency, produce/fetch RPS, admin error rates).
  • list_topics / describe_topics.
  • list_groups / describe_group.
  • fetch_offsets (consumer group offsets).
  • describe_configs (topic configs).

Mutation tools (future, gated by auth + RBAC):

  • create_topic / delete_topic.
  • create_partitions.
  • update_topic_config.
  • delete_group.
  • Broker control actions (drain/flush) via gRPC control plane.

Security and Guardrails

KafScale currently does not enforce auth on broker/admin APIs. For MCP, we must ship secure-by-default to avoid “one prompt away from prod changes”.

Requirements:

  • Strong auth (OIDC or short-lived tokens). No static shared secrets.
  • RBAC and allowlist tool sets (separate observe vs mutate).
  • Audit logs for every tool call (who/what/when + diff).
  • Dry-run mode for all mutations.
  • Environment fences (production requires explicit break-glass or approval).

See Security for the current security posture and roadmap; MCP should not enable any operations that bypass the auth/authorization roadmap there.