Conduktor MCP tools reference

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.

Using Conduktor

Insights

Conduktor MCP

Automate tasks

Manage Kafka resources

Monitor systems

Manage licenses

Govern data

Conduktor MCP tools reference

Permissions

Clusters

Topics

Messages

Schema Registry

Consumer groups

Kafka Connect

Access control and lineage

Self-service and Chargeback

Audit log

Insights

Gateway

Certificates

Analyze topics with aggregate-topics

How a request works

Parameters

Group topics

Aggregate a field

Filter topics

Keep only some groups

Internal topics

​Permissions

​Clusters

​Topics

​Messages

​Schema Registry

​Consumer groups

​Kafka Connect

​Access control and lineage

​Self-service and Chargeback

​Audit log

​Insights

​Gateway

​Certificates

​Analyze topics with aggregate-topics

​How a request works

​Parameters

​Group topics

​Aggregate a field

​Filter topics

​Keep only some groups

​Internal topics

Permissions

Clusters

Topics

Messages

Schema Registry

Consumer groups

Kafka Connect

Access control and lineage

Self-service and Chargeback

Audit log

Insights

Gateway

Certificates

Analyze topics with aggregate-topics

How a request works

Parameters

Group topics

Aggregate a field

Filter topics

Keep only some groups

Internal topics