kong-mcp

A Model Context Protocol server for Kong. It exposes Kong's control plane to MCP-capable agents (Claude Code, Claude Desktop, …) over stdio, so an agent can create and test workflows, extensions and secrets against a running Kong stack.

It talks to the same gateway endpoints the UI and kong-cli use (/api/management, /api/public, /api/webhook, /api/fs, /api/keycloak) and authenticates with a Keycloak resource-owner password grant against the public kong-web client (identical to kong-cli). Credentials are read from the same profile store as kong-cli (~/.kong/config + the OS keyring), so a profile saved with kong_configure is reusable by kong-cli and vice-versa.

Recommended flow (for agents)

1. Orient first: call kong_whoami to verify connectivity/tenant, then kong_learn with KONG — it is the end-to-end playbook (create → author → load samples → validate → save → publish → alias → test) and links the per-state reference docs. Read the doc for each state type before authoring it; the JQ engine is a documented subset of jq 1.6.
2. Author in TypeScript (KongSpecBuild in a workflow.ts under ~/.kong/...), never hand-written JSON.
3. Load real samples state by state, in execution order (kong_workflow_load_sample, threading each returned flow into the next call) so every downstream JQ filter is written against the real payload shape — then kong_workflow_validate, then save.
4. Let the tools compute layout — kong_workflow_save/kong_workflow_create auto-layout with the designer's real node geometry when no layout is passed; don't invent coordinates.
5. Deploy and verify: kong_workflow_publish_version (image build takes minutes; the tool waits) → kong_workflow_set_alias → confirm with kong_deploy_status → kong_workflow_test, judging results against the workflow's own success/fail contract, not just HTTP status.

The KONG playbook ends with a field-tested gotchas list (secret-ref quoting, | tostring in {{ ... }} templates, SQL string-typed parameters, db-call row arrays, context key camelCasing, …) — check it whenever a call fails or validation rejects a flow.

Tools

| Tool | What it does | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | kong_whoami | Verify connectivity/credentials; report user, tenant, gateway, credential source. | | kong_configure | Save credentials to the shared profile store (~/.kong/config + keyring) and switch to them. | | kong_workspace_list | List workspaces, to pick one. | | kong_workspace_create | Create a workspace. | | kong_project_list | List projects within a workspace, to pick one. | | kong_project_create | Create a project in a workspace. | | kong_learn | Read the bundled knowledge base (playbook + state reference docs); also exposed as MCP resources. | | kong_workflow_list | List workflow documents, to pick one. | | kong_workflow_create | Create a document, upload its spec bundle, save the first checkpoint (validates + auto-layouts the flow). | | kong_workflow_get | Download the current content (latest checkpoint) of a workflow as a KongSpecFile. | | kong_workflow_save | Save new content (a KongSpecFlow) for an existing workflow (validates; computes a layout when none is given). | | kong_workflow_validate | Run KongSpec validation (the designer's checks) over a flow without saving. | | kong_workflow_layout | Statically compute a designer-canvas layout from the renderer's known node geometry. | | kong_workflow_load_sample | Invoke one state's callFunction(s) with its inferred input, store the result as outputSample (designer's "load example"); call per state in execution order.| | kong_workflow_browse | Return the editor URL and try to open the workflow in the browser. | | kong_workflow_publish_version | Upload the deployable bundle, snapshot, build the image (waits via the registry), bind the alias via the public API. | | kong_workflow_set_alias | Bind a process alias to an already-published snapshot version (optional wait). | | kong_workflow_test | Launch a published workflow via the webhook trigger (sync/async). | | kong_extension_create | Scaffold a new extension project (Python/Kotlin) from the @devkong/cli-nx preset; returns next steps. | | kong_extension_set_alias | Bind an extension alias to a published snapshot version (public API; optional wait). | | kong_extension_test | Invoke a built-in function (api-call, db-call) and return its result. | | kong_deploy_status | Return the full deployment audit log of a process/extension alias + analyzed status (idle/pending/succeeded/failed). | | kong_secret_list_types | List secret types (to resolve typeId). | | kong_secret_create_type | Create a secret type (a fresh tenant has none): "jdbc" for db-call, "api" for api-call, "s3" for outputStore. | | kong_secret_list | List secrets, optionally filtered by workspace/project permission, to pick one to reference. | | kong_secret_create | Encrypt + deploy a secret with workspace/project permissions (waits for the async runtime save). |

Configuration

Credentials resolve in this order: shared profile → environment variables → built-in dev defaults.

1. Profile — ~/.kong/config ({ profileName: { kongBaseUrl, userName } }) plus the password in the OS keyring (@napi-rs/keyring, keyed by (kongBaseUrl, userName)). This is the same store kong-cli uses. Write it with the kong_configure tool (or kong configure). The profile name is KONG_PROFILE (default default).
2. Environment variables — used when the profile is missing/incomplete.
3. Built-in defaults — target a local docker compose --profile=dev stack.

| Variable | Default | Notes | | --------------- | ----------------------------------------------- | -------------------------------------------------- | | KONG_PROFILE | default | Profile name read from ~/.kong/config + keyring. | | KONG_BASE_URL | http://localhost:4000 | Gateway base url. | | KONG_USERNAME | kong-dev | Keycloak user. | | KONG_PASSWORD | kong | Keycloak password. | | KONG_TENANT | derived from base url (sandbox for localhost) | X-App-Tenant header. |

When no usable credentials are found, ask the user for the base url / username / password and call kong_configure — a stdio MCP server cannot prompt for them itself.

Install & run

The server is published to npm as @devkong/mcp — no checkout or build needed:

npx -y @devkong/mcp   # speaks MCP over stdio

Register it with Claude Code:

claude mcp add kong -- npx -y @devkong/mcp

…or in an MCP client config:

{
  "mcpServers": {
    "kong": {
      "command": "npx",
      "args": ["-y", "@devkong/mcp"],
      "env": { "KONG_BASE_URL": "http://localhost:4000" }
    }
  }
}

From source (this repo)

npx nx build kong-mcp
node packages/kong-mcp/dist/main.js   # speaks MCP over stdio

claude mcp add kong -- node /absolute/path/to/packages/kong-mcp/dist/main.js