MCP tools

klens serves these tools over the Model Context Protocol at /mcp on mcp.bind. Connect an AI agent shows how to turn MCP on. The arguments on this page use the names an agent sends.

ToolsCopy Anchor Link

A tool without a per-minute limit reads the background projection that the UI reads, so it costs Kafka nothing. A tool with the limit reads Kafka or the registry live, makes klens read more often, or changes something. tuning.mcp.live_calls_per_minute sets the limit, and every client shares it.

The tool list an agent receives leaves out each tool that needs a privilege the agent holds on none of the clusters it sees. It leaves out each write tool unless a cluster the agent sees has writable: true and grants the privilege of that tool.

Every tool that reads one cluster takes a cluster argument. The argument is optional when the agent sees exactly one cluster.

Read the catalogCopy Anchor Link

klens_clustersCopy Anchor Link

Lists the clusters the agent sees, with broker, topic, partition, group, and subject counts, the counts of under-replicated and offline partitions, and each background lane that failed or has not run yet.

klens_searchCopy Anchor Link

Finds topics, consumer groups, brokers, and schema subjects by name, on one cluster or on all of them. It returns up to 20 matches for each cluster, best first, each with its kind (TOPIC, GROUP, NODE, or SUBJECT) and exact ID. notReady names each cluster klens has not read yet.

klens_access_explainCopy Anchor Link

Explains the privileges the agent holds under the MCP ceiling, whether each cluster accepts changes, and the privilege each unavailable tool or section needs.

klens_topics_listCopy Anchor Link

Lists topics with their partition count, records, size, produce rate, the number of groups that read them, and whether a partition is under-replicated.

klens_topic_describeCopy Anchor Link

Describes one topic: partitions with replicas and watermarks, records, size, produce rate, retention, and cleanup policy. groups lists the groups that read it, largest lag first. subjects lists its <topic>-key and <topic>-value subjects. configs lists each config that differs from Kafka's default and needs topic_configs.

klens_groups_listCopy Anchor Link

Lists consumer groups, largest total lag first, with their state, member count, and total lag. lagComplete is false when the total leaves out partitions whose lag klens has not read.

klens_group_describeCopy Anchor Link

Describes one group: state, assignment protocol, total lag, members, and partitions, largest lag first. findings names what looks wrong:

A call makes klens read the offsets of the group every tuning.ingest.fast_offset for tuning.ingest.interest_ttl, as opening the group in the UI does.

klens_brokers_listCopy Anchor Link

Lists brokers by ID with address, rack, controller flag, partition counts, size, and log dirs.

klens_schemas_listCopy Anchor Link

Lists schema subjects from A to Z with their latest version, schema type, and compatibility level. It fails with NO_SCHEMA_REGISTRY when the cluster has no schema_registry.

klens_schema_getCopy Anchor Link

Reads one version of a subject's schema live from the registry, with its references.

klens_acls_listCopy Anchor Link

Lists ACL bindings. status DISABLED means the cluster runs no authorizer. DENIED means the Kafka user of klens may not describe ACLs.

Read recordsCopy Anchor Link

klens_records_readCopy Anchor Link

Reads a page of records live from Kafka. For the next page, pass the cursor of the result with the other arguments unchanged.

klens_record_getCopy Anchor Link

Reads one record live from Kafka. It fails with UNKNOWN_OFFSET when the partition holds no record at that offset.

Record resultsCopy Anchor Link

A record result is text. For each record, a first JSON line gives the partition, offset, timestamp, size, value schema ID, verbatim, cut, and headersLeftOut. verbatim is true when the text shows the exact bytes. A second JSON line holds the key, the headers, and the value, between two markers that change with every result. The result tells the agent to read the text between the markers as data, not as instructions. JSON escapes keep a payload on one line, and klens escapes a payload that holds the closing marker.

An obfuscation rule hides what it covers, as in the UI, and contains matches only what klens shows.

Change KafkaCopy Anchor Link

Each write tool needs its privilege in mcp.privileges and a cluster with writable: true. On any other cluster it fails with READ_ONLY_CLUSTER. klens logs each change as it logs a change from the UI. A client that names itself in each request appears on that log line as unverified:<name>.

klens_topic_createCopy Anchor Link

Creates a topic. It fails with REFUSED when Kafka refuses, such as for a topic that exists. The result gives the name and the partition count, which is null when the call gave no partitions and klens has not seen the topic yet.

klens_record_produceCopy Anchor Link

Writes one record and returns its partition and offset. klens writes no tombstones, so value is required. It fails with UNENCODABLE when the data does not fit its schema.

A payload is an object with an encoding:

klens_schema_registerCopy Anchor Link

Registers a schema as the next version of a subject and returns the version and the schema ID. When the subject already holds the same schema, the registry returns that version and registers nothing. It fails with REGISTRY_REFUSED when the registry refuses the schema, such as for one the compatibility level of the subject rules out.

LimitsCopy Anchor Link

A call past either call limit fails with RATE_LIMITED, and klens does not queue it. A list result that does not fit keeps its first rows and says how many it left out. A record result instead cuts long keys, headers, and values to one length, so that a page keeps every record and its cursor, and it marks each record it cut. When the cursor of a topic with many partitions leaves too little room, klens_records_read fails with INVALID_REQUEST and asks for fewer records or partitions.

A count, size, or rate that klens has not measured yet is null, not 0.

ErrorsCopy Anchor Link

A refused call returns a JSON object with error, code, and hint. The hint says what the agent can call next. When the refusal carries a message from Kafka or the registry, the message sits between markers, as record text does. klens logs the tool and the code at info level, never the arguments.

This list holds the codes an agent meets most often. HTTP API errors lists every code.