Kong Konnect

mcp-konnect: A Model Context Protocol Server for Kong Konnect

What is mcp-konnect?

mcp-konnect is a Model Context Protocol (MCP) server designed to enable AI assistants, such as Claude, to interact with Kong Konnect APIs. It allows these AI assistants to query and analyze Kong Gateway configurations, traffic, and analytics data through natural language conversations.

How to use mcp-konnect?

To use mcp-konnect, you need to:

1. Prerequisites: Ensure you have Node.js 20+, a Kong Konnect account with API access, and an MCP-capable client (e.g., Claude Desktop).
2. Installation: Clone the repository, install dependencies (npm install), and build the project (npm run build).
3. Configuration: Set the KONNECT_ACCESS_TOKEN environment variable with your Kong Konnect API key. Optionally, set KONNECT_REGION.
4. Integration with AI Assistants: For Claude Desktop, configure the mcpServers section in your claude_desktop_config.json file, pointing to the index.js build file and providing your API key and region. Restart Claude Desktop to enable the tools.

Key Features of mcp-konnect

• API Gateway Interaction: Enables AI assistants to communicate with Kong Konnect APIs.
• Analytics Tools: Query and analyze Kong API Gateway requests with customizable filters (time range, status codes, HTTP methods, consumer/service/route IDs).
• Configuration Tools: List and inspect gateway services, routes, consumers, and plugins associated with a control plane.
• Control Planes Tools: List, get detailed information, and check memberships of control planes and control plane groups.
• Natural Language Interface: Allows AI assistants to query and manage Kong Konnect through conversational commands.
• Extensible: Designed for adding new tools and functionalities.

Use Cases of mcp-konnect

• Analyzing API Traffic: Querying API requests for specific services, filtering by status codes or time ranges to identify issues or trends.
• Troubleshooting Consumer Issues: Analyzing API requests made by specific consumers to diagnose problems or understand usage patterns.
• Monitoring Gateway Health: Gaining insights into the performance and configuration of your Kong Gateway instances.
• Automated Configuration Management: Potentially automating tasks like listing services or consumers through AI assistant commands.
• Developer Productivity: Empowering developers and operations teams to quickly retrieve information about their Kong Konnect environment using natural language.

FAQ from mcp-konnect

Q: What are the prerequisites for running mcp-konnect? A: You need Node.js 20 or higher, a Kong Konnect account with API access, and a client with MCP capabilities (e.g., Claude Desktop).

Q: How do I configure my Kong Konnect API key? A: You need to set the KONNECT_ACCESS_TOKEN environment variable with your Kong Konnect API key. Optionally, you can also set KONNECT_REGION.

Q: What should I do if I encounter connection or authentication errors? A: Verify your API key is valid and has necessary permissions, check the API region, ensure network connectivity to Kong Konnect API, and regenerate your API key if needed.

Q: What if the data I'm looking for is not found? A: Verify the IDs used in your requests are correct, ensure the resources exist in the specified control plane, and check that time ranges are valid for analytics queries.

Q: Can I add new tools to mcp-konnect? A: Yes, the project structure supports adding new tools by defining parameters, documentation, operation logic, and registering the tool.

Kong Konnect MCP Server

A Model Context Protocol (MCP) server for interacting with Kong Konnect APIs, allowing AI assistants to query and analyze Kong Gateway configurations, traffic, and analytics.

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

Table of Contents

• Overview
• Project Structure
• Installation
• Configuration
• Available Tools
  • Analytics Tools
  • Configuration Tools
  • Control Planes Tools
• Usage with Claude
• Example Workflows
• Development
• Troubleshooting

Overview

This project provides a Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Kong Konnect's API Gateway. It offers a set of tools to query analytics data, inspect configuration details, and manage control planes through natural language conversation.

Key features:

• Query API request analytics with customizable filters
• List and inspect gateway services, routes, consumers, and plugins
• Manage control planes and control plane groups
• Integration with Claude and other MCP-compatible AI assistants

Konnect MCP is a work in progress and we will be adding additional functionality and improvements with each release.

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

Installation

Prerequisites

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

Setup

# 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

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: The API region to use (defaults to US)
# Possible values: US, EU, AU, ME, IN
export KONNECT_REGION=us

Available Tools

The server provides tools organized in three categories:

Analytics Tools

Query API Requests

Query and analyze Kong API Gateway requests with customizable filters.

Inputs:
- 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

Get Consumer Requests

Analyze API requests made by a specific consumer.

Inputs:
- 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

List Services

List all services associated with a control plane.

Inputs:
- controlPlaneId: ID of the control plane
- size: Number of services to return
- offset: Pagination offset token

List Routes

List all routes associated with a control plane.

Inputs:
- controlPlaneId: ID of the control plane
- size: Number of routes to return
- offset: Pagination offset token

List Consumers

List all consumers associated with a control plane.

Inputs:
- controlPlaneId: ID of the control plane
- size: Number of consumers to return
- offset: Pagination offset token

List Plugins

List all plugins associated with a control plane.

Inputs:
- controlPlaneId: ID of the control plane
- size: Number of plugins to return
- offset: Pagination offset token

Control Planes Tools

List Control Planes

List all control planes in your organization.

Inputs:
- 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 capability
- labels: Filter by labels
- sort: Sort field and direction

Get Control Plane

Get detailed information about a specific control plane.

Inputs:
- controlPlaneId: ID of the control plane to retrieve

List Control Plane Group Memberships

List all control planes that are members of a specific group.

Inputs:
- groupId: Control plane group ID
- pageSize: Number of members to return per page
- pageAfter: Cursor for pagination

Check Control Plane Group Membership

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

Inputs:
- controlPlaneId: Control plane ID to check

Usage with Claude

To use this MCP server with Claude for Desktop:

1. Install Claude for Desktop

2. 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 the following 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
5. The Kong Konnect tools will now be available for Claude to use

Example Workflows

Analyzing API Traffic

1. First, list all control planes:

   Please list all control planes in my Kong Konnect organization.
   

2. Then, 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 for service [SERVICE_NAME/ID] in the last hour that had 5xx status codes.
   

Troubleshooting Consumer Issues

1. List consumers for a control plane:

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

2. Analyze requests for a specific consumer:

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

3. Check for common errors or patterns:

   What are the most common errors experienced by this consumer?
   

Development

Adding New Tools

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

Troubleshooting

Common Issues

Connection Errors

• Verify your API key is valid and has the necessary permissions
• Check that the API region is correctly specified
• 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 correctly set

Data Not Found

• Verify the IDs used in requests are correct
• Check that the resources exist in the specified control plane
• Ensure time ranges are valid for analytics queries

Credits

Built by Kong. Inspired by Stripe's Agent Toolkit.