mcp-konnect

Kong MCP-Konnect Project Detailed Introduction

Project Overview

Kong MCP-Konnect is a server project based on the Model Context Protocol (MCP) that allows AI assistants to query and analyze Kong Gateway configurations, traffic, and analytics data. This project enables AI assistants like Claude to interact with Kong Konnect's API gateway using natural language.

Core Features

• API Request Analytics Querying: Supports API request analytics with custom filters.
• Gateway Configuration Management: Lists and inspects gateway services, routes, consumers, and plugins.
• Control Plane Management: Manages control planes and control plane groups.
• AI Assistant Integration: Integrates with Claude and other MCP-compatible AI assistants.

Project Structure

src/
├── index.ts            # Main entry point
├── api.ts             # Kong API client
├── tools.ts           # Tool definitions
├── parameters.ts      # Zod schemas for tool parameters
├── prompts.ts         # Detailed tool documentation
├── operations/
│   ├── analytics.ts   # API request analytics operations
│   ├── configuration.ts # Services, routes, consumers, plugins
│   └── controlPlanes.ts # Control plane management
└── types.ts           # Common type definitions

System Requirements

• Node.js 20 or higher
• Kong Konnect account with API access
• MCP-enabled client (e.g., Claude Desktop, Cursor, etc.)

Installation and Configuration

1. Clone and Install

# Clone the repository
git clone https://github.com/Kong/mcp-konnect.git
cd mcp-konnect

# Install dependencies
npm install

# Build the project
npm run build

2. Environment Configuration

Set the following environment variables to configure the MCP server:

# Required: Your Kong Konnect API key
export KONNECT_ACCESS_TOKEN=kpat_api_key_here

# Optional: API region to use (defaults to US)
# Possible values: US, EU, AU, ME, IN
export KONNECT_REGION=us

Available Tools

Analytics Tools

1. API Request Analytics (analyze-api-requests)

Queries and analyzes Kong API gateway requests, supporting custom filters.

Input Parameters:

• timeRange: Time range for data retrieval (15M, 1H, 6H, 12H, 24H, 7D)
• statusCodes: Filter by specific HTTP status codes
• excludeStatusCodes: Exclude specific HTTP status codes
• httpMethods: Filter by HTTP methods
• consumerIds: Filter by consumer IDs
• serviceIds: Filter by service IDs
• routeIds: Filter by route IDs
• maxResults: Maximum number of results to return

2. Consumer Request Analytics (analyze-consumer-requests)

Analyzes API requests made by a specific consumer.

Input Parameters:

• consumerId: ID of the consumer to analyze
• timeRange: Time range for data retrieval
• successOnly: Show only successful (2xx) requests
• failureOnly: Show only failed (non-2xx) requests
• maxResults: Maximum number of results to return

Configuration Tools

1. List Services (list-services)

Lists all services associated with a control plane.

Input Parameters:

• controlPlaneId: Control plane ID
• size: Number of services to return
• offset: Pagination offset token

2. List Routes (list-routes)

Lists all routes associated with a control plane.

3. List Consumers (list-consumers)

Lists all consumers associated with a control plane.

4. List Plugins (list-plugins)

Lists all plugins associated with a control plane.

Control Plane Management Tools

1. List Control Planes (list-control-planes)

Lists all control planes in the organization.

Input Parameters:

• pageSize: Number of control planes per page
• pageNumber: Page number to retrieve
• filterName: Filter control planes by name
• filterClusterType: Filter by cluster type
• filterCloudGateway: Filter by cloud gateway functionality
• labels: Filter by labels
• sort: Sort field and direction

2. Get Control Plane (get-control-plane)

Retrieves detailed information about a specific control plane.

3. List Control Plane Group Members (list-control-plane-group-members)

Lists all control plane members of a specific group.

4. Check Control Plane Group Membership (check-control-plane-group-membership)

Checks if a control plane is a member of any group.

Integration with Claude

1. Install Claude for Desktop

Download and install Claude for Desktop from the Claude website.

2. Configure Claude Desktop

Create or edit the Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Add Configuration

{
  "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"
      }
    }
  }
}

4. Restart Claude for Desktop

After restarting, the Kong Konnect tools will be available for use with Claude.

Example Workflows

1. List All Control Planes

Please list all control planes in my Kong Konnect organization.

2. List Services for a Specific Control Plane

List all services for control plane [CONTROL_PLANE_NAME/ID].

3. Query API Requests for a Specific Service

Show me all API requests with 5xx status codes for service [SERVICE_NAME/ID] in the past hour.

4. List Consumers for a Control Plane

List all consumers for control plane [CONTROL_PLANE_NAME/ID].

5. Analyze Requests for a Specific Consumer

Show me all requests made by consumer [CONSUMER_NAME/ID] in the past 24 hours.

6. Check for Common Errors or Patterns

What are the most common errors encountered by this consumer?

Development Guide

To add a new tool, follow these steps:

1. Define parameters in parameters.ts
2. Add documentation in prompts.ts
3. Create operation logic in the appropriate file in operations/
4. Register the tool in tools.ts
5. Handle tool execution in index.ts

Troubleshooting

Connection Errors

• Verify your API key is valid and has the necessary permissions.
• Check that the API region is specified correctly.
• Ensure your network can connect to the Kong Konnect API.

Authentication Errors

• Regenerate your API key in the Kong Konnect portal.
• Check that environment variables are set correctly.

Data Not Found

• Verify that the IDs used in the request are correct.
• Check that the resource exists in the specified control plane.
• Ensure the time range for analytics queries is valid.

Summary

Kong MCP-Konnect is a powerful tool that bridges the gap between AI assistants and Kong API gateway management. By providing a natural language interface to query and analyze API gateway configurations, traffic, and analytics data, it makes API management more intuitive and efficient. The project offers a rich feature set, from basic configuration queries to advanced traffic analysis, making it an important tool for modern API infrastructure management.