Control MCP tool access with Consumer and Consumer Group ACLs

Uses: Kong Gateway AI Gateway Insomnia deck

Deployment Platform

konnect

on-prem

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'
```
Copied!

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 -e KONG_STATUS_LISTEN=0.0.0.0:8100 --deck-output

Copied!

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'

Copied!

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'

Copied!

Run the quickstart script:

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

Copied!

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

 Kong Gateway Ready

Insomnia

Download and install Insomnia.

Insomnia

Download and install Insomnia.

decK v1.43+

decK is a CLI tool for managing Kong Gateway declaratively with state files. To complete this tutorial, install decK version 1.43 or later.

This guide uses deck gateway apply, which directly applies entity configuration to your Gateway instance. We recommend upgrading your decK installation to take advantage of this tool.

You can check your current decK version with deck version.

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: mcp-acl-service
    url: http://host.docker.internal:3001/mcp
routes:
  - name: mcp-acl-route
    paths:
    - "/mcp"
    service:
      name: mcp-acl-service
' | deck gateway apply -

Copied!

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

Mock API Server

Before using the AI MCP Proxy plugin, you need an upstream MCP-compatible HTTP server to expose. For this tutorial, we’ll use a simple Express-based MCP server that simulates a marketplace system. It provides read-only access to sample users and their orders.

The server exposes a single /mcp endpoint and registers tools instead of REST routes, including:

list_users
get_user
list_orders
list_orders_for_user
search_orders

These tools operate on in-memory marketplace data, allowing you to test MCP behavior without connecting to a real backend.

Run the following command to clone the repository, install dependencies, build the server, and start it:

git clone https://github.com/tomek-labuk/marketplace-acl.git && \
cd marketplace-acl && \
npm install && \
npm run build && \
node dist/server.js

Copied!

When the server starts, it listens at:

http://localhost:3001/mcp

Copied!

Set up Consumer authentication

Let’s configure authentication so the Kong Gateway can identify each caller. We’ll use the Key Auth plugin so each user (or AI agent) presents an API key with requests:

echo '
_format_version: "3.0"
plugins:
  - name: key-auth
    route: mcp-acl-route
    config:
      key_names:
      - apikey
' | deck gateway apply -

Copied!

Create Consumer Groups for each AI usage tier

Now, let’s configure Consumer Groups that reflect access levels. These groups govern MCP tool permissions:

admin - full access
developer - limited access
suspended - blocked from MCP tools

echo '
_format_version: "3.0"
consumer_groups:
  - name: admin
  - name: developer
  - name: suspended
' | deck gateway apply -

Copied!

Create Consumers

Let’s configure individual Consumers and assign them to groups. Each Consumer will use a unique API key and inherits group permissions which will govern access to MCP tools:

echo '
_format_version: "3.0"
consumers:
  - username: alice
    groups:
    - name: admin
    keyauth_credentials:
    - key: alice-key
  - username: bob
    groups:
    - name: developer
    keyauth_credentials:
    - key: bob-key
  - username: carol
    groups:
    - name: suspended
    keyauth_credentials:
    - key: carol-key
  - username: eason
    keyauth_credentials:
    - key: eason-key
' | deck gateway apply -

Copied!

Configure the AI MCP Proxy plugin

Now, let’s configure the AI MCP Proxy plugin to apply tool-level access rules. The plugin controls which users or AI agents can see or call each MCP tool. Access is determined by Consumer Groups and individual Consumers using allow and deny lists. A tool ACL replaces the default rule when present.

The table below shows the effective permissions for the configuration:

MCP Tool	Admin group	Developer group	Eason consumer	Suspended group
`list_users`
`get_user`
`list_orders`
`list_orders_for_user`
`search_orders`

The following plugin configuration applies the ACL rules for the MCP tools shown in the table above:

echo '
_format_version: "3.0"
plugins:
  - name: ai-mcp-proxy
    route: mcp-acl-route
    config:
      mode: passthrough-listener
      include_consumer_groups: true
      default_acl:
      - scope: tools
        allow:
        - developer
        - admin
        deny:
        - suspended
      logging:
        log_payloads: false
        log_statistics: true
        log_audits: true
      tools:
      - description: List users
        name: list_users
        acl:
          allow:
          - admin
          - eason
          deny:
          - developer
      - description: Get user
        name: get_user
        acl:
          allow:
          - admin
          - developer
      - description: List orders
        name: list_orders
        acl:
          allow:
          - admin
          - developer
      - description: List orders for users
        name: list_orders_for_user
        acl:
          allow:
          - admin
          - developer
      - description: Search orders by name (case-insensitive substring)
        name: search_orders
        acl:
          allow:
          - admin
          deny:
          - developer
' | deck gateway apply -

Copied!

Validate the configuration

Let’s use Insomnia’s MCP Client feature to validate our ACL configuration:

Go to the Insomnia app.
Click Create MCP Client in the left sidebar.
Enter the preferred name and click Create.
In the HTTP field enter http://localhost:8000/mcp.
Go to the Auth tab.
Select API Key from the Auth type dropdown.

Now let’s verify access for each user by connecting with their API key:

Enter apikey in the Key field.
Enter alice-key in the Value field.
Click the Connect button.
Once connected, Insomnia should list these tools in the sidebar:
```
list_users
get_user
list_orders
list_orders_for_user
search_orders
```
Copied!
Alice belongs to the admin group and has access to all tools.
Click Disconnect to switch to another user.

Enter apikey in the Key field.
Enter bob-key in the Value field.
Click the Connect button.
Once connected, Insomnia should list these tools in the sidebar:
```
get_user
list_orders
list_orders_for_user
```
Bob belongs to the developer group and is denied access to list_users.
Click Disconnect to update the key for the next user.

Enter apikey in the Key field.
Enter carol-key in the Value field.
Click the Connect button.
The connection should fail with a INVALID_PARAMS -32602 response.
Carol belongs to the suspended group, which is globally denied access to all tools.
Click Disconnect to switch to another user.

Enter apikey in the Key field.
Enter eason-key in the Value field.
Click the Connect button.
Once connected, Insomnia should list this tool in the sidebar:
```
list_users
```
Copied!

Eason is not part of any group but is explicitly allowed access to list_users in the tool’s ACL.

Click Disconnect after validation.

Next → 2. Observe MCP Traffic with Access Control Enabled

Control MCP tool access with Consumer and Consumer Group ACLs

Prerequisites

Kong Konnect

Kong Gateway running

Insomnia

Insomnia

decK v1.43+

Required entities

Mock API Server

Set up Consumer authentication

Create Consumer Groups for each AI usage tier

Create Consumers

Configure the AI MCP Proxy plugin

Validate the configuration

Help us make these docs great!

Still need help