> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conduktor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/guide/insights) data held by Console. To start using it, [connect an AI assistant](/guide/conduktor-in-production/automate/mcp/connect).

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](/guide/conduktor-concepts/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](/guide/conduktor-in-production/admin/set-up-rbac#govern-who-can-edit-labels-and-descriptions) 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](#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](/guide/insights#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:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](#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](#aggregate-a-field). |
| `filter` | No | Which topics to include, using the same filters as **query-topics**. See [filter topics](#filter-topics). |
| `having` | No | Keep only the groups whose computed value matches. See [keep only some groups](#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](#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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.