Kong Konnect MCP Server

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

• 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

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

# 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

Analytics Tools

Query API Requests

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

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

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

List Routes

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

List Consumers

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

List Plugins

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

Control Planes Tools

List Control Planes

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

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

List Control Plane Group Memberships

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

Check Control Plane Group Membership

Inputs:
- controlPlaneId: Control plane ID to check

Usage with Claude

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

1. Restart Claude for Desktop
2. 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

• 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

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

• 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