Connect Akto with Kong

Monitor and secure all incoming requests and outgoing responses from your AI agents and MCP (Model Context Protocol) servers running on Kong API Gateway. The akto-mcp-endpoint-shield plugin works for any agentic workload behind Kong — whether that's an MCP server handling tool calls, an AI agent API, an LLM-backed service, or any HTTP-based AI workload. It captures traffic flowing through Kong and sends it to Akto's guardrail service for real-time security analysis, visibility, and compliance monitoring.

Prerequisites

Before you begin, make sure you have:

• Kong Gateway 2.0 or later already running with your AI agent or MCP server registered as a Kong service/route

• Access to Kong's Admin API (default: http://localhost:8001)

• A server or Kubernetes cluster to host the Akto guardrail backend

• Your Akto API Token (go to Akto Argus → Connectors → Setup Guardrail card and copy your token)

---

Step 1: Install the Plugin in Kong

1

Download the Plugin Files

Clone the Akto Kong integration repository:

git clone https://github.com/akto-api-security/kong-integration.git
cd kong-integration

Inside the plugin/ directory you will find two files:

• handler.lua — plugin logic

• schema.lua — configuration schema

You only need these two files. Nothing else from the repository is required for the plugin itself.

2

Copy the Plugin Files into Kong

Create the plugin directory inside Kong and copy both files into it:

mkdir -p /usr/local/share/lua/5.1/kong/plugins/akto-mcp-endpoint-shield

cp plugin/handler.lua /usr/local/share/lua/5.1/kong/plugins/akto-mcp-endpoint-shield/
cp plugin/schema.lua  /usr/local/share/lua/5.1/kong/plugins/akto-mcp-endpoint-shield/

Using Docker? Mount the plugin directory as a volume instead:

volumes:
  - /path/to/kong-integration/plugin:/usr/local/share/lua/5.1/kong/plugins/akto-mcp-endpoint-shield:ro

3

Register the Plugin with Kong

Add akto-mcp-endpoint-shield to Kong's plugins list. How you do this depends on how Kong is configured:

Via kong.conf:

plugins = bundled,akto-mcp-endpoint-shield

Via environment variable:

KONG_PLUGINS=bundled,akto-mcp-endpoint-shield

If you are using Docker Compose, set this as an environment variable on the Kong service.

4

Restart Kong

kong restart

Or if using Docker:

docker compose restart kong

---

Step 2: Enable the Plugin on Your Service or Route

You can attach the plugin to a specific service, a specific route, or globally across all traffic.

Enable on a specific service (recommended — scopes monitoring to your AI agent or MCP service only):

curl -X POST http://localhost:8001/services/<YOUR_SERVICE_NAME>/plugins \
  --data "name=akto-mcp-endpoint-shield" \
  --data "config.service_url=http://<AKTO_GUARDRAIL_URL>" \
  --data "config.mode=async" \
  --data "config.timeout=15000"

Enable on a specific route:

curl -X POST http://localhost:8001/routes/<YOUR_ROUTE_NAME>/plugins \
  --data "name=akto-mcp-endpoint-shield" \
  --data "config.service_url=http://<AKTO_GUARDRAIL_URL>" \
  --data "config.mode=async" \
  --data "config.timeout=15000"

Enable globally (monitors all traffic through Kong):

curl -X POST http://localhost:8001/plugins \
  --data "name=akto-mcp-endpoint-shield" \
  --data "config.service_url=http://<AKTO_GUARDRAIL_URL>" \
  --data "config.mode=async" \
  --data "config.timeout=15000"

Replace <AKTO_GUARDRAIL_URL> with your guardrail service URL:

• If Akto provided you a URL (e.g., https://17*******0-guardrails.akto.io), use that directly.

• Otherwise, complete Step 3 to self-host the backend and use the URL you get from there.

Configuration Parameters

Parameter	Required	Description
service_url	Yes	Base URL of your deployed Akto guardrail backend (e.g., http://10.0.1.4:8080)
mode	Yes	async — non-blocking, logs traffic in background. blocked — validates request and response before serving, can return 403.
timeout	No	Request timeout in milliseconds. Default: 30000. Recommended minimum: 15000.

You can also configure the plugin via Kong Manager UI: go to Plugins → New Plugin → search for akto-mcp-endpoint-shield.

---

Step 3: Deploy the Akto Guardrail Backend

If you already have the Akto guardrail backend deployed (or have been given a service_url by your team), skip this step and use that URL directly in Step 2.

The guardrail backend is a set of services that receive traffic from the Kong plugin, run security checks, and ingest data for analysis. You can deploy it using Docker Compose (any Linux VM) or Helm (Kubernetes).

Option A: Docker Compose — Any Linux VM

This is the fastest way to get started. You need a Linux server with at least 4 vCPUs and 8 GB RAM.

The deployment files are available at: https://github.com/akto-api-security/infra/tree/feature/quick-setup/guardrail-service-e2e-setup

1

Clone the Setup Repository

git clone -b feature/quick-setup https://github.com/akto-api-security/infra.git
cd infra/guardrail-service-e2e-setup

2

Set Up Environment Files

Navigate into the docker-compose folder, then copy each template and fill in your Akto API token:

cd docker-compose

# Kafka IP (only variable substituted by docker-compose itself)
cp .env.example .env
# Edit .env — set AKTO_KAFKA_IP to your server's private IP

# Service env files — copy each template and replace <YOUR_AKTO_API_TOKEN>
cp docker-guardrails-service.env.template          docker-guardrails-service.env
cp docker-guardrails-service-kafka.env.template    docker-guardrails-service-kafka.env
cp docker-mini-runtime.env.template                docker-mini-runtime.env
cp data-ingestion-docker.env.template              data-ingestion-docker.env
cp docker-account-job-executor.env.template        docker-account-job-executor.env

Open each .env file you just created and replace every <YOUR_AKTO_API_TOKEN> with your token from the Akto dashboard (Settings → API Tokens).

Never publish .env files in the public — they contain your API token.

3

Start the Services

docker compose up -d

This starts the following services:

Service	Port	Purpose
zoo1	2181	ZooKeeper (Kafka coordination)
kafka1	9092	Kafka message broker
akto-api-security-runtime	—	Processes API traffic from Kafka
guardrails-service	9090	Async guardrails (Kafka-based)
guardrails-service-http	9091	Internal sync guardrails (called by data-ingestion-service)
data-ingestion-service	8080	Receives traffic, runs guardrails, and ingests data — this is the Kong plugin endpoint

4

Verify All Services Are Running

docker compose ps

All services should show status Up. If any are restarting, check their logs:

docker compose logs guardrails-service-http
docker compose logs data-ingestion-service

Test the guardrail service endpoint directly:

curl -sf http://localhost:9091/health && echo "guardrails OK"
curl -sf http://localhost:8080/health && echo "data-ingestion OK"

5

Update the Kong Plugin with the Service URL

Your guardrail service is now available at http://<YOUR_SERVER_IP>:8080. Update the Kong plugin configuration:

# Update an existing plugin (replace <PLUGIN_ID> with your plugin's ID)
curl -X PATCH http://localhost:8001/plugins/<PLUGIN_ID> \
  --data "config.service_url=http://<YOUR_SERVER_IP>:8080"

Or if you haven't enabled the plugin yet, use this URL in the Step 2 commands above.

If your Kong instance and guardrail server are on different networks, make sure port 8080 is accessible from the Kong host. If you want HTTPS, place a reverse proxy (nginx, Caddy) or load balancer in front of the guardrail service.

---

Option B: Kubernetes (Helm Charts)

Use this option if your infrastructure runs on Kubernetes.

1

Add the Akto Helm Repository

helm repo add akto https://akto-api-security.github.io/helm-charts
helm repo update

2

Install the Charts in Order

Deploy the following four charts in the exact order shown. Each chart depends on the previous one.

Chart 1 — Database Abstractor

Sets up the data access layer. After installing, retrieve the service token from your Akto dashboard.

helm install akto-database-abstractor akto/akto-setup-database-abstractor \
  -n <NAMESPACE> \
  --set mongo.aktoMongoConn="<MONGODB_CONNECTION_STRING>"

Chart 2 — Data Ingestion + Runtime

Processes and stores the traffic captured by the Kong plugin.

helm install akto-mrs-runtime-combined akto/akto-mrs-runtime-combined \
  -n <NAMESPACE> \
  --set mini_runtime.aktoApiSecurityRuntime.env.databaseAbstractorUrl="https://ultron.akto.io" \
  --set mini_runtime.aktoApiSecurityRuntime.env.databaseAbstractorToken="<YOUR_AKTO_API_TOKEN>" \
  --set mini_runtime.aktoApiSecurityRuntime.env.aktoLogLevel="INFO"

Chart 3 — Threat Backend

helm install akto-threat-backend akto/akto-threat-backend \
  -n <NAMESPACE> \
  --set mongo.aktoMongoConn="<MONGODB_CONNECTION_STRING>"

Chart 4 — AI Guardrails

helm install akto-ai-guardrails akto/akto-ai-guardrails \
  -n <NAMESPACE> \
  --set guardrailsService.env.aktoApiToken="<YOUR_AKTO_API_TOKEN>" \
  --set guardrailsService.env.aktoDbAbstractorHost="https://ultron.akto.io" \
  --set guardrailsService.env.aktoAgentGuardUrl="http://akto-ai-guardrails-executor:8092" \
  --set guardrailsService.env.aktoThreatDetectionHost="http://akto-threat-backend:8080" \
  --set guardrailsService.env.aktoLlmValidatorHost="https://ultron.akto.io" \
  --set guardrailsService.env.aktoIngestHost="http://akto-mrs-runtime-combined-data-ingestion-service:8080" \
  --set guardrailsService.env.logLevel="info" \
  --set agentGuardExecutor.enabled=true

3

Verify All Pods Are Running

kubectl get pods -n <NAMESPACE>

You should see pods for all four charts in Running status. If any pod is stuck in CrashLoopBackOff or Pending, check its logs:

kubectl logs -n <NAMESPACE> <POD_NAME>

4

Get the Guardrail Service URL

kubectl get services -n <NAMESPACE> | grep guardrails

Use the service's CLUSTER-IP (for in-cluster access) or set up an Ingress / LoadBalancer service for external access. Update the Kong plugin config.service_url with this URL.

---

How the Two Modes Work

	async	blocked
When guardrails run	After the response is sent to the client	Before the request reaches your AI agent or MCP server
Impact on latency	None — runs in background	Adds guardrail check latency to every request
Can block requests	No (logs only)	Yes — returns 403 if a request or response is flagged
Best for	Monitoring and visibility	Enforcing security policies

Start with async to monitor traffic without impacting your users. Switch to blocked once you've validated your guardrail rules.

---

Verify the Integration

After setup, send a test request through Kong (use the port Kong is listening on in your environment):

curl -X POST http://<KONG_HOST>:<KONG_PROXY_PORT>/<YOUR_ROUTE> \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Check Kong logs to confirm the plugin is active:

# Docker
docker compose logs kong | grep "\[akto\]"

# Kubernetes
kubectl logs -n <NAMESPACE> <KONG_POD_NAME> | grep "\[akto\]"

In async mode, you should see lines like:

[akto] ASYNC MODE — queuing ingest
[akto]   method : POST
[akto]   path   : /your-route
[akto] [async] sending to → http://<AKTO_GUARDRAIL_URL>/api/http-proxy?...
[akto] [async] ingest ok — guardrails passed

In blocked mode, the log will show each step: request check → upstream call → response check.

---

Troubleshooting

Plugin not loading after restart Verify that akto-mcp-endpoint-shield appears in KONG_PLUGINS and that both handler.lua and schema.lua are present in the correct directory. Run kong check to validate the configuration.

[akto] async ingest error: request failed: timeout The guardrail service is not reachable from Kong within the configured timeout. Check:

1. The config.service_url is correct and reachable from the Kong host

2. Firewall/NSG rules allow traffic on port 9091 (or your configured port)

3. Increase config.timeout (e.g., 15000 ms) if the service is reachable but slow on first connection due to SSL handshake

No [akto] lines in Kong logs The default Kong log level is warn. Plugin info messages only appear at info level. Set KONG_LOG_LEVEL=info in your Kong environment and restart.

blocked mode returns 500 / unexpected errors Confirm that kong.router.get_route() returns a valid route object. This happens when the plugin runs on a route that is properly registered via the Kong Admin API.

---

Get Support

• Raise an issue in the Kong Integration GitHub repository

• Contact the team via Slack or your assigned support channel

• For enterprise support, email the engineering team with your Kong version, plugin version, and relevant log snippets