Kong Konnect MCP server

This MCP server allows AI assistants to interact with Kong Konnect APIs, enabling you to query and analyze Gateway configurations, traffic patterns, and analytics data through natural language conversations.

Prerequisites

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

Installation

Setting Up the Server

# 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

Configure the server by setting these environment variables:

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

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

Integrating 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

Available Tools

Analytics Tools

Query API Requests

Inputs:
- timeRange: Time range for data (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

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?
   

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

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.