TLS configuration

Configure TLS termination, cipher suites, backend TLS, and mutual TLS for agentgateway listeners.

Agentgateway supports HTTPS listeners with full TLS termination, configurable cipher suites, TLS version pinning, backend TLS for upstream connections, and mutual TLS (mTLS) for client certificate authentication.

Basic TLS termination

To expose a listener over HTTPS, set the listener protocol to HTTPS and supply a tls block with the paths to your certificate and private key.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
binds:
- port: 3000
  listeners:
  - name: default
    protocol: HTTPS
    tls:
      cert: examples/tls/certs/cert.pem
      key: examples/tls/certs/key.pem
    routes:
    - backends:
      - mcp:
          targets:
          - name: everything
            stdio:
              cmd: npx
              args: ["@modelcontextprotocol/server-everything"]

This is the exact configuration from examples/tls/config.yaml. Self-signed certificates require the -k flag when testing with curl.

Verify that TLS is working:

curl https://localhost:3000 -k
# Not Acceptable: Client must accept text/event-stream

The request fails because no valid MCP request was sent, but the TLS handshake succeeded.

The MCP Inspector does not support unverified (self-signed) TLS certificates. Use curl -k or a CA-signed certificate when testing.

TLS fields reference

Field	Description
tls.cert	Path to the PEM-encoded certificate file
tls.key	Path to the PEM-encoded private key file
tls.root	Optional path to a CA certificate for client verification (mTLS)
tls.cipherSuites	Optional cipher suite allowlist — order is preserved
tls.minTLSVersion	Minimum TLS version. Only 1.2 and 1.3 are supported
tls.maxTLSVersion	Maximum TLS version. Only 1.2 and 1.3 are supported

Cipher suites

You can restrict which cipher suites the listener negotiates. The order you specify is preserved — agentgateway will prefer suites listed first.

TLS 1.3 only

tls:
  cert: certs/cert.pem
  key: certs/key.pem
  minTLSVersion: "1.3"
  cipherSuites:
    - TLS13_AES_256_GCM_SHA384
    - TLS13_AES_128_GCM_SHA256
    - TLS13_CHACHA20_POLY1305_SHA256

TLS 1.2 + 1.3

tls:
  cert: certs/cert.pem
  key: certs/key.pem
  minTLSVersion: "1.2"
  maxTLSVersion: "1.3"
  cipherSuites:
    - TLS13_AES_256_GCM_SHA384
    - TLS13_AES_128_GCM_SHA256
    - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

Supported cipher suites

TLS 1.3 cipher suites

Cipher suite
TLS13_AES_256_GCM_SHA384
TLS13_AES_128_GCM_SHA256
TLS13_CHACHA20_POLY1305_SHA256

TLS 1.2 cipher suites

Cipher suite
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

TLS version control

Agentgateway supports TLS 1.2 and TLS 1.3 only. Use minTLSVersion and maxTLSVersion to pin the acceptable range.

tls:
  cert: certs/cert.pem
  key: certs/key.pem
  minTLSVersion: "1.2"
  maxTLSVersion: "1.3"

Attempts to configure versions below TLS 1.2 are not supported.

Backend TLS

When agentgateway proxies traffic to an upstream service that requires TLS, configure backendTLS on the route policy. Agentgateway will use the system trusted CA certificates by default, and automatically derive the SNI from the destination hostname.

binds:
- port: 3000
  listeners:
  - routes:
    - backends:
      - mcp:
          targets:
          - name: secure-upstream
            http:
              host: api.example.com
              port: 443
      policies:
        backendTLS:
          tls: {}

Custom CA certificate

To verify the upstream with a custom CA, reference a ConfigMap containing the CA certificate:

policies:
  backendTLS:
    tls:
      caCertificateRefs:
        - name: my-ca-configmap

Custom SNI

Override the SNI sent during the TLS handshake:

policies:
  backendTLS:
    tls:
      sni: api.internal.example.com

Skip verification (insecure)

Skipping TLS verification is insecure. Only use this in development environments.

policies:
  backendTLS:
    tls:
      insecureSkipVerify: All

The Hostname mode verifies the CA certificate but ignores hostname/SAN mismatches.

Mutual TLS (mTLS)

mTLS requires clients to present a certificate signed by a trusted CA. Set the tls.root field to the CA certificate path on the listener.

binds:
- port: 3000
  listeners:
  - name: mtls-listener
    protocol: HTTPS
    tls:
      cert: certs/server-cert.pem
      key: certs/server-key.pem
      root: certs/ca-cert.pem
    routes:
    - backends:
      - mcp:
          targets:
          - name: everything
            stdio:
              cmd: npx
              args: ["@modelcontextprotocol/server-everything"]

Backend mTLS

To use a client certificate when connecting to a backend (outbound mTLS), reference a Kubernetes Secret containing the client certificate:

policies:
  backendTLS:
    tls:
      mtlsCertificateRef:
        - name: client-tls-secret

The Secret must be of type kubernetes.io/tls with tls.crt and tls.key data fields. An optional ca.crt field, if present, will be used to verify the server certificate.

Complete example

1. Generate a self-signed certificate

   openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
     -days 365 -nodes -subj '/CN=localhost'
   
2. Write the agentgateway config

   # yaml-language-server: $schema=https://agentgateway.dev/schema/config
   binds:
   - port: 3000
     listeners:
     - name: default
       protocol: HTTPS
       tls:
         cert: cert.pem
         key: key.pem
         minTLSVersion: "1.2"
         cipherSuites:
           - TLS13_AES_256_GCM_SHA384
           - TLS13_AES_128_GCM_SHA256
           - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
       routes:
       - backends:
         - mcp:
             targets:
             - name: everything
               stdio:
                 cmd: npx
                 args: ["@modelcontextprotocol/server-everything"]
   
3. Start agentgateway

   cargo run -- -f config.yaml
   
4. Test the connection

   curl https://localhost:3000 -k
   # Not Acceptable: Client must accept text/event-stream