Kafka MCP

Overview Schema Source Related Servers Discussions Admin

cluster_health

Checks Kafka cluster health in one call, reporting the controller, brokers, partition leadership, and unhealthy partitions with their issues; optionally filter topics or include internal topics.

Instructions

Check the health of the cluster this endpoint serves in one call: cluster id, controller, every broker (id, host, port, rack, and how many partitions it leads), a summary count, and every partition that is not fully healthy.

A problem partition lists its issues:

offline: no leader, so nothing can be produced to or consumed from it.
under_replicated: fewer in-sync replicas than replicas, so a broker is down or falling behind.
under_min_isr: fewer in-sync replicas than the topic's min.insync.replicas, so producers using acks=all fail with NOT_ENOUGH_REPLICAS.
error: the broker returned an error for the partition.

A problem partition with reassigning true is being moved between brokers; adding_replicas catch up before joining the ISR, so under_replicated there is expected while the move runs, not an outage.

healthy is true only when there are no problems. Use search to limit the check to topics whose name contains a substring (case-insensitive); internal topics are skipped unless include_internal is true. min_isr_unknown lists topics whose min.insync.replicas the broker did not report, so under_min_isr was not judged for them.

Input Schema

Name	Required	Description	Default
`search`	No	Optional case-insensitive substring that a topic name must contain to be checked. Omit to check every topic. Brokers and the controller are always reported.
`include_internal`	No	Optional. When true, also check Kafka's internal topics such as __consumer_offsets. Defaults to false. An unhealthy internal topic breaks every consumer group, so include them when groups fail across the board.

Output Schema

Name	Required	Description	Default
`brokers`	Yes
`healthy`	Yes
`summary`	Yes
`problems`	Yes
`warnings`	Yes
`cluster_id`	Yes
`controller`	Yes
`min_isr_unknown`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.2.7Oct 25, 2026

addedOutput schema / properties / problems / items / properties / adding_replicas

Added value: +{
+  "items": {
+    "maximum": 2147483647,
+    "minimum": -2147483648,
+    "type": "integer"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / problems / items / properties / reassigning
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / problems / items / properties / removing_replicas

Added value: +{
+  "items": {
+    "maximum": 2147483647,
+    "minimum": -2147483648,
+    "type": "integer"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

addedOutput schema / properties / summary / properties / reassigning
```
Added value: +{
+  "type": "integer"
+}
```

changedOutput schema / properties / summary / required

Previous value: -[
-  "topics",
-  "partitions",
-  "offline",
-  "under_replicated",
-  "under_min_isr",
-  "errored"
-]New value: +[
+  "topics",
+  "partitions",
+  "offline",
+  "under_replicated",
+  "under_min_isr",
+  "errored",
+  "reassigning"
+]

First observedv0.2.0Oct 7, 2026

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it explains what each problem flag means operationally, that acks=all producers fail with NOT_ENOUGH_REPLICAS, and that under_replicated during a reassignment is expected rather than an outage. It still never states explicitly that the call is read-only or comment on cost on large clusters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with a one-sentence summary of what one call returns, then a bulleted glossary of issue types that genuinely aids interpretation. The reassigning and min_isr_unknown paragraphs are useful but push the length past what an agent strictly needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter, fully optional-input diagnostic with an output schema, the definition covers interpretation of the results and edge cases (reassigning brokers, min_isr_unknown topics). Only the explicit read-only/no-side-effect assurance is missing, which matters given the absence of annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters are already described there with the same case-insensitive substring and default-false semantics, so the description largely restates the schema. The only added value is the 'brokers and the controller are always reported' scope note and the usage framing for include_internal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Check the health of the cluster') and immediately enumerates the payload (cluster id, controller, per-broker details, summary, problem partitions), which cleanly separates it from siblings like list_clusters or describe_topic.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete scoping guidance ('Use search to limit the check to topics whose name contains a substring') and a decision rule for internal topics (include them when consumer groups fail across the board). It never names a sibling alternative or states when a different tool would be a better choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.