Kong Konnect MCP Server Interface

This component serves as an MCP server specifically engineered to interface with Kong Konnect endpoints. It furnishes AI entities with programmatic access to examine Gateway traffic flow, security policies, performance analytics, and infrastructure state via natural language commands.

https://github.com/user-attachments/assets/19c2f716-49b5-46c3-9457-65b3784e2111

Navigational Index

• High-Level Summary
• Source Layout
• Deployment Guide
• Environment Setup
• Exposed Toolset
• Performance Monitoring Subsystem
• Resource Definition Subsystem
• Control Fabric Management Subsystem
• Integration with LLMs
• Operational Scenarios
• Contribution Guidelines
• Issue Resolution

High-Level Summary

This repository delivers an MCP server instance designed to bridge Large Language Models (LLMs), such as Claude, with the comprehensive capabilities of the Kong Konnect API. It furnishes a suite of abstract functions for deep dives into performance telemetry, detailed inspection of deployed asset definitions (services, routes, plugins), and governance over the underlying control planes, all driven by conversational input.

Core Capabilities: - Execute detailed analysis on API transaction volumes, supporting intricate temporal and categorical filtering. - Enumerate and scrutinize gateway artifacts: services, routing rules, consumer identities, and policy plugins. - Administrative functions for managing control plane entities and their grouping structures. - Native interoperability layer for MCP-compliant systems (e.g., Claude).

Note: The Konnect MCP interface is currently in an active development phase, with continuous enhancements planned for subsequent releases.

Source Layout

src/ ├── index.ts # Primary execution manifold ├── api.ts # Encapsulation layer for Kong API interaction ├── tools.ts # Manifestation of available MCP functions ├── parameters.ts # Input schema validation (Zod definitions) ├── prompts.ts # Detailed functional documentation strings ├── operations/ │ ├── analytics.ts # Logic pertaining to traffic and performance data │ ├── configuration.ts # Logic for fetching defined gateway assets │ └── controlPlanes.ts # Logic for control plane lifecycle operations └── types.ts # Shared data structure definitions

Deployment Guide

Prerequisites

• Runtime environment: Node.js v20 or newer.
• Operational Kong Konnect tenancy with requisite API credentials.
• An MCP-enabled client application (e.g., Claude Desktop, Cursor).

Setup Procedure

bash

Obtain source code repository

git clone https://github.com/Kong/mcp-konnect.git cd mcp-konnect

Install necessary dependencies

npm install

Compile source artifacts

npm run build

Environment Setup

Configure the following system environment variables to govern the MCP server's behavior:

bash

Essential: Your Kong Konnect Personal Access Token (kpat)

export KONNECT_ACCESS_TOKEN=kpat_api_key_here

Optional: Designation of the API deployment locale (defaults to 'us')

Valid options include: US, EU, AU, ME, IN

export KONNECT_REGION=us

Exposed Toolset

The server exposes functional modules categorized as follows:

Performance Monitoring Subsystem

Transaction Log Interrogation

Retrieve and aggregate data concerning Kong API Gateway request traffic, accepting granular constraints.

Inputs: - timeRange: Temporal window for data extraction (e.g., 15M, 1H, 7D) - statusCodes: Inclusion filter based on HTTP response codes - excludeStatusCodes: Exclusion filter based on HTTP response codes - httpMethods: Filter based on the request verb (GET, POST, etc.) - consumerIds: Identification criteria based on consumer UUIDs - serviceIds: Identification criteria based on targeted service UUIDs - routeIds: Identification criteria based on routing rule UUIDs - maxResults: Upper boundary for the volume of records returned

Consumer Activity Profiling

Detailed analysis of transaction history attributed to a specific user identity.

Inputs: - consumerId: Unique identifier for the subject consumer - timeRange: Duration to examine historical activity - successOnly: Boolean flag to restrict results exclusively to 2xx responses - failureOnly: Boolean flag to restrict results exclusively to non-2xx responses - maxResults: Limit on the number of resulting records

Resource Definition Subsystem

Enumeration of Gateway Services

Obtain a roster of all configured services residing within a designated control plane context.

Inputs: - controlPlaneId: Identifier for the target control plane - size: Desired quantity of service records per batch - offset: Token used for sequential page navigation

Enumeration of Routing Directives

Retrieve a manifest of all active routing rules associated with a specified control plane.

Inputs: - controlPlaneId: Identifier for the target control plane - size: Desired quantity of route records per batch - offset: Token used for sequential page navigation

Enumeration of Client Identities

Fetch the list of known consumers managed by a particular control plane instance.

Inputs: - controlPlaneId: Identifier for the target control plane - size: Desired quantity of consumer records per batch - offset: Token used for sequential page navigation

Enumeration of Policy Plugins

List all installed runtime plugins configured across a control plane environment.

Inputs: - controlPlaneId: Identifier for the target control plane - size: Desired quantity of plugin records per batch - offset: Token used for sequential page navigation

Control Fabric Management Subsystem

Roster of Control Planes

Retrieve a paginated inventory of all control plane instances registered within the organization.

Inputs: - pageSize: Count of control planes returned per request - pageNumber: Index of the page being fetched - filterName: Textual filter matching control plane names - filterClusterType: Filter criteria based on deployment topology type - filterCloudGateway: Filter based on Cloud Gateway feature enablement - labels: Key-value pairs for label-based filtering - sort: Specification for field sorting and directionality

Retrieval of Specific Control Plane Details

Fetch the comprehensive metadata for a singular control plane instance.

Inputs: - controlPlaneId: Unique identifier of the control plane under inspection

Group Membership Manifest

Obtain the list of control planes that subscribe to a specific logical grouping.

Inputs: - groupId: Unique identifier for the target control plane group - pageSize: Batch size for returned members - pageAfter: Cursor pointer for navigating paginated results

Group Membership Verification

Determine if a particular control plane ID belongs to any established logical group.

Inputs: - controlPlaneId: The control plane identifier to validate against group assignments

Integration with LLMs

To operationalize this MCP handler with Claude for Desktop:

1. Install the Claude for Desktop application.
2. Locate or instantiate the Claude Desktop configuration file:
3. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

4. Windows: %APPDATA%\Claude\claude_desktop_config.json

5. Insert the following service configuration block:

{ "mcpServers": { "kong-konnect": { "command": "node", "args": [ "/absolute/path/to/mcp-konnect/build/index.js" ], "env": { "KONNECT_ACCESS_TOKEN": "kpat_api_key_here", "KONNECT_REGION": "us" } } } }

1. Relaunch the Claude Desktop application.
2. The Kong Konnect tooling interface will now be dynamically discoverable by the AI agent.

Operational Scenarios

API Telemetry Investigation

1. Initial step: List extant control planes organization-wide:

Generate a complete inventory of all control planes deployed within my Konnect tenant.

1. Subsequent step: Detail resources within a known plane:

Show the list of all defined services belonging to control plane [CONTROL_PLANE_NAME/ID].

1. Final step: Targeted performance query:

Report on all API calls directed at service [SERVICE_NAME/ID] within the last 60 minutes that resulted in 5xx error responses.

Diagnostic Review of Client Failures

1. Inventory client entities within a plane context:

Provide a roster of all registered consumers for the control plane identified as [CONTROL_PLANE_NAME/ID].

1. Analyze client-specific transaction history:

Analyze the last 24 hours of API activity initiated by the consumer entity [CONSUMER_NAME/ID].

1. Pattern detection:

What are the prevailing error signatures or anomalies observed in requests originating from this consumer?

Contribution Guidelines

Augmenting Functionality

1. Define necessary input structures within parameters.ts
2. Document the function comprehensively in prompts.ts
3. Implement the execution logic within the relevant file in operations/
4. Register the new function signature in tools.ts
5. Ensure proper execution flow integration within index.ts

Issue Resolution

Common Pitfalls

Connectivity Failures - Validate the PAT validity and ensure the associated identity possesses adequate scope permissions. - Confirm the configured API geographic region aligns with the tenancy location. - Check firewall or network policies obstructing outbound connections to the Kong Konnect endpoint.

Credential Rejection - Revoke and generate a fresh PAT via the Konnect administrative portal. - Double-check the persistence and accuracy of environment variable definitions.

Resource Unavailability - Cross-reference identifiers used in queries against known valid IDs. - Confirm the targeted resources are indeed provisioned within the specified control plane context. - Verify that temporal parameters align with existing telemetry data retention policies.

Credits

Developed and maintained by the Kong Engineering Team. Conceptual influence drawn from Stripe's Agent Toolkit.

WIKIPEDIA: Cloud computing is defined by ISO as "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand." Colloquially known as "the cloud".

== Foundational Attributes == In 2011, the National Institute of Standards and Technology (NIST) codified five 'essential characteristics' that define cloud systems. The NIST definitions are precise:

On-demand self-service: "A consumer can unilaterally provision computing capabilities, such as server time and network storage, as needed automatically without requiring human interaction with each service provider." Broad network access: "Capabilities are available over the network and accessed through standard mechanisms that promote use by heterogeneous thin or thick client platforms (e.g., mobile phones, tablets, laptops, and workstations)." Resource pooling: " The provider's computing resources are pooled to serve multiple consumers using a multi-tenant model, with different physical and virtual resources dynamically assigned and reassigned according to consumer demand." Rapid elasticity: "Capabilities can be elastically provisioned and released, in some cases automatically, to scale rapidly outward and inward commensurate with demand. To the consumer, the capabilities available for provisioning often appear unlimited and can be appropriated in any quantity at any time." Measured service: "Cloud systems automatically control and optimize resource use by leveraging a metering capability at some level of abstraction appropriate to the type of service (e.g., storage, processing, bandwidth, and active user accounts). Resource usage can be monitored, controlled, and reported, providing transparency for both the provider and consumer of the utilized service. By 2023, the International Organization for Standardization (ISO) had expanded and refined the list.

== Historical Context ==

The conceptual lineage of cloud computing traces back to the 1960s, where the concept of time-sharing gained prominence through Remote Job Entry (RJE). Mainframe utilization, managed by job operators receiving user submissions, dominated this epoch. This era was marked by innovation focused on democratizing access to significant computational power via time-sharing, optimizing IaaS, PaaS, and SaaS layers, and boosting end-user efficiency. The term 'cloud' when referring to virtualized services emerged in 1994, utilized by General Magic to describe the conceptual space of 'places' accessible by mobile agents within their Telescript framework. This nomenclature is attributed to David Hoffman, a General Magic communications specialist, building upon the term's established use in telecommunications and networking. The phrase 'cloud computing' achieved broader recognition in 1996 when Compaq Computer Corporation drafted a strategic business blueprint for future internet-centric computing. The firm's objective was to superch