Get started with Kong Konnect MCP Server

Uses: Kong Gateway AI Gateway decK

Deployment Platform:

Prerequisites

Kong Konnect

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

Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
Export your token to an environment variable:
```
 export KONNECT_TOKEN='YOUR_KONNECT_PAT'
```
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.

Kong Gateway running

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.

Export your license to an environment variable:

 export KONG_LICENSE_DATA='LICENSE-CONTENTS-GO-HERE'

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

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

Required entities

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:

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.

OpenAI

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'

Claude account and Claude desktop

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

Node.js

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.

Clone the repository:

 git clone https://github.com/Kong/mcp-konnect.git
 cd mcp-konnect

Use npm to install the required packages:
```
 npm install
```
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

Use this prompt to retrieve all control planes in your Konnect organization:

List all Control Planes in my Kong Konnect organization.

The following is a sample response from Kong MCP Server:

{
  "metadata": {
    "pageSize": 100,
    "pageNumber": 1,
    "filters": {
      "name": null,
      "clusterType": null,
      "cloudGateway": null,
      "labels": null
    },
    "sort": null
  },
  "controlPlanes": [
    {
      "controlPlaneId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "default",
      "description": "",
      "labels": {},
      "metadata": {
        "createdAt": "2022-10-06T23:54:23.695Z",
        "updatedAt": "2024-07-09T07:40:37.224Z"
      }
    }
  ]
}

List Services in a Control Plane

Once you’ve identified a control plane, ask Claude to list its services:

List all services for the quickstart Control Plane.

{
  "metadata": {
    "controlPlaneId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "size": 50,
    "offset": null
  },
  "services": [
    {
      "serviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "AIManagerModelService_1747139045696",
      "host": "localhost",
      "port": 80,
      "protocol": "http",
      "retries": 5,
      "connectTimeout": 60000,
      "writeTimeout": 60000,
      "readTimeout": 60000,
      "tags": [
        "ai-manager-created"
      ],
      "enabled": true,
      "metadata": {
        "createdAt": 1747139045,
        "updatedAt": 1747139045
      }
    },
    ...
  ],
  "relatedTools": [
    "Use list-routes to find routes that point to these services",
    "Use list-plugins to see plugins configured for these services"
  ]
}

Query API traffic for a Service

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

Show me all API requests for the example-service Gateway Service in the quickstart Control Plane in the last hour that had 5xx status codes.

{
  "requests": [
    {
      "requestId": "ca19e138bf16f1678e5ecb0f253aba37",
      "timestamp": "2025-05-16T05:19:11.332Z",
      "httpMethod": "GET",
      "uri": "/v1/ingest",
      "statusCode": "500",
      "consumerId": null,
      "serviceId": "986dc7ab-6238-48d8-b989-78c5f4910066:5050365a-faf2-4269-b53d-aff042b9178e",
      "routeId": "986dc7ab-6238-48d8-b989-78c5f4910066:1055be1b-1677-47da-ba62-c6d5f8c25b90",
      "latency": {
        "totalMs": 6,
        "gatewayMs": 0,
        "upstreamMs": 6
      },
      "clientIp": "205.234.240.66",
      "apiProduct": null,
      "apiProductVersion": null,
      "applicationId": null,
      "authType": "",
      "headers": {
        "host": "5a385ad748.eu.tp0.konghq.tech:443",
        "userAgent": ""
      },
      "dataPlane": {
        "nodeId": "986dc7ab-6238-48d8-b989-78c5f4910066:e4f2fa05-d918-4b53-8479-891157dc8499",
        "version": "3.11.0.0"
      },
      "controlPlane": {
        "id": "986dc7ab-6238-48d8-b989-78c5f4910066",
        "group": null
      }
      ...
    }
  ]
}

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

Clean up Kong Konnect environment

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.

Destroy the Kong Gateway container

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

FAQs

Why am I getting a connection error for the Konnect MCP server?

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.

Why am I seeing authentication errors for the Konnect MCP server?

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.

Why is my data not found when using the Konnect MCP server?

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.