Kafka MCP

Overview Schema Source Related Servers Discussions Admin

list_acls

List Kafka cluster ACL entries to diagnose authorization failures: filter by principal or resource to see allows, denies, prefixes, and wildcards.

Instructions

List the access control entries (ACLs) on the cluster this endpoint serves. Each entry has principal, host, resource_type, resource_name, pattern_type (literal, prefixed), operation (read, write, describe, ...) and permission (allow or deny). Results are sorted.

Use it when a client fails with TOPIC_AUTHORIZATION_FAILED, GROUP_AUTHORIZATION_FAILED or similar: filter by the client's principal, or by the resource it was refused on. Filtering by resource_name returns every ACL the broker applies to that name, including prefixed and wildcard entries, so the answer covers what actually decides access. A deny overrides any allow.

All filters are optional and combine. Fails with SECURITY_DISABLED when the broker has no authorizer, which means ACLs are not enforced at all. Needs DESCRIBE permission on the cluster.

Input Schema

TableJSON Schema

Name	Required	Description
`principal`	No	Optional principal to list ACLs for, including its type, such as User:payments. Matched exactly and case-sensitively. Omit for every principal.
`resource_name`	No	Optional resource name, such as a topic or group. Returns every ACL the broker applies to that name: the exact name, prefixed ACLs whose prefix it starts with, and the * wildcard. Case-sensitive. Needs resource_type.
`resource_type`	No	Optional resource type: topic, group, cluster, transactional_id or delegation_token. Case-insensitive. Omit for every type. Required when resource_name is given.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`acls`	Yes
`count`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Oct 7, 2026

TDQS

A4.8/5.0

Behavior5/5

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

No annotations exist, so the description carries the full burden and does so well: it discloses the DESCRIBE permission requirement on the cluster, the SECURITY_DISABLED failure mode meaning no authorizer is present, that results are sorted, and the semantic rule that a deny overrides any allow.

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 what the tool does, then usage, then caveats. Mostly every sentence earns its place, though phrasing like 'so the answer covers what actually decides access' is slightly wordy for the value it adds.

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

Completeness5/5

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

An output schema exists so return values need no explanation, and the description covers purpose, triggers, permission requirements, failure modes, and filter combination semantics. Nothing needed to invoke it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that resource_name matches exact, prefixed, and wildcard entries and requires resource_type, and that a deny overrides an allow. That goes beyond the field-level schema text.

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 (List) and resource (access control entries/ACLs) plus the exact fields each entry contains (principal, host, resource_type, resource_name, pattern_type, operation, permission). No sibling tool covers ACLs, so the agent can route to it unambiguously.

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

Usage Guidelines5/5

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

Gives an explicit trigger scenario (client fails with TOPIC_AUTHORIZATION_FAILED, GROUP_AUTHORIZATION_FAILED) and prescribes how to narrow: filter by the client's principal or by the refused resource. This is a concrete when-to-use with actionable filtering guidance.

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