By Greg Nowak. Last updated 2026-09-24.
NGINX 1.31.5 changes a long-standing assumption about reverse proxies. The URL no longer has to carry all the information needed to choose a route. NGINX can read a request body early, extract a value from JSON, store it in a variable, and use that variable during location selection.
That matters for MCP, GraphQL, and other AI-facing APIs that funnel several operations through one endpoint. A request to /mcp, for example, could be a tool call, a resource lookup, or another method entirely. NGINX can now separate selected operations at the edge instead of sending every request to the same application router.
The feature is useful, but it also gives the proxy more work and more responsibility. The practical decision is which classifications are stable and simple enough to maintain in NGINX without turning the proxy configuration into a second application.
What changed in NGINX 1.31.5
The NGINX 1.31.5 announcement introduces four related capabilities: predicate locations, early request-body reading, native JSON extraction, and an open-source Control API. The independent 1.31.5 change log confirms that all four landed in the release.
Predicate locations let an evaluated variable take part in location selection. NGINX treats the predicate as true when its value is neither empty nor 0. Enable client_body_early_read, and NGINX buffers the body before matching the location. The JSON module can then pull out a field such as an MCP method and expose it to a map or predicate location.
Once that classification exists, familiar NGINX controls can act on it. Requests arriving at the same URI can go to different upstreams, receive different rate limits, be rejected, or be logged with a more useful operation label.
Where this approach earns its keep
The cleanest use case is narrow classification based on a stable field. Sending a handful of known MCP methods to different upstream classes is plausible. Recreating application authorization rules or business workflows in proxy configuration is much harder to justify.
A short method-to-upstream map is easy to review and test. A growing collection of nested predicates tends to age badly as application behaviour changes. NGINX makes the same point in its predicate-routing guidance: complex predicates, particularly those that read request bodies, can reduce performance. The guidance recommends a catch-all location, selective early reading, deliberate predicate ordering, meaningful names, and logs that include the variables behind the routing decision.
| Routing decision | Likely home | What to check |
|---|---|---|
| Split a few stable JSON method values | NGINX | Can each value map directly to an upstream or limit? |
| Apply coarse rate limits by operation class | NGINX | Is the classification useful before application code runs? |
| Interpret changing business state | Application | Does the decision need to change with domain logic? |
| Make complex authorization decisions | Application or policy layer | Are identity context and failure semantics explicit and testable? |
| Inspect large or highly variable bodies | Benchmark before deciding | What do buffering and parsing cost under realistic load? |
Body inspection has a real operating cost
Path- and header-based routing can choose a destination before consuming the payload. Early body inspection changes the order of events. NGINX must first receive and buffer the body, then evaluate the predicate and select a location. The release announcement describes this sequence, and the predicate-routing guidance notes that larger bodies require more memory and CPU.
AI API traffic makes averages especially unhelpful. A useful staging test needs to reflect the actual spread of body sizes and concurrent requests. It should also include slow uploads, invalid JSON, missing routing fields, and requests that never needed body inspection in the first place. Compare latency, memory use, CPU load, temporary-file activity where applicable, and upstream timing with early reading enabled and disabled.
There is no reason to inspect every request by default. NGINX documents that variables can control early body reading, allowing a path or header to narrow the candidate traffic first. Requests whose destination is already clear can stay on the cheaper route.
Check the binary, then test the awkward inputs
The JSON module documentation states that ngx_http_json_module is not built by default. The binary must be configured with --with-http_json_module. Seeing version 1.31.5 in production therefore does not prove that the proposed configuration will work.
On first access to an extracted variable, the parser processes the JSON document once for that request, even if the configuration asks for several values. Its default maximum nesting depth is 32, configurable from 1 to 256. When the source is empty, incomplete, invalid JSON, or missing the requested member, the extracted variables are not found.
Those cases need a conservative, explicit fallback. A missing or malformed value must never slip into a privileged, lightly limited, or specialist route because a predicate behaved differently than someone expected. The test set should include absent members, 0, false-like values, arrays, excessive nesting, incomplete bodies, and unexpected value types.
Treat the Control API as a separate security decision
The new Control API is useful for operations, but it is not an ordinary public HTTP endpoint. It can return worker-process information, expose the configuration currently loaded in memory, and trigger a reload with immediate logs. The runtime Control API documentation says the API is disabled by default and requires NGINX Open Source to be built with --with-control-api.
Access control deserves particular care. NGINX recommends a Unix-domain socket protected by filesystem permissions and says the API should never be exposed to the public internet. The release announcement adds the reason plainly: the interface is unauthenticated and exposes NGINX internals. A protected Unix socket keeps that management surface away from the network listener serving the AI API.
The deployment process still needs familiar safeguards. Validate the candidate configuration, reload through the protected local interface, capture the response, check worker health, and keep a tested rollback route. Faster feedback from the Control API does not make release discipline optional.
How to evaluate it without overcommitting
Choose one operation class with a clear operational benefit, such as a stable method that needs separate upstream capacity or its own rate limit. Reproduce representative traffic in staging, confirm the binary’s build flags, and create an explicit catch-all route. Log the extracted class and the route selected, while keeping full prompts and tool arguments out of the proxy logs.
Next, benchmark realistic concurrency and body sizes. Send malformed input deliberately and verify that every ambiguous case lands on the safe fallback. A limited production rollout should begin only after the dashboards and rollback criteria are ready. Additional predicates can follow when each one solves a specific operational problem.
Used with restraint, payload-aware routing can remove an unnecessary application hop and bring NGINX controls into play earlier. Push too much policy into it, however, and a fast routing layer becomes another place where application behaviour must be tested and maintained. The sensible boundary is the one your team can explain, observe, and reverse under pressure.
If you want a practical second pair of hands, Greg can help reproduce the workload in staging, verify the required modules, measure the cost of body inspection, and shape a limited rollout with safe fallbacks, useful logs, and a tested rollback path.
Related on GrN.dk
- Google’s 2026 AI Search Guidance: SEO Still Matters, but Reporting Has Changed
- OpenAI Has Machine Identity Now. Which Jobs Should Lose API Keys?
- Your AI Gateway Can Name the User. Decide What That Log Is For
Need help with this kind of work?
Plan a safe NGINX evaluation Get in touch with Greg.
