Get started with Kong Konnect MCP Server

Uses: Kong Gateway AI Gateway decK
Incompatible with
on-prem
Related Resources
Minimum Version
Kong Gateway - 3.6
TL;DR

With Kong’s Model Context Protocol (MCP) Server, you can enable AI assistants like Claude to interact directly with Kong Konnect’s API Gateway. This integration allows you to query analytics data, inspect configuration details, and manage control planes—all through natural language conversation.

This tutorial will help you get started with MCP by connecting an AI assistant to Kong Konnect.

This quickstart is intended for experimentation with AI-assisted API management. Do not run it as-is in production.

Prerequisites

This is a Konnect tutorial and requires a Konnect personal access token.

  1. Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.

  2. Export your token to an environment variable:

     export KONNECT_TOKEN='YOUR_KONNECT_PAT'
    
  3. Run the quickstart script to automatically provision a Control Plane and Data Plane, and configure your environment:

     curl -Ls https://get.konghq.com/quickstart | bash -s -- -k $KONNECT_TOKEN --deck-output
    

    This sets up a Konnect Control Plane named quickstart, provisions a local Data Plane, and prints out the following environment variable exports:

     export DECK_KONNECT_TOKEN=$KONNECT_TOKEN
     export DECK_KONNECT_CONTROL_PLANE_NAME=quickstart
     export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
     export KONNECT_PROXY_URL='http://localhost:8000'
    

    Copy and paste these into your terminal to configure your session.

This tutorial requires Kong Gateway Enterprise. If you don’t have Kong Gateway set up yet, you can use the quickstart script with an enterprise license to get an instance of Kong Gateway running almost instantly.

  1. Export your license to an environment variable:

     export KONG_LICENSE_DATA='LICENSE-CONTENTS-GO-HERE'
    
  2. Run the quickstart script:

    curl -Ls https://get.konghq.com/quickstart | bash -s -- -e KONG_LICENSE_DATA 
    

    Once Kong Gateway is ready, you will see the following message:

     Kong Gateway Ready
    

decK is a CLI tool for managing Kong Gateway declaratively with state files. To complete this tutorial you will first need to install decK.

For this tutorial, you’ll need Kong Gateway entities, like Gateway Services and Routes, pre-configured. These entities are essential for Kong Gateway to function but installing them isn’t the focus of this guide. Follow these steps to pre-configure them:

  1. Run the following command:

    echo '
    _format_version: "3.0"
    services:
      - name: example-service
        url: http://httpbin.konghq.com/anything
    consumers:
      - username: example-consumer
    ' | deck gateway apply -
    

To learn more about entities, you can read our entities documentation.

This tutorial uses the AI Proxy plugin with OpenAI. You’ll need to create an OpenAI account and get an API key. Once you have your API key, create an environment variable:

export OPENAI_KEY='YOUR-API-KEY'

To complete this tutorial, you’ll need to have a Claude account and Claude desktop.

To use the Kong MCP Server, you’ll need Node.js 20.0 or later. Run node --version in your terminal to check your installed version.

Check that Kong Gateway is running

We’ll be using decK for this tutorial, so let’s check that Kong Gateway is running and that decK can access it:

deck gateway ping

If everything is running, then you should get the following response:

Successfully connected to Kong!
Kong version: 3.9.0.0
Successfully Konnected to the Kong organization!

Configure Kong MCP Server

To get started with Kong MCP server, first clone the repository and install dependencies.

  1. Clone the repository:

     git clone https://github.com/Kong/mcp-konnect.git
     cd mcp-konnect
    
  2. Use npm to install the required packages:

     npm install
    
  3. Compile the MCP server:

     npm run build
    

Configure Claude desktop

Claude uses a configuration file to register custom MCP servers. You’ll need to create this file based on your operating system:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Now, add the following configuration to the file:

{
  "mcpServers": {
    "kong-konnect": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-konnect/build/index.js"
      ],
      "env": {
        "KONNECT_ACCESS_TOKEN": "YOUR_KONNECT_PAT",
        "KONNECT_REGION": "us"
      }
    }
  }
}
  • Replace /absolute/path/to/mcp-konnect/build/index.js with the full path to your local MCP server build.
  • Make sure the KONNECT_ACCESS_TOKEN matches the one you set earlier.
  • Replace the KONNECT_REGION value with your geographic region. You can see a list of all Konnect regions in the Geographic regions documentation.

Restart Claude desktop

After saving the claude_desktop_config.json file, restart Claude for Desktop. The Kong Kong Konnect tools will now be available for Claude to use in conversation.

Analyze API traffic using Claude and Kong MCP Server

Now that you’ve configured Claude Desktop with the Konnect MCP server, you can analyze API traffic.

List all Control Planes

List Services in a Control Plane

Query API traffic for a Service

To analyze traffic and detect error trends, run a query like this:

Troubleshoot Consumer issues

List Consumers in a Control Plane

Start by getting the list of consumers for a control plane:

List all Consumers for the quickstart Control Plane.

Analyze requests by a specific Consumer

To view traffic made by a specific Consumer in the last 24 hours:

Show me all requests made by the example-consumer Consumer in the last 24 hours.

Identify common errors for a Consumer

Ask Claude to identify frequent issues experienced by that Consumer:

What are the most common errors experienced by this Consumer?

Cleanup

If you created a new control plane and want to conserve your free trial credits or avoid unnecessary charges, delete the new control plane used in this tutorial.

curl -Ls https://get.konghq.com/quickstart | bash -s -- -d

FAQs

  • Verify your API key is valid and has the necessary permissions.
  • Check the API region is correctly specified (KONNECT_REGION).
  • Ensure network access to the Kong Kong Konnect API is not blocked by a firewall or proxy.
  • Regenerate your API key from the Kong Kong Konnect portal if it’s expired or revoked.
  • Confirm environment variables like KONNECT_ACCESS_TOKEN are set and available to the process.
  • Check resource IDs used in your request (e.g., control plane or service IDs).
  • Ensure the resources exist in the correct control plane and region.
  • Validate time ranges used in analytics queries to ensure they cover a period with data.
Something wrong?

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!