Skip to main content
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

FieldDescription
tls.certPath to the PEM-encoded certificate file
tls.keyPath to the PEM-encoded private key file
tls.rootOptional path to a CA certificate for client verification (mTLS)
tls.cipherSuitesOptional cipher suite allowlist — order is preserved
tls.minTLSVersionMinimum TLS version. Only 1.2 and 1.3 are supported
tls.maxTLSVersionMaximum 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:
  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

​
Supported cipher suites

Cipher suite
TLS13_AES_256_GCM_SHA384
TLS13_AES_128_GCM_SHA256
TLS13_CHACHA20_POLY1305_SHA256
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