T

Stéphane Tailland d4008e5e38 docs: record Kong's MCP tool-generation limits and our workarounds

The domains' tools: arrays are hand-maintained, and that has now cost two
defects an agent found the hard way — create-product could never succeed, and
list-products cannot paginate, which let a model answer a product count that
looked right and did not come from the data.

Five limits measured against decK v1.64.0 and Kong Gateway 3.15, each
reproduced rather than read: per-tool ACLs cannot express a consumer-group
model and fail silently; the four MCP behavioural annotations are not
generated; response schemas are not generated although the plugin consumes them
for structuredOutput; servers is taken as the upstream target; every content
type is copied and every operation exposed.

FastMCP run on the same spec is recorded as a comparison point — it closes
three of the five out of the box — with the reason we are not adopting it: it
would move per-tool authorization out of the realm and into application code.

Also records that MCP Composer and MCP Runner never shipped, so none of this is
waiting on an imminent release.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-29 08:39:04 +02:00

dataplane-globalpolicy-template

Give the Konnect control-plane ref a stable, derived name

2026-08-26 16:30:02 +02:00

dataplane-template

Make the request body buffer a per-domain setting

2026-08-27 16:41:33 +02:00

flux

Place the dataplane defaults in every domain namespace

2026-08-27 14:31:11 +02:00

kong-platform

Make the request body buffer a per-domain setting

2026-08-27 16:41:33 +02:00

observability

Send Kong traces to Tempo and gateway audit logs to Loki

2026-08-25 07:25:36 +02:00

.gitignore

Template defaults

2026-08-19 17:34:06 +02:00

MCP-TOOL-GENERATION.md

docs: record Kong's MCP tool-generation limits and our workarounds

2026-08-29 08:39:04 +02:00

README.md

docs: record Kong's MCP tool-generation limits and our workarounds

2026-08-29 08:39:04 +02:00

README.md

k8s-platform

Platform-team owned, cluster-scoped only. Rare changes, cautious sync (not aggressive auto-sync).

Per-domain gateway infrastructure (Gateway, GatewayConfiguration, KonnectAPIAuthConfiguration) does NOT live here — see the dedicated dataplane-<domain> repos, to avoid write contention across domains.

MCP-TOOL-GENERATION.md

How the domains' MCP tool definitions are produced, the five limits of Kong's deck file openapi2mcp generator, and the workaround each one forces. Read it before editing any <domain>-api/kong/mcp/ai-mcp-proxy.yaml by hand — that file is hand-maintained today, and that is precisely the problem it documents.

flux/

The Flux Operator (flux-system namespace) that everything else in this GitOps setup depends on. Installed 2026-08-19 on the local cluster.

The operator itself is installed manually via Helm — bootstrap problem, Flux can't deploy the thing that deploys it:

helm install flux-operator oci://ghcr.io/controlplaneio-fluxcd/charts/flux-operator \
  --namespace flux-system --create-namespace

flux/fluxinstance.yaml configures the actual Flux controllers (source-controller, kustomize-controller, helm-controller, notification-controller) — tracked in git, applied via kubectl apply -k flux/.

flux/gitrepository.yaml is what lets Flux clone this (k8s-platform) repo so other repos' Kustomizations can reference paths inside it (e.g. dataplane-template/). url is a PLACEHOLDER — this repo has no git remote yet. Once it does, apply it manually once (kubectl apply -f flux/gitrepository.yaml) — same bootstrap-chicken-egg reasoning as the operator install above.

kong-platform/

Cluster-wide Kong foundations:

gatewayclass.yaml — GatewayClass kong-v2 (deliberately not named kong, to avoid touching the pre-existing kong GatewayClass that backs the unrelated tasks/jira/openrouter Gateway on this cluster).
operator/ — HelmRepository + HelmRelease for the Kong Gateway Operator itself, matching the release already installed manually on this cluster (helm list -n kong: chart kong-operator-1.3.1, env.ENABLE_CONTROLLER_KONNECT: true). helm-controller can adopt an existing release under the same releaseName/targetNamespace rather than reinstalling.

dataplane-template/

The shared KonnectAPIAuthConfiguration + GatewayConfiguration + Gateway

Secret template (one copy, ${VAR}-parameterized) that every domain's Flux Kustomization builds via postBuild.substitute — see dataplane-catalog/README.md for the full mechanism and the values/secret side of it.

Applying today (no git remote yet)

Nothing here reconciles from git automatically yet — flux/gitrepository.yaml has no real URL. Apply directly:

kubectl apply -k flux/           # fluxinstance.yaml + gitrepository.yaml (the
                                  # latter will just sit inert, PLACEHOLDER url)
kubectl apply -f kong-platform/gatewayclass.yaml

dataplane-template/ is never applied on its own — it only makes sense built + substituted by a domain's flux-kustomization.yaml, which itself can't reconcile yet (needs the real GitRepository, see above).