Kuadrant MCP Server

A Model Context Protocol (MCP) server that generates Kuadrant policy manifests in YAML format. Designed to work alongside Kubernetes MCP servers like mcp-server-kubernetes for applying resources to clusters.

Demo

Quick Start (Claude Code CLI)

# Add the MCP server using Docker (available in all projects)
claude mcp add kuadrant docker run -i --rm ghcr.io/jasonmadigan/kuadrant-mcp-server:latest -s user

# Verify installation
claude mcp list

# Start using
claude  # Start new session, type /mcp to see available servers

Overview

This MCP server generates Kuadrant-specific Kubernetes manifests:

Gateway resources with Kuadrant annotations
HTTPRoute configurations
Kuadrant policies (DNS, TLS, RateLimit, Auth)

All manifests are generated in YAML format, matching the actual Kuadrant CRD specifications.

Installation

Using Go

go install github.com/jasonmadigan/kuadrant-mcp-server@latest

Using Docker

The server is available as a Docker image from GitHub Container Registry:

docker pull ghcr.io/jasonmadigan/kuadrant-mcp-server:latest

Building from Source

git clone https://github.com/jasonmadigan/kuadrant-mcp-server
cd kuadrant-mcp-server
docker build -t kuadrant-mcp-server:latest .

Usage

Transport Options

The server supports multiple transport protocols:

stdio (default) - Standard input/output for CLI integration
sse - Server-Sent Events for web-based clients
http - Streamable HTTP for modern web applications

Standalone

Using stdio transport (default)

kuadrant-mcp-server

Using SSE transport

kuadrant-mcp-server -transport sse -addr :8080

Using StreamableHTTP transport

kuadrant-mcp-server -transport http -addr :8080

With Docker

Using the pre-built image from GitHub Container Registry:

stdio transport (default)

docker run -i --rm ghcr.io/jasonmadigan/kuadrant-mcp-server:latest

SSE transport

docker run -i --rm -p 8080:8080 ghcr.io/jasonmadigan/kuadrant-mcp-server:latest -transport sse -addr :8080

StreamableHTTP transport

docker run -i --rm -p 8080:8080 ghcr.io/jasonmadigan/kuadrant-mcp-server:latest -transport http -addr :8080

With Docker Compose

docker-compose up

MCP Client Configuration

For stdio transport (Claude Desktop, CLI tools)

Using the pre-built Docker image:

{
  "mcpServers": {
    "kuadrant": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/jasonmadigan/kuadrant-mcp-server:latest"]
    }
  }
}

Or if running the binary directly:

{
  "mcpServers": {
    "kuadrant": {
      "command": "/path/to/kuadrant-mcp-server"
    }
  }
}

For HTTP transports (web applications)

{
  "mcpServers": {
    "kuadrant-mcp": {
      "url": "http://localhost:8080",
      "transport": "streamablehttp"  // or "sse" for SSE transport
    }
  }
}

Available Resources

The MCP server provides comprehensive documentation and examples through resources:

Documentation Resources

kuadrant://docs/gateway-api - Gateway API overview and Kuadrant integration
kuadrant://docs/dnspolicy - Complete DNSPolicy reference with examples
kuadrant://docs/ratelimitpolicy - RateLimitPolicy patterns and advanced usage
kuadrant://docs/authpolicy - AuthPolicy authentication and authorization methods
kuadrant://docs/tlspolicy - TLSPolicy certificate management guide

Example Resources

kuadrant://examples/basic-setup - Simple API with rate limiting and API key auth
kuadrant://examples/production-setup - Full production setup with TLS, DNS, JWT auth

Troubleshooting

kuadrant://troubleshooting - Common issues, debugging techniques, and solutions

Access these resources in Claude by asking questions like:

"Show me the Kuadrant rate limiting documentation"
"How do I set up production TLS with Kuadrant?"
"Help me troubleshoot my AuthPolicy not working"

Note: Claude may not always use resources automatically. To ensure resource usage:

Be specific about wanting documentation or examples
Reference Kuadrant policies by name (e.g., "RateLimitPolicy", "AuthPolicy")
Ask for "complete examples" or "troubleshooting guide"

Available Tools

`create_gateway`

Generate a Gateway manifest with Kuadrant annotations.

Arguments:

name (required): Gateway name
namespace (required): Namespace
gatewayClassName: Gateway class (default: "istio")
listeners: Array of listener configurations
kuadrantEnabled: Enable Kuadrant annotations (default: true)

Example Output:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  annotations:
    kuadrant.io/policy: enabled
  name: prod-gateway
  namespace: production
spec:
  gatewayClassName: istio
  listeners:
  - name: https
    port: 443
    protocol: HTTPS
    hostname: "*.example.com"

`create_httproute`

Generate an HTTPRoute manifest.

Arguments:

name (required): Route name
namespace (required): Namespace
parentRefs (required): Parent gateway references
hostnames: List of hostnames
rules: Routing rules

Example Output:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
  namespace: production
spec:
  parentRefs:
  - name: prod-gateway
  hostnames:
  - api.example.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: api-service
      port: 8080

`create_dnspolicy`

Generate a Kuadrant DNSPolicy manifest.

Arguments:

name (required): Policy name
namespace (required): Namespace
targetRef (required): Target resource reference
providerRefs (required): DNS provider references
loadBalancing: Load balancing configuration
healthCheck: Health check configuration

Example Output:

apiVersion: kuadrant.io/v1
kind: DNSPolicy
metadata:
  name: prod-dns
  namespace: production
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: prod-gateway
  providerRefs:
  - name: aws-dns-credentials
  loadBalancing:
    defaultGeo: true
    weight: 100
    geo: US
  healthCheck:
    path: /health
    failureThreshold: 3
    interval: 5min

`create_tlspolicy`

Generate a Kuadrant TLSPolicy manifest (v1alpha1).

Arguments:

name (required): Policy name
namespace (required): Namespace
targetRef (required): Target resource reference
issuerRef (required): Certificate issuer reference
commonName: Certificate common name
duration: Certificate duration
renewBefore: Renew before expiry

Example Output:

apiVersion: kuadrant.io/v1alpha1
kind: TLSPolicy
metadata:
  name: prod-tls
  namespace: production
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: prod-gateway
  issuerRef:
    group: cert-manager.io
    kind: ClusterIssuer
    name: letsencrypt-prod
  commonName: "*.example.com"
  duration: 90d
  renewBefore: 15d

`create_ratelimitpolicy`

Generate a Kuadrant RateLimitPolicy manifest.

Arguments:

name (required): Policy name
namespace (required): Namespace
targetRef (required): Target resource reference
limits: Rate limit configurations (each limit must have a rates array with limit and window fields)
defaults: Default rate limits
overrides: Override rate limits

Important: Rate limits must use the format:

{
  "limit-name": {
    "rates": [
      {
        "limit": 100,
        "window": "60s"  // Use time units: s, m, h (e.g., "10s", "5m", "1h")
      }
    ]
  }
}

Example Output:

apiVersion: kuadrant.io/v1
kind: RateLimitPolicy
metadata:
  name: api-limit
  namespace: production
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: api-route
  limits:
    "global":
      rates:
      - limit: 5
        window: 10s
    "per-user":
      rates:
      - limit: 2
        window: 10s
      when:
      - predicate: "auth.identity.userid == 'bob'"

`create_authpolicy`

Generate a Kuadrant AuthPolicy manifest.

Arguments:

name (required): Policy name
namespace (required): Namespace
targetRef (required): Target resource reference
rules: Authentication and authorization rules
defaults: Default auth rules
overrides: Override auth rules

Example Output:

apiVersion: kuadrant.io/v1
kind: AuthPolicy
metadata:
  name: api-auth
  namespace: production
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: api-route
  rules:
    authentication:
      jwt-auth:
        jwt:
          issuerUrl: https://auth.example.com
    authorization:
      api-users:
        opa:
          rego: |
            allow = true {
              input.auth.identity.groups[_] == "api-users"
            }

Kubernetes Integration

For a complete Kubernetes workflow, you can combine this server with the Kubernetes MCP server.

Installing Kubernetes MCP Server

# Install globally
npm install -g @flux159/mcp-server-kubernetes

# Or use directly with npx
npx @flux159/mcp-server-kubernetes

The Kubernetes MCP server will:

Automatically use your ~/.kube/config
Connect to your current kubectl context
Provide tools for managing Kubernetes resources

Configuration

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

Using Docker (recommended):

{
  "mcpServers": {
    "kuadrant": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/jasonmadigan/kuadrant-mcp-server:latest"]
    },
    "kubernetes": {
      "command": "npx",
      "args": ["@flux159/mcp-server-kubernetes"]
    }
  }
}

Or using the binary directly:

{
  "mcpServers": {
    "kuadrant": {
      "command": "/path/to/kuadrant-mcp-server"
    },
    "kubernetes": {
      "command": "npx",
      "args": ["@flux159/mcp-server-kubernetes"]
    }
  }
}

Claude Code CLI

# Add Kuadrant server
claude mcp add kuadrant /path/to/kuadrant-mcp-server -s user

# Add Kubernetes server
claude mcp add kubernetes npx @flux159/mcp-server-kubernetes -s user

Safe Mode

To prevent destructive operations, run the Kubernetes server in safe mode:

# In Claude Desktop config:
{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["@flux159/mcp-server-kubernetes"],
      "env": {
        "ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS": "true"
      }
    }
  }
}

# Or with Claude Code CLI:
ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true npx @flux159/mcp-server-kubernetes

Example Workflow

With both servers configured, you can:

Generate and Deploy:

Create a production gateway using Kuadrant and deploy it to my Kubernetes cluster

Create Complete Setup:

Create a Gateway with TLS and rate limiting policies, then apply them all to the production namespace in my Kubernetes cluster

Check Status:

Show me all Gateways and their associated Kuadrant policies in my Kubernetes cluster

Real Example

User: Create a production API gateway with HTTPS and rate limiting, then deploy it

Assistant will:

Use kuadrant MCP to generate Gateway manifest
Use kuadrant MCP to generate RateLimitPolicy
Use kubernetes MCP to apply both manifests
Use kubernetes MCP to verify deployment status

Complete Example Workflow

Here's a complete example setting up a Gateway with all policies:

Generate Gateway

# Generated output:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
  namespace: production
spec:
  parentRefs:
  - name: api-gateway
  hostnames:
  - api.example.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /v1
    backendRefs:
    - name: api-v1
      port: 8080

Generate DNSPolicy

# Generated output:
apiVersion: kuadrant.io/v1
kind: DNSPolicy
metadata:
  name: api-dns
  namespace: production
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: api-gateway
  providerRefs:
  - name: route53-credentials

Generate RateLimitPolicy

# Generated output:
apiVersion: kuadrant.io/v1
kind: RateLimitPolicy
metadata:
  name: api-ratelimit
  namespace: production
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: api-route
  limits:
    "global":
      rates:
      - limit: 10
        window: 60s

Generate AuthPolicy

# Generated output:
apiVersion: kuadrant.io/v1
kind: AuthPolicy
metadata:
  name: api-auth
  namespace: production
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: api-route
  rules:
    authentication:
      jwt:
        jwt:
          issuerUrl: https://auth.example.com/realms/api

API Version Reference

Gateway/HTTPRoute: gateway.networking.k8s.io/v1
DNSPolicy: kuadrant.io/v1
TLSPolicy: kuadrant.io/v1alpha1
RateLimitPolicy: kuadrant.io/v1
AuthPolicy: kuadrant.io/v1

Building from Source

git clone https://github.com/jasonmadigan/kuadrant-mcp-server
cd kuadrant-mcp-server
go build -o kuadrant-mcp-server

Claude Code CLI Setup

To use this server with Claude Code CLI:

Option 1: Using Docker (Recommended)

# Add using Docker image
claude mcp add kuadrant docker run -i --rm ghcr.io/jasonmadigan/kuadrant-mcp-server:latest -s user

# Verify installation
claude mcp list

# Start using
claude  # Start new session, type /mcp to see available servers

Option 2: Using Local Binary

Build the server
```
go build -o kuadrant-mcp-server
```

Add to Claude Code

claude mcp add kuadrant /path/to/kuadrant-mcp-server

For example:

claude mcp add kuadrant /Users/yourusername/kuadrant-mcp-server/kuadrant-mcp-server

Verify installation
```
claude mcp list
```
Test in Claude Start a new Claude session and type:
```
/mcp
```
You should see "kuadrant" listed. Then try:
```
Create a Gateway manifest named 'test-gateway' in namespace 'default'
```

Troubleshooting

If /mcp shows "No MCP servers configured":

Make sure you're in the same directory where you ran claude mcp add (for project/local scope)
The MCP configuration scopes are:
- local: Private to you in the current project (default)
- user: Available to you in all projects
- project: Shared with all users in the current project
Try adding with the full absolute path
Check the server is executable: chmod +x kuadrant-mcp-server
Start a new Claude session after adding the server

Enable Logging (Optional)

To see when Claude uses your MCP server:

Use the logging wrapper script:

chmod +x run_with_logging.sh
claude mcp remove kuadrant -s local
claude mcp add kuadrant /path/to/kuadrant-mcp-server/run_with_logging.sh

Monitor the logs:
```
tail -f /tmp/kuadrant-mcp.log
```

Testing Your Installation

After setting up the MCP server, test it with these commands in Claude:

Verify MCP tools are available in Claude:
```
/mcp
```
You should see "kuadrant" listed. Then check what tools it provides:
```
What tools does the kuadrant MCP server provide?
```
Monitor the logs (in a separate terminal):
```
tail -f /tmp/kuadrant-mcp.log
```

Test with natural language commands in Claude:

# Gateway creation
Create a Kuadrant Gateway named 'api-gateway' in the 'gateway-system' namespace with HTTPS enabled and apply this in my Kubernetes cluster with the kubernetes tool

# HTTPRoute creation  
Create an HTTPRoute named 'api-routes' in namespace 'gateway-system' that routes traffic from gateway 'api-gateway' to service 'api-backend' on port 8080 and apply this in my Kubernetes cluster with the kubernetes tool

# Rate limiting
Create a RateLimitPolicy that limits requests to 100 per minute for the HTTPRoute 'api-routes' in namespace 'gateway-system' and apply this in my Kubernetes cluster with the kubernetes tool

# Per-user rate limiting
Create a RateLimitPolicy for HTTPRoute 'api-routes' that allows 5 requests per 10 seconds for user 'alice' and 2 requests per 10 seconds for user 'bob' and apply this in my Kubernetes cluster with the kubernetes tool

# Authentication
Create an AuthPolicy for HTTPRoute 'api-routes' that requires JWT authentication from issuer 'https://auth.example.com' and apply this in my Kubernetes cluster with the kubernetes tool

# DNS management
Create a DNSPolicy for gateway 'api-gateway' using AWS Route53 credentials 'route53-creds' with multi-region load balancing and apply this in my Kubernetes cluster with the kubernetes tool

# TLS certificates
Create a TLSPolicy for gateway 'api-gateway' using Let's Encrypt to get a wildcard certificate for '*.example.com' and apply this in my Kubernetes cluster  with the kubernetes tool

With Kubernetes integration:

Create a production API gateway with rate limiting of 50 requests per minute and deploy it to my Kubernetes cluster with the kubernetes tool

Generate a complete Kuadrant setup with Gateway, HTTPRoute, rate limiting, and JWT auth for my API, then apply it to the 'gateway-system' namespace in my Kubernetes cluster with the kubernetes tool

Common real-world scenarios:

E-commerce API protection:

I need to protect my e-commerce API. Create a Gateway with rate limiting that allows regular users 100 requests per minute but gives premium users 1000 requests per minute and apply this in my Kubernetes cluster

Multi-tenant SaaS platform:

Set up a Gateway for my SaaS platform with different rate limits per tenant: 
- Free tier: 10 requests per minute
- Pro tier: 100 requests per minute
- Enterprise: unlimited
Then apply this configuration to my Kubernetes cluster

Public API with authentication:

Create a public API gateway that requires API key authentication and limits each API key to 50 requests per second and deploy it to my Kubernetes cluster

Complete production setup:

Set up a production-ready API gateway with:
- HTTPS using Let's Encrypt certificates
- JWT authentication from Auth0
- Rate limiting of 1000 requests per hour per user
- DNS managed by Route53
Then deploy everything to my Kubernetes cluster

What you should see in the logs:

[KUADRANT MCP] Starting server with transport=stdio
[KUADRANT MCP] create_gateway called with name=api-gateway, namespace=production
[KUADRANT MCP] create_httproute called with name=api-route, namespace=production
[KUADRANT MCP] create_ratelimitpolicy called with name=api-route, namespace=production

If you don't see logs:

Type /mcp in Claude - verify "kuadrant" is listed
Make sure you started a new Claude session after adding the server
Try being more explicit: "Use the kuadrant MCP server to create a Gateway"

Common Issues

RateLimitPolicy format errors:

If you get errors like "unknown field spec.limits.xxx.rates[0].duration", make sure your rate limits use the correct format:

✅ Correct:

rates:
- limit: 100
  window: 60s    # or "1m", "5m", "1h", etc.

❌ Incorrect:

rates:
- limit: 100
  duration: 60
  unit: second

MCP Configuration

To use this server with an MCP client (like Claude Desktop), add it to your MCP configuration:

Using the pre-built Docker image:

{
  "mcpServers": {
    "kuadrant": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/jasonmadigan/kuadrant-mcp-server:latest"]
    }
  }
}

Or if running the binary locally:

{
  "mcpServers": {
    "kuadrant": {
      "command": "/path/to/kuadrant-mcp-server"
    }
  }
}

License

Apache 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github/workflows		.github/workflows
examples		examples
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
kuadrant-mcp-server-demo.gif		kuadrant-mcp-server-demo.gif
kuadrant-mcp-server-demo.mp4		kuadrant-mcp-server-demo.mp4
main.go		main.go
resources.go		resources.go
run_with_logging.sh		run_with_logging.sh

Kuadrant/kuadrant-mcp-server

Folders and files

Latest commit

History

Repository files navigation

Kuadrant MCP Server

Demo

Quick Start (Claude Code CLI)

Overview

Installation

Using Go

Using Docker

Building from Source

Usage

Transport Options

Standalone

Using stdio transport (default)

Using SSE transport

Using StreamableHTTP transport

With Docker

stdio transport (default)

SSE transport

StreamableHTTP transport

With Docker Compose

MCP Client Configuration

For stdio transport (Claude Desktop, CLI tools)

For HTTP transports (web applications)

Available Resources

Documentation Resources

Example Resources

Troubleshooting

Available Tools

create_gateway

create_httproute

create_dnspolicy

create_tlspolicy

create_ratelimitpolicy

create_authpolicy

Kubernetes Integration

Installing Kubernetes MCP Server

Configuration

Claude Desktop

Claude Code CLI

Safe Mode

Example Workflow

Real Example

Complete Example Workflow

API Version Reference

Building from Source

Claude Code CLI Setup

Option 1: Using Docker (Recommended)

Option 2: Using Local Binary

Troubleshooting

Enable Logging (Optional)

Testing Your Installation

Common Issues

MCP Configuration

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

`create_gateway`

`create_httproute`

`create_dnspolicy`

`create_tlspolicy`

`create_ratelimitpolicy`

`create_authpolicy`

Packages