list_consumers
Retrieve and manage all consumers associated with a specific control plane in Kong Konnect, with pagination support for handling large datasets.
Instructions
List all consumers associated with a control plane.
INPUT:
controlPlaneId: String - ID of the control plane
size: Number - Number of consumers to return (1-1000, default: 100)
offset: String (optional) - Pagination offset token from previous response
OUTPUT:
metadata: Object - Contains controlPlaneId, size, offset, nextOffset, totalCount
consumers: Array - List of consumers with details for each including:
consumerId: String - Unique identifier for the consumer
username: String - Username for this consumer
customId: String - Custom identifier for this consumer
tags: Array - Tags associated with the consumer
enabled: Boolean - Whether the consumer is enabled
metadata: Object - Creation and update timestamps
relatedTools: Array - List of related tools for consumer analysis
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| controlPlaneId | Yes | Control Plane ID (obtainable from list-control-planes tool) | |
| size | No | Number of consumers to return | |
| offset | No | Offset token for pagination (from previous response) |
Implementation Reference
- src/operations/configuration.ts:112-150 (handler)Core handler function that executes the list_consumers tool logic: calls the Kong API and transforms the raw response into a structured output with metadata, formatted consumers list, and related tools suggestions.
export async function listConsumers( api: KongApi, controlPlaneId: string, size = 100, offset?: string ) { try { const result = await api.listConsumers(controlPlaneId, size, offset); // Transform the response to have consistent field names return { metadata: { controlPlaneId: controlPlaneId, size: size, offset: offset || null, nextOffset: result.offset, totalCount: result.total }, consumers: result.data.map((consumer: any) => ({ consumerId: consumer.id, username: consumer.username, customId: consumer.custom_id, tags: consumer.tags, enabled: consumer.enabled, metadata: { createdAt: consumer.created_at, updatedAt: consumer.updated_at } })), relatedTools: [ "Use get-consumer-requests to analyze traffic for a specific consumer", "Use list-plugins to see plugins configured for these consumers", "Use query-api-requests to identify consumers with high error rates" ] }; } catch (error) { throw error; } } - src/tools.ts:49-55 (registration)Tool specification registration in the tools() array, defining the method name, name, description prompt, parameters schema, and category for the list_consumers tool.
{ method: "list_consumers", name: "List Consumers", description: prompts.listConsumersPrompt(), parameters: parameters.listConsumersParameters(), category: "configuration" }, - src/parameters.ts:90-100 (schema)Zod schema defining the input parameters and validation for the list_consumers tool, including controlPlaneId, size, and optional offset.
export const listConsumersParameters = () => z.object({ controlPlaneId: z.string() .describe("Control Plane ID (obtainable from list-control-planes tool)"), size: z.number().int() .min(1).max(1000) .default(100) .describe("Number of consumers to return"), offset: z.string() .optional() .describe("Offset token for pagination (from previous response)"), }); - src/index.ts:92-98 (handler)MCP server tool handler dispatch case that routes list_consumers tool invocations to the configuration.listConsumers handler.
case "list_consumers": result = await configuration.listConsumers( this.api, args.controlPlaneId, args.size, args.offset ); - src/api.ts:172-180 (helper)Low-level API helper that constructs and executes the HTTP request to Kong's consumers list endpoint.
async listConsumers(controlPlaneId: string, size = 100, offset?: string): Promise<any> { let endpoint = `/control-planes/${controlPlaneId}/core-entities/consumers?size=${size}`; if (offset) { endpoint += `&offset=${offset}`; } return this.kongRequest<any>(endpoint); }