Skip to main content
Glama
kong-ai-gateway-mcp

kong-ai-gateway-mcp

by Iqram09

Kong AI Gateway Diagnostics

An MCP server that lets an LLM agent investigate a Kong Gateway through fourteen read-only, bounded, schema-validated tools, with a deterministic diagnostic engine producing the facts, a bounded agent loop producing the explanation, and an evaluation harness measuring whether it works.

User:   Why is authentication failing on /payments?

Agent:  find_route_by_path({"path":"/payments"})        ->  route:payments-prod
Agent:  diagnose_route({"route":"route:payments-prod"})   ->  NO_AUTH_PLUGIN (HIGH), CONFIRMED

Agent:  Authentication is not failing on /payments because no authentication plugin
        is attached or enabled for that route at all. Kong is passing every request
        through without requiring credentials. [evidence, next steps, limitations]

        3 steps · 2 tool calls · 12,977 tokens · $0.0046 · 5.0 s

Kong is the source of truth. The model selects tools, sequences the investigation and writes the explanation; it never produces a fact.

Status: a working reference implementation, verified against a local Kong 3.9.3 and the live Gemini API. It is not deployed anywhere and has not been used in production.


Problem

Debugging an API gateway is a sequence of narrow questions against a large, structured configuration: which route serves this path, which service does it point to, which plugins actually apply once you account for scope precedence, is the upstream healthy, does this consumer hold the credential the route requires. Each question is a specific Admin API call. The failure modes are not exotic -- a disabled plugin that still shows in the UI, a route attached to the wrong service, a 503 that means "wrong address" rather than "backend down" -- but they are easy to miss when eyeballing JSON, and the obvious first hypothesis is often wrong.

An LLM is good at sequencing an investigation from a vague description. It is bad at being trusted with infrastructure state. This project is about getting the first property without paying for the second.

Related MCP server: mnm-incident-investigator

Why MCP?

The Model Context Protocol gives the model a fixed vocabulary of operations, each with a schema, a description of when to use it, and a bounded result -- instead of an HTTP client and a URL. That makes the entire attack and blast surface enumerable (see src/mcp/registry.ts), lets the same tools serve any MCP client and this repository's own agent from one definition, and puts a protocol-enforced validation boundary between the model and the gateway. There is deliberately no execute_kong_api_call tool and never will be (decisions.md).

Architecture

flowchart LR
    Client["AI client<br/>(Claude Desktop, IDE, or npm run agent)"]
    subgraph S["kong-ai-gateway-mcp"]
        direction TB
        MCP["MCP tools (14, read-only)"]
        Ctx["Context management<br/>references · summaries · limits"]
        Diag["Diagnostic engine<br/>evidence collector · pure rules"]
        Kong["Kong client<br/>typed · GET only · bounded"]
        Safety["Safety: permissions · audit"]
        Tel["Telemetry: logs · metrics · cost"]
        MCP --> Ctx --> Diag --> Kong
        MCP -.-> Safety
        MCP -.-> Tel
    end
    subgraph A["Agent + evaluation (needs an LLM key)"]
        Loop["Bounded agent loop"] --> Prov["LLM provider interface"] --> Gem["Gemini provider"]
        Eval["Evaluation harness<br/>28 cases · deterministic scorer"] --> Loop
    end
    Client -- MCP / stdio --> MCP
    Loop -- in-process --> MCP
    Kong -- Admin API --> KG[(Kong 3.9<br/>+ Postgres)]
    Gem --> API[(Gemini API)]

The tool layer runs without any LLM. Full component map, data flow and responsibilities in docs/architecture.md.

Features

  • MCP tooling -- 14 tools on the official TypeScript SDK v2 (@modelcontextprotocol/server): find_route_by_path, get_route, get_service, list_services, list_routes_for_service, list_plugins_for_route, list_global_plugins, get_consumer, list_consumers, list_upstreams, check_upstream_health, diff_config, diagnose_route, explain_auth_failure. Every description states what the tool does, when to use it, what it returns, and its limits.

  • Kong integration -- a typed client with explicit methods only, Zod-validated responses, a stable error taxonomy, response and page-count ceilings, and credential values stripped at the boundary. Kong is treated as authoritative.

  • Deterministic diagnostics -- eleven pure rules over an evidence bundle that can only be filled from Kong. Absence is asserted only when every relevant scope was read. Runs in ~64 ms with no model. Detects all ten seeded defects and reports the healthy control as clean.

  • Agentic investigation -- a loop this project owns (not the SDK's), with a step limit, identical-call detection, a cumulative context budget, and a halt path that produces an explicit "diagnosis incomplete" rather than a guess.

  • Context management -- references instead of embedded entities, allowlisted plugin config projection, announced truncation, cursor pagination written for a model, progressive and conditional collection. Measured: a single-route diagnosis is 11% of the raw configuration dump.

  • Safety controls -- no write method exists in src/; write tools are gated at registration; the server refuses to start with ENABLE_WRITE_TOOLS=true because none are implemented; secrets are stopped at each boundary they cross, with a test for each.

  • Evaluation -- 28 cases, three difficulties, varied phrasings, false-positive controls, a deterministic scorer with no LLM judge, quota-aware and resumable runs, JSON and Markdown reports.

  • Observability -- structured JSON logs (stderr only; stdout is the protocol), per-call telemetry with three correlation ids, a separate audit log, nearest-rank percentiles, provider-reported tokens, and cost that says "unavailable" rather than guessing.

  • Provider abstraction -- one-method LlmProvider interface; @google/genai imported in exactly one file; two Gemini-specific protocol requirements discovered during development were absorbed without touching the agent, tools or evaluation.

Demo

Actual output of npm run agent -- --trace "Why is authentication failing on /payments?" against the seeded gateway and gemini-3.5-flash-lite (run captured on 2026-09-12):

Investigation trace:

  Step 1  (llm 1602ms, finish=tool_calls)
    -> find_route_by_path({"path":"/payments"})  ok 30ms 209B

  Step 2  (llm 1317ms, finish=tool_calls)
    -> diagnose_route({"route":"route:payments-prod"})  ok 64ms 3162B

  Step 3  (llm 1971ms, finish=stop)

DIAGNOSIS
**Diagnosis:**
Authentication is not failing on `/payments` because **no authentication plugin is
attached or enabled** for that route at all. Kong is currently passing all requests to
`/payments` through without requiring any credentials.

**Evidence:**
- The route `payments-prod` (serving `/payments`) has only a `cors` plugin attached at
  the route scope.
- There are no service-level plugins on `payments-api`.
- The global plugins active on the gateway are `request-size-limiting` and
  `correlation-id`.
- None of these are authentication plugins (`key-auth`, `jwt`, `basic-auth`, etc.).

**What to do next:**
1. Confirm with your team whether the `/payments` endpoint is intentionally public.
2. If authentication *should* be required, configure and enable an appropriate
   authentication plugin (such as `key-auth` or `jwt`) on the route or its backing
   service.

**Limitations:**
This diagnosis reflects gateway configuration only. If clients are receiving 401 or 403
responses when calling `/payments`, those responses are coming from the upstream backend
service (`http://payments-upstream:8080/v1`), not from Kong itself.

RUN METRICS
  steps                3 / 10
  tool calls           2 (0 error(s))
  repeated calls       0
  tools used           find_route_by_path, diagnose_route
  tool latency avg/p95 46.5ms / 64ms
  llm calls            3 (avg 1630ms)
  tokens               12677 in / 300 out / 12977 total
  estimated cost       $0.004553
  context used         3371 / 50000 chars
  wall clock           4993ms

The question's premise is wrong -- nothing is rejecting requests -- and the agent corrects it from evidence rather than accepting it. The diagnose_route result it reasoned over is the same structured object an MCP client would receive:

{
  "confidence": "CONFIRMED",
  "summary": "No enabled authentication plugin applies to route route:payments-prod. ...",
  "findingCount": 2,
  "findings": [
    {
      "code": "NO_AUTH_PLUGIN",
      "category": "AUTHENTICATION",
      "severity": "HIGH",
      "entityType": "route",
      "entityRef": "route:payments-prod",
      "observedState": "No enabled authentication plugin applies to route route:payments-prod. No authentication plugin is attached at route, service or global scope.",
      "expectedState": "A route serving protected resources should have an enabled authentication plugin (key-auth, jwt, basic-auth, oauth2, ...) at route, service or global scope.",
      "evidence": [
        "Route-scoped plugins: cors.",
        "Service-scoped plugins: none.",
        "Global plugins: request-size-limiting, correlation-id."
      ],
      "recommendedNextStep": "Kong forwards every request to /payments without authenticating it, ..."
    }
  ],
  "observed": { "route": { "ref": "route:payments-prod", ... }, "effectivePlugins": [ ... ] },
  "gaps": [],
  "suggestedNextSteps": [ ... ]
}

Installation

Requirements: Node.js >= 20, npm, Docker with Compose v2.

git clone <this repository>
cd kong-ai-gateway-mcp
npm install
cp .env.example .env        # defaults work for the local Kong; add GEMINI_API_KEY for the agent

Verify the toolchain without Docker or an API key:

npm run check               # lint + typecheck + 140 unit tests

Running Kong

npm run kong:up             # docker compose up -d  (Postgres, migrations, Kong 3.9)
npm run seed                # 12 services, 12 routes, 4 upstreams, 7 consumers, 20 plugins,
                            # 10 intentional defects; waits for health-check verdicts
npm run health              # PASS/FAIL for Admin API, proxy, seed state

Ports on the host: 8000 proxy, 8443 proxy TLS, 127.0.0.1:8001 Admin API, 127.0.0.1:8002 Kong Manager. The Admin API is an unauthenticated control plane and is bound to loopback only. Postgres is not published.

Other lifecycle commands: npm run kong:down, npm run kong:reset (destroys volumes), npm run kong:logs, npm run seed:reset (deletes every seeded entity first; the seed is idempotent either way).

What is seeded and why each defect exists: docs/scenarios.md.

Running the MCP server

npm run dev                 # tsx, stdio transport
# or
npm run build && npm start  # node dist/server.js

Register with an MCP client by pointing it at the built server. For Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "kong-diagnostics": {
      "command": "node",
      "args": ["/absolute/path/to/kong-ai-gateway-mcp/dist/server.js"],
      "env": { "KONG_ADMIN_URL": "http://localhost:8001" }
    }
  }
}

The server needs no LLM key. It probes Kong at startup and logs a warning (not an error) if the gateway is not yet up; tools return structured UNREACHABLE errors until it is.

Point clients at node dist/server.js (or npx tsx src/server.ts) directly, not at npm run ...: npm prints a script banner to stdout, which is the protocol channel. npm run dev is for driving the server by hand; it deliberately does not use watch mode (see MCP-STDOUT-001 in the failure modes).

Running the agent

Requires GEMINI_API_KEY in .env.

npm run agent -- "Why is authentication failing on /payments?"
npm run agent -- --trace "Clients hitting /orders get 429 immediately. What's going on?"
npm run agent -- --json "Is /shipping protected?"     # full run record as JSON

Exit code is 0 for a complete diagnosis and 1 when the run was cut off by a limit or a provider error -- in which case the answer says so explicitly.

Running evaluation

npm run eval                        # all 28 cases -> evals/results/run-NNN.{json,md}
npm run eval -- --case auth-001     # one case (repeatable flag)
npm run eval -- --difficulty hard
npm run eval -- --scenario UPSTREAM-UNHEALTHY-001
npm run eval -- --dry-run           # validate the dataset, run nothing
npm run eval -- --resume run-003    # finish a run the provider's daily quota cut short

Configuration

All variables are validated at startup by src/config/env.ts. Blank values fall through to defaults.

Variable

Default

Purpose

KONG_ADMIN_URL

http://localhost:8001

Admin API base URL

KONG_PROXY_URL

http://localhost:8000

used only by npm run health

KONG_TIMEOUT_MS

5000

per-request timeout to Kong

LLM_PROVIDER

gemini

provider for the agent and evaluation

GEMINI_API_KEY

(unset)

required for agent and eval only

GEMINI_MODEL

gemini-3.5-flash-lite

any model the key can access; pricing must be declared in src/telemetry/cost.ts for cost to be reported

LOG_LEVEL

info

pino level; audit events always emit

LOG_FILE

(unset)

additional JSON log destination; stderr always

ENABLE_WRITE_TOOLS

false

must stay false: no write tool is implemented and the server refuses to start otherwise

MAX_TOOL_RESULT_ITEMS

50

cap on any list in a tool result

MAX_CONTEXT_CHARS

12000

cap on a single serialized tool result

MAX_AGENT_STEPS

10

LLM calls per run

MAX_REPEATED_TOOL_CALLS

2

identical (tool, arguments) calls per run

MAX_TOTAL_TOOL_RESULT_SIZE

50000

cumulative tool-result characters per run

.env is gitignored. Nothing in the project prints a key; redactConfig reduces it to [set] / [unset].

Evaluation

Methodology. One case per user question; 28 cases across 11 scenarios and three difficulties. Scoring is deterministic -- no LLM judge. A case passes when the deterministic engine produced every expected finding code during the run, the answer contains every expected fact, contains no named wrong conclusion, and the run finished within its limits. Cases the provider's daily quota prevents from running are marked SKIPPED and excluded from every rate rather than counted as failures.

Results of the current run (run-003, dataset 1.2.0, gemini-3.5-flash-lite, Kong 3.9.3, 2026-09-12):

Passed

28 / 28 (easy 6/6, medium 14/14, hard 8/8)

Finding recall / fact match / completion

100% / 100% / 100%

Steps per case

mean 3.5 (min 3, max 9)

Tool calls per case

mean 2.57; repeated calls: 0

Duration per case

median 5.4 s; mean 20.5 s (nine cases include 30-60 s of free-tier rate-limit backoff); retry-free median 4.5 s

Tokens

425,710 total, 15,204 per case

Estimated cost

$0.1496 total, $0.0053 per case

Two earlier runs are kept: run-001 scored 22/28 and run-002 26/28, and in both every miss was either a provider rate-limit loss or a correct answer the substring scorer marked wrong. No case in any run failed because the agent gave a wrong diagnosis. How the scorer was fixed, and what these numbers do and do not show, is in docs/evaluation.md. Per-case results and every verbatim answer: evals/results/run-003.md.

Observability

Structured JSON to stderr (and LOG_FILE), never stdout. Every tool call records requestId, traceId, taskId, tool, duration, status, error category, result size and whether it was a repeat; every LLM call records provider, model, duration, provider-reported tokens, finish reason and estimated cost. A separate audit log records each invocation with sanitized arguments at warn. Metrics (call counts, success rate, mean / p50 / p95 latency, repeat rate, tokens, cost) are computed only from recorded calls. Details: docs/observability.md.

Failure Modes

Twelve failures were observed while building this and are documented with symptom, root cause, impact, mitigation and regression test -- including a halt path that would have returned an empty answer, a cost calculation off by 10x, a per-day quota mistaken for a rate limit, a Gemini 3 protocol requirement that broke every case after its first tool call, and a scorer that marked correct answers wrong. Twenty-three more were deliberately provoked and verified. docs/failure-modes.md.

Security

docs/security.md -- threat model, the five boundaries at which secrets are stopped (each with its test), execution limits, the read-only guarantee and how it is structural, what prompt injection is and is not mitigated, and what is not handled.

Architecture Decisions

docs/decisions.md -- fourteen decisions in context / decision / alternatives / trade-offs / consequences form, each tied to something in this repository.

Context Management

docs/context-management.md -- the mechanisms and the measurements behind them.

Testing

npm test                    # 140 unit tests; no Docker, no network
npm run test:integration    # 27 tests against live seeded Kong, incl. MCP over real stdio
npm run test:e2e            # 3 tests: question -> agent -> tool -> Kong -> diagnosis (needs a key)
npm run test:all

Integration and e2e suites skip themselves with a message when their dependency is absent, so npm test passes on a fresh clone.

Limitations

  • Read-only. The agent can find a problem but not fix it. The write flow (confirmation token, preview diff, audit, rollback) is designed and documented, not built.

  • Rules must be written. The engine detects the defect classes it has rules for (eleven). A novel class is invisible until someone adds a rule; the model cannot discover it from a summary that omitted the relevant field.

  • find_route_by_path matches whole paths. It does not simulate Kong's prefix or regex routing.

  • One provider. Gemini only. Anthropic and OpenAI are one file each away, but that file does not exist yet.

  • Free-tier constraints shaped the harness. Per-minute rate limits add 30-60 s to some cases; some models have a 20-request daily quota. The harness handles both honestly but a paid tier would give cleaner latency numbers.

  • Scoring is substring-based. It is a regression net for named facts and named wrong conclusions, not a judge of prose quality.

  • Prompt injection through gateway data is not detected. It is defanged (no write path, typed arguments, facts from rules) but not detected or filtered.

  • Kong 3.9.x only has been tested.

  • Sample size. 28 cases, one model, one full run per dataset version. Enough to demonstrate and to catch regressions; not enough to state a stable percentage.

Roadmap

Possible, not promised:

  • Confirmation-gated write tools (enable a plugin, fix a route path) with preview and audit, behind ENABLE_WRITE_TOOLS.

  • Anthropic and OpenAI providers.

  • Rules for more defect classes: certificate/SNI mismatches, plugin ordering conflicts, consumer-scoped plugin overrides.

  • A second full evaluation run per model to establish variance, and evaluation across models.

  • OpenTelemetry export for tool and LLM spans.

  • Human feedback on answers, feeding the case set.

  • Other gateways behind the same tool contract.

License

MIT.

Available Tools

14 tools
check_upstream_healthCheck upstream target healthA
Read-onlyIdempotent

Reports Kong's own health verdict for each target of an upstream.

USE WHEN: a route returns 503, or you have ruled out authentication and routing and need to know whether the backend pool is actually serving. Reach this tool from a service whose host names a Kong upstream.

CRITICAL DISTINCTION between the verdicts this returns: HEALTHY probed and responding UNHEALTHY address is correct, backend is failing -> availability problem DNS_ERROR address cannot be resolved -> configuration problem HEALTHCHECKS_OFF Kong is not probing at all -> health is UNKNOWN, not healthy

Do not read HEALTHCHECKS_OFF as "fine". It means no information.

RETURNS: targets each with target, health, weight and a meaning line; plus healthchecksEnabled, verdict and canServeTraffic.

LIMITATIONS: reports the gateway's view only, and that view is only as fresh as Kong's last probe or proxied request for this upstream. A freshly created or rebuilt target is reported HEALTHY before the first probe runs, and an idle upstream can show a stale HEALTHY for a target that is actually down. If a HEALTHY verdict contradicts other evidence (e.g. 503s), say so rather than treating it as proof the backend is up.

Inputs: upstream (required).

diagnose_routeRun a full diagnostic on a routeA
Read-onlyIdempotent

Runs a complete, rule-based diagnostic on one route and returns structured findings.

This is the highest-value tool in this server and usually the right SECOND call, after find_route_by_path. It performs the whole investigation a careful engineer would -- resolve the route, resolve its service, collect plugins at all three scopes, check upstream target health, check the named consumer's credentials and ACL groups, compare against the declared configuration baseline -- and applies the diagnostic rules to the result.

USE WHEN: the user reports a problem with a route or path. Prefer it over assembling the same picture yourself from get_route + list_plugins_for_route + check_upstream_health: it is one call instead of four, and it will not mistake "not collected" for "not present".

Pass consumer whenever the user named a specific client. Without it, consumer-specific causes are invisible and the diagnosis will look clean when it is not.

RETURNS: confidence CONFIRMED | PARTIAL | INSUFFICIENT_EVIDENCE summary one-sentence verdict findings[] each with code, severity, observedState, expectedState, evidence[], recommendedNextStep observed what Kong actually reports (route, service, effective plugins, consumer, upstream) gaps[] evidence that could not be collected, and what that prevents concluding suggestedNextSteps[]

HOW TO READ IT: every finding is derived from Kong by deterministic rules -- these are facts, not guesses. Report them as such, and cite the evidence entries. Respect confidence: PARTIAL means something could not be read and a further problem may be hidden there. Zero findings with CONFIRMED means the route is genuinely fine; say so rather than inventing a cause.

LIMITATIONS: inspects gateway configuration and Kong's own health verdicts only. It does not send traffic, read gateway logs, or observe live request behaviour. A backend that returns HTTP 500 on every request looks perfectly healthy here.

Inputs: path, route, consumer.

diff_configDiff live Kong against the declared baselineA
Read-onlyIdempotent

Compares what Kong is actually running against the declared configuration baseline in kong/seed/baseline.json, and reports every difference.

USE WHEN: something is configured but behaving unexpectedly, and you need to know whether the live configuration matches what was intended. Especially effective for problems with no local symptom -- a route attached to the wrong service, a dropped HTTP method, a changed upstream address -- where the entity looks perfectly valid in isolation.

Pass entity to scope the comparison to one route or service. A whole-gateway diff is much larger and usually buries the relevant line.

RETURNS: drift[], each entry naming the entity, the attribute, the baseline value, the Kong value and the operational impact; plus inSync and driftCount.

IMPORTANT: a difference does NOT establish which side is wrong. The baseline may be out of date just as easily as the gateway may have drifted. Report the difference and what it causes; do not assert that Kong is misconfigured on the strength of this tool alone.

LIMITATIONS: the baseline covers services (host/port/protocol), routes (service, paths, methods, required plugins) and upstreams (targets). Plugin configuration VALUES are not compared -- only whether a required plugin is present and enabled.

Inputs: scope, entity.

explain_auth_failureExplain an authentication or authorization failureA
Read-onlyIdempotent

Focused analysis of why requests to a route are being rejected, narrowed to the authentication and authorization chain.

USE WHEN: the reported symptom is specifically a 401 or 403, or the user says credentials are being rejected. For a broader or vaguer problem, use diagnose_route.

Walks the chain in the order Kong evaluates it and reports where it breaks:

  1. does a route serve this path?

  2. is an authentication plugin attached, and is it ENABLED?

  3. does the named consumer exist?

  4. does that consumer hold a credential of the required type? -> 401 if not

  5. does an acl plugin apply, and is the consumer in an allowed group? -> 403 if not

RETURNS: chain with a per-step verdict, plus the authentication and authorization findings and a likelyCause.

LIMITATIONS: reasons from configuration, not from observed traffic. It cannot tell you whether a client is sending a malformed header or an expired token -- only what the gateway is configured to require.

Inputs: path, route, consumer.

find_route_by_pathFind the route serving a URL pathA
Read-onlyIdempotent

Resolves a URL path to the Kong route (or routes) that serve it.

USE WHEN: the user describes a problem in terms of a path -- "auth is failing on /payments", "/orders returns 429". This is almost always the correct FIRST tool for such a question, because everything else needs a route identifier.

RETURNS: matches, each a route summary with a ref to pass to get_route, list_plugins_for_route or diagnose_route. When nothing matches, returns matches: [] plus suggestions listing configured paths that closely resemble the one requested -- a near-miss there usually means a typo in the route definition.

LIMITATIONS: matches whole path values only, not Kong prefix-matching semantics, so a request to /payments/v2 handled by a /payments route will not match here. More than one match means the path is genuinely ambiguous in Kong and is worth investigating in itself.

Inputs: path (required).

get_consumerGet a consumer with credential and group stateA
Read-onlyIdempotent

Retrieves one Kong consumer together with what it can actually authenticate and authorize with: how many credentials of each type it holds, and which ACL groups it belongs to.

USE WHEN: a specific client is failing while others succeed, or you need to distinguish a 401 from a 403. The two have different causes and this tool separates them:

  • no credential of the type the route requires -> 401, authentication fails

  • credential present but wrong ACL group -> 403, authorization fails

RETURNS: consumer (ref, username, customId), credentialCounts per credential type, and aclGroups.

SECURITY: credential COUNTS only. Key values, passwords and secrets are never returned by this tool and are not available through any tool in this server.

LIMITATIONS: does not say which routes the consumer may reach -- that depends on the plugins on each route. Pair with list_plugins_for_route, or use diagnose_route with a consumer name to have both sides checked together.

Inputs: consumer (required).

get_routeGet one Kong routeA
Read-onlyIdempotent

Retrieves a single Kong route and the service it is attached to.

USE WHEN: you already know the route name or have a route: reference from another tool, and need its paths, methods, hosts, protocols, or which service handles it.

DO NOT USE with a URL path such as "/payments" -- route names and route paths are different things, and this tool takes the name. Use find_route_by_path to go from a path to a route.

RETURNS: route with ref, paths, methods, hosts, protocols, stripPath, and serviceRef naming the owning service.

LIMITATIONS: does not return plugins. A route can look entirely correct here while being unauthenticated -- call list_plugins_for_route to see what actually applies to it.

Inputs: route (required).

get_serviceGet one Kong serviceA
Read-onlyIdempotent

Retrieves the full configuration of a single Kong service.

USE WHEN: you have identified a service and need its backend address, protocol, path prefix, retry policy or timeouts. Typically the step after get_route tells you which service a route belongs to.

DO NOT USE to find out which plugins apply -- plugins live on a separate endpoint; use list_plugins_for_route, which already accounts for service-level inheritance.

RETURNS: one service with ref, host, port, path, protocol, retries and the three timeout values.

LIMITATIONS: does not list the routes attached to the service, and does not tell you whether host names a Kong upstream or a plain DNS hostname. If you need target health, pass the host to check_upstream_health.

Inputs: service (required).

list_consumersList Kong consumersA
Read-onlyIdempotent

Lists the consumers (API clients) registered in Kong.

USE WHEN: you need to find the right consumer name before calling get_consumer, or to confirm whether a client the user named exists at all. A client that is not registered as a consumer cannot authenticate, which is a different problem from a missing credential.

RETURNS: items with ref, username and customId, plus a page object.

LIMITATIONS: no credentials and no group membership -- call get_consumer for one consumer.

Inputs: limit, cursor.

list_global_pluginsList globally applied pluginsA
Read-onlyIdempotent

Lists plugins applied to every request, i.e. those with no service, route or consumer scope.

USE WHEN: you need to rule out a gateway-wide plugin before concluding that a route lacks something. A global key-auth would protect every route without appearing on any of them.

RETURNS: plugins with ref, name, enabled and relevant config, plus pluginCount.

LIMITATIONS: global scope only. To see everything affecting one route including inheritance, use list_plugins_for_route, which covers this case already.

Inputs: no named parameters.

list_plugins_for_routeList plugins affecting a routeA
Read-onlyIdempotent

Lists every plugin that affects a route, resolved across all three Kong scopes.

USE WHEN: investigating authentication, rate limiting, CORS, ACL or any other plugin-driven behaviour. This is the tool that answers "is this route protected, and by what".

IMPORTANT -- three things this resolves that a raw plugin list does not:

  1. Scope precedence. Kong applies the most specific instance of a plugin: route beats service beats global. effectivePlugins reflects that; shadowed lists instances that exist but never run.

  2. Disabled plugins. A plugin with enabled=false is still returned by Kong and still shows in Kong Manager, but does nothing. Check the enabled field, not mere presence.

  3. Authentication summary. authentication states plainly whether any ENABLED auth plugin applies, which is usually the actual question.

RETURNS: effectivePlugins (what actually runs, each with ref, name, enabled, scope and relevant config), shadowed, and an authentication summary object.

LIMITATIONS: plugin config is filtered to diagnostically relevant keys; secret-bearing fields are never returned. Consumer-scoped plugin instances are listed but their effect depends on which consumer is calling.

Inputs: route (required), includeInherited.

list_routes_for_serviceList the routes attached to a serviceA
Read-onlyIdempotent

Lists every route attached to one Kong service.

USE WHEN: you need to know how traffic reaches a service, or to check whether a service has any route at all. A service with zero routes is unreachable through the gateway, which is a real and easily missed misconfiguration.

RETURNS: routes, each with ref, paths and methods, plus routeCount.

LIMITATIONS: does not return plugins for those routes.

Inputs: service (required), limit.

list_servicesList Kong servicesA
Read-onlyIdempotent

Lists the services configured in Kong, one compact summary each.

USE WHEN: you need to discover what exists in the gateway, or map a vague name a user gave ("the payments API") onto a real service. Also useful to confirm a service exists before investigating further.

DO NOT USE to investigate a specific route or path. If the user named a path such as /payments, call find_route_by_path instead -- it goes straight to the relevant entity rather than making you scan a list.

RETURNS: items, each with ref (pass to other tools), name, target (where the service sends traffic) and enabled; plus a page object with hasMore and nextCursor.

LIMITATIONS: summaries only -- no plugins, no routes, no timeouts. Use get_service for the full record of one service. A page that reports hasMore=true is NOT the complete set.

Inputs: limit, cursor, nameContains.

list_upstreamsList Kong upstreamsA
Read-onlyIdempotent

Lists the upstreams (load-balanced backend pools) configured in Kong.

USE WHEN: you need to know which upstream a service name refers to, or which upstreams have health checking configured at all.

RETURNS: upstreams with ref, name, algorithm and healthchecksConfigured.

LIMITATIONS: no targets and no health. Use check_upstream_health for one upstream.

Inputs: limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 14 tools

    Disambiguation4/5

    Tools target distinct Kong entities and actions, and descriptions explicitly steer between similar options such as find_route_by_path vs get_route and diagnose_route vs explain_auth_failure. However, the composite diagnostic tools overlap with the lower-level get/list tools, so an agent could still be unsure whether to assemble evidence manually or use the high-level diagnostic.

    Naming Consistency5/5

    All 14 tools use consistent snake_case and a verb-first pattern (find_, list_, get_, check_, diff_, diagnose_, explain_). There are no mixed conventions or ambiguous suffixes.

    Tool Count5/5

    14 tools is well within the expected 3–15 range for a Kong diagnostic surface. Each tool maps to a meaningful entity or check, with no obvious bloat or thin coverage.

    Completeness4/5

    The set covers core diagnostic paths: route resolution, service/consumer/upstream lookup, plugin scoping, health checks, config diff, and high-level diagnosis. Minor gaps remain, such as no general list_routes or get_upstream, but core route/auth troubleshooting workflows are largely complete.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Kubernetes diagnostic agent that provides on-demand root cause analysis and human-in-the-loop remediation via Slack, using LLM reasoning with OPA-bounded security controls.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables a local AI agent to investigate service incidents by querying read-only telemetry such as service health, metrics, logs, and traces, then produce verifiable assessments with evidence links and uncertainty.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives AI agents read-only access to production NATS and JetStream event buses through twenty-five bounded, schema-typed tools covering message search, dead-letter inspection, causal flow reconstruction from a request or correlation id, and stream, consumer, KV, object-store and server-health topology. Because the runtime is wired only to read paths and every result is limited, cursored and truncation-flagged, agents can debug live traffic without any ability to mutate it.
      Apache 2.0