kong-ai-gateway-mcp
Provides read-only diagnostic tools for investigating a Kong Gateway through its Admin API. It exposes fourteen bounded, schema-validated MCP tools (e.g. find_route_by_path, get_route, get_service, list_plugins_for_route, list_global_plugins, get_consumer, list_upstreams, check_upstream_health, diff_config) and a deterministic diagnostic engine that applies eleven pure rules over Kong-collected evidence to produce findings such as NO_AUTH_PLUGIN, diagnose routes and explain authentication failures, with scoped plugin resolution, upstream health checks, and context-bounded, credential-stripped responses. The agent sequences these tools to answer questions like "Why is authentication failing on /payments?" without ever inventing gateway facts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kong-ai-gateway-mcp Why is authentication failing on /payments?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 sKong 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 withENABLE_WRITE_TOOLS=truebecause 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
LlmProviderinterface;@google/genaiimported 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 4993msThe 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 agentVerify the toolchain without Docker or an API key:
npm run check # lint + typecheck + 140 unit testsRunning 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 statePorts 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.jsRegister 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 JSONExit 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 shortConfiguration
All variables are validated at startup by src/config/env.ts.
Blank values fall through to defaults.
Variable | Default | Purpose |
|
| Admin API base URL |
|
| used only by |
|
| per-request timeout to Kong |
|
| provider for the agent and evaluation |
| (unset) | required for |
|
| any model the key can access; pricing must be declared in |
|
| pino level; audit events always emit |
| (unset) | additional JSON log destination; stderr always |
|
| must stay false: no write tool is implemented and the server refuses to start otherwise |
|
| cap on any list in a tool result |
|
| cap on a single serialized tool result |
|
| LLM calls per run |
|
| identical (tool, arguments) calls per run |
|
| 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:allIntegration 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_pathmatches 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 toolscheck_upstream_healthCheck upstream target healthARead-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 routeARead-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 baselineARead-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 failureARead-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:
does a route serve this path?
is an authentication plugin attached, and is it ENABLED?
does the named consumer exist?
does that consumer hold a credential of the required type? -> 401 if not
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 pathARead-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 stateARead-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 routeARead-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 serviceARead-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 consumersARead-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 pluginsARead-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 routeARead-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:
Scope precedence. Kong applies the most specific instance of a plugin: route beats service beats global.
effectivePluginsreflects that;shadowedlists instances that exist but never run.Disabled plugins. A plugin with enabled=false is still returned by Kong and still shows in Kong Manager, but does nothing. Check the
enabledfield, not mere presence.Authentication summary.
authenticationstates 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 serviceARead-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 servicesARead-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 upstreamsARead-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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Zero-trust gateway for AI agents: score tool calls, verify agent cards, enforce policy, audit.
IP intelligence, network diagnostics, and AI service availability tools for AI agents.
Finds what's broken in your product, explains why, and fixes it from your agent.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA 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-
- AlicenseNot gradedqualityCmaintenanceEnables 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
- FlicenseNot gradedqualityAmaintenanceEnables AI agents and MCP clients to query and debug trace data, sessions, exceptions, route decisions, metrics, prompts, datasets, and annotation queues. Supports configurable tool groups and read-only safety modes.-
- AlicenseNot gradedqualityCmaintenanceGives 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