Conduktor MCP tools reference

Reference for every Conduktor MCP tool: topics, messages, Schema Registry, consumer groups, Kafka Connect, ACLs, Chargeback, audit log and Insights.

The Conduktor Model Context Protocol (MCP) server covers Kafka resources, Schema Registry, Kafka Connect, access control, Self-service, Chargeback, the audit log and Insights data held by Console. To start using it, connect an AI assistant.

Most tools take a clusterSlug parameter that identifies the Kafka cluster to query. If you name a cluster in your question, the assistant normally uses it as the slug. Otherwise it calls list-clusters to find it. Tools that return lists are paged, so the assistant can request further pages when it needs them.

You don’t have to call tools or write their inputs yourself: the assistant picks the tools and builds the inputs from your question. The key inputs listed below help you phrase questions and check what the assistant did.

Permissions

Each tool runs with the permissions of the token you connect with:

• Tools that list resources only return the resources you have access to, and leave out the rest without an error.
• Tools that read a single resource fail if you don’t have access to it.
• get-chargeback-report returns every application to users with platform-wide Chargeback access. For other users, it only returns the applications they have Chargeback permissions on.
• list-service-accounts and get-service-account return every service account to users who can view the cluster’s Access Control Lists (ACLs). Other users only see the service accounts owned by application instances they have access to.
• set-topic-labels needs the same permission as editing topic labels in Console: View config on the topic or, when metadata governance is enabled, Manage metadata.

Clusters

Tool	Description	Key inputs
list-clusters	List the Kafka clusters managed by Console, with their slug, bootstrap servers, Schema Registry, Kafka Connect clusters and flavor (Gateway, Confluent, Aiven or plain Kafka).	None
get-cluster	Get the connection details of one cluster by its slug.	clusterSlug

Topics

Console offers four tools to find topics. The assistant picks one based on your question:

To…	The assistant uses
List topic names and configurations on a small cluster	list-topics
Browse topics sorted by size, activity or produce rate	list-topics-with-usage
Find the topics that match conditions, on any size of cluster	query-topics
Count or total topics per group, such as per team or per label	aggregate-topics

Tool	Description	Key inputs
list-topics	List topic configurations (partitions, replication factor and configs such as retention.ms and cleanup.policy), with labels and description. Includes internal topics. Best suited to small clusters.	None
get-topic	Get one topic’s configuration, labels and description.	topicName
list-topics-with-usage	List topics with usage metrics (message count, size, produce rate and last activity). Sort them, and filter by name, cleanup policy, label or tag, or hide internal and stream topics.	filter, sort
query-topics	Filter topics on any indexed attribute, such as replication factor, size, consumer count or days idle. Choose the fields to return, then sort and page through up to 1,000 topics at a time. Leaves out internal topics unless asked. Needs Insights.	filter, fields, sort, limit
aggregate-topics	Group topics and compute a count, sum, average, minimum or maximum for each group. For example, total storage per topic name prefix. Needs Insights. See Analyze topics with aggregate-topics.	groupBy, aggregation, aggregateField, filter, having
set-topic-labels	Add or update labels on a topic. Existing labels and the description are kept. Labels can’t use the reserved conduktor.io/ prefix.	topicName, labels

Messages

Tool	Description	Key inputs
get-last-messages	Get the newest records on a topic (up to 100), from all partitions or a subset, with their key, value, headers and metadata.	topicName, messageCount, partitions
get-record-at	Get one record at an exact partition and offset. Optionally, extract part of the value with a JQ-style projection, such as .customer.id.	topicName, partition, offset, valueJsonProjection

Schema Registry

Tool	Description	Key inputs
list-subject-names	List subject names with their latest version, schema ID, version count and format. Filter by name, ID or format (Avro, Protobuf or JSON Schema).	filter, sort
list-subjects	List subjects with their latest schema, format, compatibility mode and version.	None
get-subject	Get one subject’s latest schema, format, compatibility mode, version, schema ID and labels.	subjectName
get-schema-version	Get a specific version of a subject’s schema.	subjectName, version
check-schema-compatibility	Check whether a candidate schema is compatible with a subject, according to the subject’s compatibility mode. Nothing is registered.	subjectName, format, schema

Consumer groups

Tool	Description	Key inputs
list-consumer-groups	List consumer groups with their state, members, overall lag, topics read, maximum lag time, group type and labels. Filter by name, state, group type or label, and sort by any of these or by the number of topics read.	filter, sort
list-consumer-groups-by-topic	List the consumer groups reading from a topic, with their lag on it.	topicName
get-consumer-group	Get one consumer group’s members (client ID, host and partition assignments), and its committed offset, end offset and lag per partition.	consumerGroupName

Kafka Connect

Tool	Description	Key inputs
list-connectors-detailed	List connectors with their class, type, topics, state, running and failed task counts, error traces and labels. Filter by Kafka Connect cluster or connector name.	connectSlug, nameContains
get-connector	Get one connector’s configuration and the status of each of its tasks. Values of secret-looking keys, such as passwords and tokens, are redacted.	connectSlug, connectorName

Access control and lineage

Tool	Description	Key inputs
list-acl-bindings	List the cluster’s ACL bindings, read live from the brokers. Filter by principal, resource, operation or permission (Allow or Deny), and optionally group them per resource.	principal, resourceType, resourceName, operation, permission, groupByResource
list-service-accounts	List service accounts with their labels and owning application instance, and optionally their ACLs.	nameContains, applicationInstance, includeGrants
get-service-account	Get one service account with its owning application instance, labels, ACLs and Schema Registry ACLs.	name
get-stream-lineage	Get producer and consumer lineage derived from ACLs: who is allowed to write to and read from each topic, not observed traffic. Without a focus, it returns a summary of the most-used topics and principals. With a topic or service account, it returns the graph around it, up to eight hops and 200 nodes.	topic, serviceAccount, direction, hops, maxNodes

Self-service and Chargeback

Tool	Description	Key inputs
list-applications	List Self-service applications with their owner, labels and instances.	nameContains
get-chargeback-report	Get cost and usage per application (storage, throughput and cost) for a time window, by day or by month, with totals.	from, to, granularity, search

Audit log

Tool	Description	Key inputs
query-audit-log	Find out who did what to which resource, and when. Filter by cluster, user, resource, event type or time range, and optionally include each event’s before and after state. Returns the newest events first.	cluster, user, resourceType, resourceName, eventType, from, to, includeState

Insights

These tools are only available when Insights is enabled. See Disable Insights.

Tool	Description	Key inputs
insights-cluster	Get a cluster’s health score (0–100), its topic, partition and consumer group counts, the split between user, internal and stream topics, and the serialization formats in use.	None
insights-topics	Get the topics worth attention: the most valuable ones, low replication, high partition skew, uneven partition distribution, empty, stale and over-partitioned topics, and Self-service and schema coverage.	minSkewRatio

Gateway

Tool	Description	Key inputs
list-interceptors	List the Interceptors deployed on a Gateway cluster, with their plugin class, priority and configuration.	None

Certificates

Tool	Description	Key inputs
list-certificates	List the Transport Layer Security (TLS) certificates Console trusts, with their subject, issuer, serial number and validity dates. No key material is returned.	None

Analyze topics with aggregate-topics

aggregate-topics answers “how many” and “how much per X” questions about the topics on a cluster. It groups topics, then computes one figure per group: a count, or the sum, average, minimum or maximum of a numeric field. Because the work happens in Console, the assistant gets back a short list of totals instead of thousands of topic rows.

Use it to answer questions such as:

Question	How the assistant can answer it
How many topics does each team own?	Group by topicNamePrefix(.) and count.
Which teams use the most storage?	Group by label.team, sum storageBytes and sort by value.
How many topics per environment have a replication factor below three?	Group by label.env, filtered on replicationFactor less than 3.
What does retention look like across the cluster?	Group by retentionBucket and count.
How many stale topics does each application namespace own?	Group by topicNamePrefix(.,3), filtered on the stale named filter.
Which topic prefixes add up to more than 500 partitions?	Group by topicNamePrefix(-), sum partitions, keep groups greater than 500.
How much of the cluster has a schema, or is covered by Self-service?	Group by hasSchema or hasSelfServiceCoverage and count.

aggregate-topics needs Insights and only counts the topics your token can access.

How a request works

The assistant sends a request like this one, which totals storage per team, where the team is the first dot-separated segment of the topic name:

{
  "clusterSlug": "prod",
  "groupBy": ["topicNamePrefix(.)"],
  "aggregation": "sum",
  "aggregateField": "storageBytes",
  "sortBy": "value"
}

Console returns one bucket per group. In each bucket, key is the group, value is the computed figure and count is the number of topics in the group. totalCount is the number of groups.

{
  "buckets": [
    { "key": "payments", "value": 81604378624, "count": 42 },
    { "key": "orders", "value": 20401094656, "count": 118 },
    { "key": "inventory", "value": 5100273664, "count": 23 }
  ],
  "totalCount": 3
}

Parameters

Parameter	Required	Description
clusterSlug	Yes	The cluster to analyze.
groupBy	Yes	One or more fields to group by. See group topics.
aggregation	No	count (default), sum, avg, min or max.
aggregateField	For all but count	The numeric field to aggregate. See aggregate a field.
filter	No	Which topics to include, using the same filters as query-topics. See filter topics.
having	No	Keep only the groups whose computed value matches. See keep only some groups.
sortBy	No	Sort groups by key (default, ascending), value or count (both descending by default).
sortDesc	No	Set to true or false to override the default sort direction.
includeInternal	No	Include internal topics, which are left out by default. See internal topics.

Group topics

groupBy field	Groups topics by
topicName	Topic name: one group per topic.
topicNamePrefix(<sep>)	The part of the name before the first separator. The separator is one of - (default), ., /, : or _.
topicNamePrefix(<sep>,<segments>)	The first <segments> parts of the name, from one to 10. On a.b.c.d, topicNamePrefix(.) gives a and topicNamePrefix(.,3) gives a.b.c. A name with fewer parts is kept whole.
label.<key>	The value of a topic label, such as label.team. Topics without the label go in a <none> group.
classification	Topic type: USER, INTERNAL or STREAMS.
retentionBucket	Retention time: <1h, 1h-1d, 1d-7d, 7d-30d, >30d or infinite.
partitions, replicationFactor, minInSyncReplicas, consumerCount	The exact value of that setting or metric.
hasSchema, hasSelfServiceCoverage	Whether the topic has a schema, or belongs to a Self-service application: true or false.

Pass several fields to nest the groups. With "groupBy": ["label.team", "replicationFactor"], each bucket’s key is a list, such as ["payments", "3"].

If one prefix holds most of your topics, ask the assistant to group by more segments. For example, topicNamePrefix(.,2) splits payments.* into payments.cards, payments.refunds and so on.

Aggregate a field

sum, avg, min and max work on these fields:

Field	Description
storageBytes	Size of the topic, in bytes.
messageCount	Number of messages currently in the topic.
avgMessageSize	Average message size, in bytes.
partitions	Number of partitions.
replicationFactor	Replication factor.
minInSyncReplicas	The min.insync.replicas setting.
partitionSkew	How uneven the partition sizes are.
consumerCount	Number of consumer groups reading the topic.
idleDays	Days since the topic’s last activity.
retentionMs	Retention time, in milliseconds.

Filter topics

filter narrows down the topics before they’re grouped. It takes two lists of clauses:

• all: every clause has to match.
• any: at least one clause has to match.

When you use both, a topic has to match all of the all clauses and at least one of the any clauses. Add "negate": true to a clause to match the topics that don’t satisfy it.

A clause compares a field with a value, using an operator the field accepts:

Field	Operators	Value
topicName	eq, contains, in, notlike	Text
classification	eq, in, notin	USER, INTERNAL or STREAMS
replicationFactor, minInSyncReplicas, partitions, storageBytes, consumerCount, messageCount, avgMessageSize, idleDays, retentionMs	eq, lt, lte, gt, gte, between	Whole number
partitionSkew	eq, lt, lte, gt, gte, between	Decimal number
hasSchema, hasSelfServiceCoverage	eq	true or false
lastActivity	before, after, isnull	ISO-8601 date and time
label.<key>	eq, in, notin, isnull	Text

For between, give two comma-separated values, such as "10,100". For in and notin, give a comma-separated list.

Instead of a field, a clause can use a named filter:

Named filter	Matches
empty	Topics that have never been written to, or have no messages and have been idle for seven days or more.
stale	Topics that have data, have been idle for seven days or more and have no consumers.
tiny	Topics with more than one partition but less than 10 MB or fewer than 1,000 messages, excluding repartition topics.
vip	The most valuable topics: high consumer count, high message volume and recent activity.

For example, this filter keeps the stale topics that are larger than 1 GB:

{
  "all": [
    { "named": "stale" },
    { "field": "storageBytes", "op": "gt", "value": "1073741824" }
  ]
}

Keep only some groups

having filters the groups after the figures are computed. It takes an operator (eq, lt, lte, gt, gte or between) and a value. For example, to keep the prefixes with more than 100 topics:

{
  "groupBy": ["topicNamePrefix(-)"],
  "having": { "op": "gt", "value": "100" }
}

Internal topics

Internal topics are left out by default. These are Kafka’s and Conduktor’s own topics, topics whose name starts with an underscore, Kafka Connect topics and ksqlDB topics. To include them, ask about them explicitly so the assistant sets includeInternal to true, or filter on classification.

When a request returns no groups because internal topics were left out, the response says so, and the assistant can try again with them included.