# Kong Admin API — MCP Server

An [MCP](https://modelcontextprotocol.io) server that exposes the **full Kong Gateway Admin API** (Enterprise & OSS) as tools an AI assistant can call. Configure it with your Admin API URL and admin token, and the assistant can manage services, routes, consumers, plugins, upstreams, certificates, RBAC, workspaces — anything the Admin API can do.

Built against the [Kong Gateway Admin EE API 3.14](https://developer.konghq.com/api/gateway/admin-ee/3.14/).

## What it can do

Every Admin API action is reachable. There are ergonomic CRUD tools for the standard entities plus a universal escape-hatch tool for everything else (nested resources, RBAC, keyring, schemas, declarative config, future endpoints).

| Tool | Purpose |
| --- | --- |
| `kong_list` | List entities (`GET /<entity>`), with `tags` filtering and `fetch_all` auto-pagination |
| `kong_get` | Get one entity by id or name (`GET /<entity>/<id>`) |
| `kong_create` | Create an entity (`POST /<entity>`) |
| `kong_update` | Partial update (`PATCH /<entity>/<id>`) |
| `kong_upsert` | Create-or-replace (`PUT /<entity>/<id>`) |
| `kong_delete` | Delete (`DELETE /<entity>/<id>`) |
| `kong_request` | **Any** request to **any** Admin API path (the catch-all) |
| `kong_node_info` | Node info & version (`GET /`) |
| `kong_node_status` | Health / DB reachability (`GET /status`) |
| `kong_list_workspaces` | List EE workspaces |
| `kong_plugin_schema` | Get a plugin's config schema (`GET /schemas/plugins/<name>`) |
| `kong_get_config` | Show the active connection settings (token masked) |
| `kong_configure` | Override admin URL / token / workspace / TLS at runtime |

The `entity` argument accepts plain names (`services`, `routes`, `consumers`, `plugins`, `upstreams`, `certificates`, `ca_certificates`, `snis`, `vaults`, `consumer_groups`, …) **and** nested collection paths (`upstreams/<id>/targets`, `services/<id>/routes`, `consumers/<id>/key-auth`, `rbac/roles`, …).

## Install & build

```bash
cd kong-mcp
npm install      # also builds to dist/
npm run build    # rebuild after edits
```

## Configuration

The connection is set via environment variables (see `.env.example`):

| Variable | Default | Description |
| --- | --- | --- |
| `KONG_ADMIN_URL` | `http://localhost:8001` | Base URL of the Admin API |
| `KONG_ADMIN_TOKEN` | _(none)_ | Sent as the `Kong-Admin-Token` header (RBAC) |
| `KONG_WORKSPACE` | _(none)_ | Default EE workspace to scope requests to |
| `KONG_TLS_INSECURE` | `false` | `true` to skip TLS verification (self-signed certs) |
| `KONG_ADMIN_HEADERS` | _(none)_ | Extra headers, e.g. `X-Foo: bar` or a JSON object |

You can also change the URL / token / workspace at runtime by asking the assistant to use the **`kong_configure`** tool — handy for switching between environments in one session.

## Wiring it into an MCP client

### Claude Code

```bash
claude mcp add kong \
  --env KONG_ADMIN_URL=http://localhost:8001 \
  --env KONG_ADMIN_TOKEN=your-rbac-token \
  -- node /Users/monochong/Desktop/kong-mcp/dist/index.js
```

### Claude Desktop / generic `mcp.json`

```json
{
  "mcpServers": {
    "kong": {
      "command": "node",
      "args": ["/Users/monochong/Desktop/kong-mcp/dist/index.js"],
      "env": {
        "KONG_ADMIN_URL": "http://localhost:8001",
        "KONG_ADMIN_TOKEN": "your-rbac-token",
        "KONG_WORKSPACE": "default"
      }
    }
  }
}
```

Restart the client after adding the server.

## Example prompts

- "List all services, then show the routes for the one named `web-api`."
- "Create a service `httpbin` pointing at `http://httpbin.org`, add a route on `/get`, then enable the `rate-limiting` plugin at 100 req/min."
- "Show me the config schema for the `jwt` plugin."
- "Create a consumer `alice` and a key-auth credential for her."
- "Switch to the `staging` workspace and list its plugins." (uses `kong_configure`)
- "What Kong version is running and is the database reachable?"

## Notes

- The token is masked anywhere config is displayed.
- List endpoints follow Kong's `offset`-based pagination; pass `fetch_all: true` to collect every page.
- For DB-less / declarative config, use `kong_request` with `POST /config`.
- Auth failures (401/403) and unreachable endpoints return clear, actionable error messages.

## Development

```bash
npm run dev      # run from TypeScript source via tsx
npm run watch    # tsc --watch
```

## License

MIT