> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentgateway/agentgateway/llms.txt
> Use this file to discover all available pages before exploring further.

# Listeners

> Configure how agentgateway accepts and classifies incoming connections on a port.

Listeners sit inside a [bind](/reference/binds) and describe how agentgateway handles incoming connections on that port. A listener can match traffic by hostname, specify the protocol, configure TLS termination, and group related [routes](/reference/routes).

## Fields

<ParamField path="binds[].listeners[].name" type="string">
  A human-readable name for this listener. Used in logs and metrics to identify the listener. Not required, but recommended for complex configurations with multiple listeners.
</ParamField>

<ParamField path="binds[].listeners[].namespace" type="string">
  The namespace this listener belongs to. Used when agentgateway is managed by a control plane (XDS) to scope resources. For local configurations, this can generally be omitted.
</ParamField>

<ParamField path="binds[].listeners[].hostname" type="string">
  The hostname this listener matches. Incoming requests are matched against this value using the HTTP `Host` header (or SNI for TLS connections).

  Accepts wildcard prefixes: `"*.example.com"` matches `api.example.com` and `admin.example.com`, but not `example.com`.

  When omitted, the listener matches all hostnames not claimed by another listener on the same port.
</ParamField>

<ParamField path="binds[].listeners[].protocol" type="string">
  The protocol to expect on this listener. Accepted values:

  * `HTTP` — Plain HTTP/1.1 or HTTP/2 cleartext.
  * `HTTPS` — HTTP over TLS. Requires `tls` to be configured.

  When omitted, agentgateway infers the protocol from the traffic. For MCP and A2A backends, `HTTP` is the typical choice.
</ParamField>

<ParamField path="binds[].listeners[].tls" type="object">
  TLS configuration for this listener. Required when `protocol` is `HTTPS`. Agentgateway terminates TLS and forwards plaintext to the upstream backend.

  <Expandable title="tls fields">
    <ParamField path="binds[].listeners[].tls.cert" type="string" required>
      Path to the PEM-encoded TLS certificate file (or the certificate contents inline).
    </ParamField>

    <ParamField path="binds[].listeners[].tls.key" type="string" required>
      Path to the PEM-encoded private key file (or the key contents inline).
    </ParamField>

    <ParamField path="binds[].listeners[].tls.root" type="string">
      Path to the PEM-encoded CA certificate bundle used to verify client certificates (mTLS). When omitted, client certificate verification is disabled.
    </ParamField>

    <ParamField path="binds[].listeners[].tls.cipherSuites" type="string[]">
      Optional allowlist of TLS cipher suites. Order is preserved — the first mutually supported suite is used. When omitted, the platform default cipher suites apply.

      Example values: `TLS_AES_128_GCM_SHA256`, `TLS_CHACHA20_POLY1305_SHA256`.
    </ParamField>

    <ParamField path="binds[].listeners[].tls.minTLSVersion" type="string">
      Minimum TLS version to accept. Only `TLSv1_2` and `TLSv1_3` are supported. Defaults to `TLSv1_2`.
    </ParamField>

    <ParamField path="binds[].listeners[].tls.maxTLSVersion" type="string">
      Maximum TLS version to accept. Only `TLSv1_2` and `TLSv1_3` are supported. When omitted, no upper bound is enforced.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="binds[].listeners[].routes" type="array">
  The list of routes this listener forwards traffic to. Routes are evaluated in order; the first match wins.

  See [Routes](/reference/routes) for the full field reference.
</ParamField>

## Examples

### Plain HTTP listener

```yaml theme={null}
binds:
  - port: 8080
    listeners:
      - protocol: HTTP
        routes:
          - backends:
              - host: 127.0.0.1:9090
```

### HTTPS listener with TLS termination

```yaml theme={null}
binds:
  - port: 8443
    listeners:
      - protocol: HTTPS
        tls:
          cert: /etc/certs/server.crt
          key: /etc/certs/server.key
        routes:
          - backends:
              - host: 127.0.0.1:9090
```

### Mutual TLS (mTLS)

Supply a `root` CA to require and verify client certificates.

```yaml theme={null}
binds:
  - port: 8443
    listeners:
      - protocol: HTTPS
        tls:
          cert: /etc/certs/server.crt
          key: /etc/certs/server.key
          root: /etc/certs/ca.crt
        routes:
          - backends:
              - host: 127.0.0.1:9090
```

### TLS with restricted cipher suites and version

```yaml theme={null}
binds:
  - port: 8443
    listeners:
      - protocol: HTTPS
        tls:
          cert: /etc/certs/server.crt
          key: /etc/certs/server.key
          minTLSVersion: TLSv1_3
          maxTLSVersion: TLSv1_3
          cipherSuites:
            - TLS_AES_128_GCM_SHA256
            - TLS_AES_256_GCM_SHA384
        routes:
          - backends:
              - host: 127.0.0.1:9090
```

### Wildcard hostname matching

Use wildcard hostnames to capture all subdomains with one listener.

```yaml theme={null}
binds:
  - port: 8080
    listeners:
      # Handles api.example.com, admin.example.com, etc.
      - hostname: "*.example.com"
        routes:
          - backends:
              - host: internal-service:8080
      # Fallback: any other hostname
      - hostname: "*"
        routes:
          - policies:
              directResponse:
                status: 421
                body: "no listener matched"
```

### Named listeners for observability

Naming listeners makes them easier to identify in logs and distributed traces.

```yaml theme={null}
binds:
  - port: 3000
    listeners:
      - name: mcp-listener
        namespace: production
        routes:
          - backends:
              - mcp:
                  targets:
                    - name: tools
                      stdio:
                        cmd: npx
                        args: ["@modelcontextprotocol/server-everything"]
```

## Hostname matching precedence

When multiple listeners exist on the same port, agentgateway selects the most specific match:

1. Exact hostname match (e.g., `api.example.com`)
2. Wildcard prefix match (e.g., `*.example.com`)
3. Global wildcard (`*`) or no hostname specified

<Note>
  If two listeners share the same hostname on the same port, the behavior is undefined. Ensure each listener on a port has a distinct hostname.
</Note>