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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.