CEL expressions

Use Common Expression Language (CEL) in Agentgateway for authorization policies, header transformations, rate limiting, and observability.

Agentgateway uses CEL (Common Expression Language) throughout the request processing pipeline. CEL expressions give you fine-grained, programmable control over authorization, header transformations, rate limiting selectors, and log/trace fields — all evaluated at runtime without restarting the proxy.

What is CEL?

CEL is a fast, safe expression language designed for evaluating user-defined conditions at runtime. Unlike Lua or WASM, CEL is sandboxed and cannot perform I/O or side effects — this makes it predictable, safe to use in a high-performance proxy, and straightforward to reason about.

A simple MCP authorization expression:

jwt.sub == "test-user" && mcp.tool.name == "add"

Where CEL is used

Use case	Example
Authorization policies	jwt.sub == "alice" && mcp.tool.name != "delete"
Log and trace field extraction	request.headers["user-agent"]
HTTP header and body transformations	"Bearer " + jwt.sub
Rate limit selectors	source.address
Tracing sampling	0.1 (10% random sampling)

How expressions are evaluated

Expressions are compiled at configuration load time (not per request). During compilation, Agentgateway extracts which context variables the expression references. At request time, only the referenced data is collected — you only pay for what you use.

Config load → CEL expression parsed → referenced variables extracted
                                              │
                                              ▼
Request arrives → ContextBuilder collects required fields → CEL evaluates expression

This is especially important for expensive fields:

• request.body — causes the body to be buffered in memory (expensive)
• request.headers — header map allocation (moderate cost)
• llm.prompt / llm.completion — large string copies for LLM traffic

Accessing request.body or response.body in a CEL expression causes the full body to be buffered in memory before the expression is evaluated. Avoid this for large payloads unless necessary.

Variable extraction uses static analysis. It handles request.body correctly, but not dynamic access patterns like request["body"]. Stick to dot notation for reliable optimization.

Context reference

The following variables are available in CEL expressions. Availability depends on where in the pipeline the expression runs — for example, response is not available in request-phase transformations.

request — incoming HTTP request

The request object contains attributes about the incoming HTTP request.

Field	Type	Description
request.method	string	HTTP method, e.g. GET
request.uri	string	Complete URI, e.g. http://example.com/path
request.host	string	Hostname, e.g. example.com
request.scheme	string	Scheme, e.g. https
request.path	string	Path component, e.g. /path
request.pathAndQuery	string	Path and query, e.g. /path?foo=bar
request.version	string	HTTP version, e.g. HTTP/1.1
request.headers	map	Request headers (access by name)
request.body	string	Request body (buffers entire body)
request.startTime	timestamp	Time the request started
request.endTime	timestamp	Time the request completed

Examples:

# Allow only GET and POST
request.method in ["GET", "POST"]

# Match a specific path prefix
request.path.startsWith("/api/v2")

# Check a custom header
request.headers["x-tenant-id"] == "acme"

# Use in a log field
request.headers["user-agent"]

response — HTTP response

The response object is available in response-phase expressions (e.g., response transformations, access logs).

Field	Type	Description
response.code	int	HTTP status code
response.headers	map	Response headers
response.body	string	Response body (buffers entire body)

Examples:

# Log only error responses
response.code >= 400

# Check a response header
response.headers["content-type"].contains("application/json")

jwt — JWT token claims

The jwt object contains claims from a verified JWT token. It is only present when the JWT authentication policy is enabled and a valid token is provided.

Field	Type	Description
jwt.sub	string	Subject claim
jwt.iss	string	Issuer claim
jwt.aud	list	Audience claim
jwt.<claim>	any	Any custom claim from the token

Examples:

# Allow a specific user
jwt.sub == "[e-mail]"

# Check a custom role claim
jwt.roles.contains("admin")

# Require a specific issuer
jwt.iss == "https://auth.example.com"

# Combine user and tool checks (MCP)
jwt.sub == "test-user" && mcp.tool.name == "add"

jwt is only available after the JWT policy has verified the token. If authentication fails, the request is rejected before authorization expressions run.

mcp — MCP request context

The mcp object contains attributes about an MCP request. It is available when the route handles MCP traffic.

Field	Type	Description
mcp.tool.name	string	Name of the MCP tool being called
mcp.tool.target	string	Target server for the tool call
mcp.resource.name	string	Name of the MCP resource being accessed
mcp.resource.target	string	Target server for the resource
mcp.prompt.name	string	Name of the MCP prompt being requested
mcp.prompt.target	string	Target server for the prompt

Examples:

# Allow access to a specific tool only
mcp.tool.name == "get_weather"

# Block a dangerous tool
mcp.tool.name != "delete_all"

# Allow only reads (tools starting with "get" or "list")
mcp.tool.name.startsWith("get") || mcp.tool.name.startsWith("list")

# Restrict a user to specific tools
jwt.sub == "readonly-bot" && mcp.tool.name in ["search", "get_item"]

# Check which backend is serving the request
mcp.tool.target == "production-server"

llm — LLM request and response

The llm object contains attributes about an LLM request or response. It is only present when using an ai backend.

Field	Type	Description
llm.streaming	bool	Whether the response is streamed
llm.requestModel	string	Model requested by the client
llm.responseModel	string	Model that served the response
llm.provider	string	LLM provider name
llm.inputTokens	int	Input/prompt token count
llm.outputTokens	int	Output/completion token count
llm.totalTokens	int	Total token count
llm.cachedInputTokens	int	Tokens read from cache (savings)
llm.reasoningTokens	int	Reasoning tokens in output
llm.prompt	list	Prompt messages (has performance impact)
llm.completion	string	Completion text (has performance impact)
llm.params.temperature	float	Temperature parameter
llm.params.max_tokens	int	Max tokens parameter

Examples:

# Log total token usage
llm.totalTokens

# Alert on large requests
llm.inputTokens > 10000

# Rate limit by model
llm.requestModel == "gpt-4"

# Block non-streaming requests to a specific model
llm.requestModel == "claude-3" && !llm.streaming

source — connection source

The source object contains attributes about the downstream connection.

Field	Type	Description
source.address	string	IP address of the downstream connection
source.port	int	Port of the downstream connection
source.identity	object	SPIFFE identity (if mTLS is enabled)
source.identity.trustDomain	string	SPIFFE trust domain
source.identity.namespace	string	Kubernetes namespace
source.identity.serviceAccount	string	Kubernetes service account
source.subjectAltNames	list	SANs from the downstream certificate
source.issuer	string	Issuer from the downstream certificate
source.subject	string	Subject from the downstream certificate

Examples:

# Allow only from a specific IP range (use for rate limiting key)
source.address

# Require a specific Kubernetes service account (mTLS)
source.identity.serviceAccount == "my-agent"

# Restrict to a specific namespace
source.identity.namespace == "production"

backend — upstream backend info

The backend object contains information about the backend selected for the request.

Field	Type	Description
backend.name	string	Backend name, e.g. my-service
backend.type	string	Backend type: ai, mcp, static, dynamic, service
backend.protocol	string	Backend protocol: http, tcp, a2a, mcp, llm

Examples:

# Log the backend name (useful in access logs)
backend.name

# Different behavior based on backend type
backend.type == "mcp"

apiKey and basicAuth — API key and basic auth

These objects are present when the corresponding authentication policy is enabled and credentials have been verified.

Field	Type	Description
apiKey.key	string	The verified API key value
basicAuth.username	string	The verified username

Examples:

# Restrict to a specific API key holder
apiKey.key == "internal-service-key"

# Use the username in an authorization rule
basicAuth.username == "admin"

env — environment variables

The env object exposes a curated subset of well-known environment attributes. It does not expose raw process environment variables.

Field	Type	Description
env.podName	string	Kubernetes pod name
env.namespace	string	Kubernetes namespace
env.gateway	string	Gateway name (Kubernetes)

Examples:

# Include pod name in logs
env.podName

# Namespace-aware routing logic
env.namespace == "staging"

Authorization policy examples

CEL expressions are most commonly used in authorization (authz) policies. Here are practical examples:

JWT + MCP tool authorization

routes:
- policies:
    auth:
      jwt:
        issuer: https://auth.example.com
    authz:
      rules:
      # Only allow verified users to call the "add" tool
      - expression: 'jwt.sub == "test-user" && mcp.tool.name == "add"'
  backends:
  - mcp:
      targets:
      - name: calculator
        stdio:
          cmd: npx
          args: ["mcp-server-calculator"]

routes:
- policies:
    auth:
      jwt:
        issuer: https://auth.example.com
    authz:
      rules:
      # Admins can call any tool; regular users get read-only tools
      - expression: |
          jwt.roles.contains("admin") ||
          mcp.tool.name.startsWith("get") ||
          mcp.tool.name.startsWith("list")
  backends:
  - mcp:
      targets:
      - name: my-server
        host: mcp-server:8080

routes:
- policies:
    authz:
      rules:
      # Only allow requests from the "agent" service account in production
      - expression: |
          source.identity.serviceAccount == "agent" &&
          source.identity.namespace == "production"
  backends:
  - host: internal-service:8080

routes:
- policies:
    rateLimit:
      # Rate limit per JWT subject
      key: 'jwt.sub'
      requests: 1000
      window: 60s
  backends:
  - mcp:
      targets:
      - name: ai-tools
        host: ai-tools:8080

Authorization guide

Complete guide to setting up CEL-based authorization policies

MCP proxy guide

Proxy MCP servers with tool-level access control