Ens on lo0 — Tech Blog

deepagents on a cluster of your own: the SDK is free, the server is not, and what you have to build in between

Tue, 15 Sep 2026 07:00:00 +0200

Opening of the agentic platform vertical. The previous articles dealt with the pieces separately: the inference gateway, its second door, what a fleet of agents costs and isolation. This one deals with what goes on top. Verified against deepagents 0.7.14 and the LangGraph repository, commits of 14 September 2026.

TL;DR

deepagents is not a runtime. It is a factory that assembles middleware and delegates to LangChain’s agent factory. It returns a compiled LangGraph graph and nothing else. The repository’s own documentation says so without decoration: it introduces no new runtime. That is good news for whoever deploys it, because it runs wherever Python runs.

The planning tool no longer exists. It disappeared in 0.7.0 as a breaking change, along with the state channel that backed it. Almost everything written about this harness still describes it as one of its three legs. Today you have to ask for it explicitly, and you have to ask for it in each subagent too.

With the default configuration, the agent’s files live inside the checkpoint. The state backend stores the full content, binaries in base64, in the same place the conversation is persisted. Changing that is one line and it is the first architecture decision of the deployment.

The database grows per loop step, not per turn. Four tables, one row per superstep, one per channel and version, another per task write. And of the four cleanup operations the base class declares, the Postgres implementation has only one: delete an entire thread. The other three raise not-implemented.

Pruning by hand can empty the history silently. The code itself warns that a partial delete breaks the delta chain and leaves the channels rebuilding empty without raising any error. The only safe pruning is by whole thread.

Tenant isolation is the thread identifier, and there is no owner check. Whoever can send a thread identifier reads that thread. The on-disk filesystem backend fixes its root when the agent is built, so it separates nobody. And the documentation’s example for computing the per-user namespace does not work outside the managed platform.

There is a configuration trap that leaves a short-window model uncompacted. If the model does not expose its window, the compaction threshold falls back to 170,000 tokens. Served on a vLLM with a 32,768 window, the agent blows up on context length long before it compacts. The failure is silent and is fixed by passing the profile by hand.

Observability without the platform does exist, and it goes through a package that is not obvious. LangChain’s core does not emit OpenTelemetry: zero references. The exporter lives inside the LangSmith SDK, and there is a mode that emits over OTLP only, without talking to the service. It is the road to a Langfuse of your own, and it is worth knowing where it passes.

And here is where the free part ends: the server. The SDK, the graph engine and the checkpointers are MIT. The server that publishes them over HTTP carries an Elastic 2.0 licence, asks for a commercial licence key for production, adds Redis to the stack and reports metadata to an external endpoint unless there is an isolation agreement. The development tool is explicitly for development.

What is left is a list of things you have to write. Per-thread authorisation, retention, a run queue, cancellation, clean draining and migrations. None of them is hard. All of them are work, and none of them appears in the twenty-line front-page example.

You are here: the harness arrives after the model

The sequence repeats on every project. First you set up inference, which is the visible part. Then the gateway, because you need keys and budgets. Then observability, because nobody knows what is going on. And when all of that works, somebody asks why the assistant cannot do multi-step tasks, and the word agent enters the scene.

At that point the temptation is to write the loop by hand, and for two weeks it looks like a good idea. The loop is easy. What is not easy is everything you discover afterwards: what happens when the context fills up, where the intermediate files are stored, how you resume a task that was left half done, how you ask a human for confirmation without losing state.

An agent harness is exactly that: the packaged answer to those questions. And choosing one looks like a library decision, about the size of choosing an HTTP client. It is not. It decides where your users’ state lives, which database grows, what can be isolated and what cannot, and in the case at hand, whether there is a commercial licence waiting at the end of the road.

This article looks at deepagents with those eyes. It is not a usage guide, and I do not assess whether its agents are any good. I look at what it forces you to build.

The analogy: the scaffolding and the crane

A building site needs scaffolding and it needs a crane, and they are not the same thing even though both are metal structures surrounding the building.

You put up the scaffolding yourself with parts you bought. It adapts to the façade, it can be extended, and the day the work finishes you take it down and put it away. Nobody charges you for using it once it is bought.

The crane is another matter. You hire it, it comes with an operator, it has a serial number and you have to notify somebody when it goes up. Without a crane the work still moves forward, more slowly and with more people, but it moves forward.

Here the scaffolding is the SDK and the graph engine, and it belongs to whoever buys it. The crane is the server that exposes the agent over HTTP, and that one comes with a contract. This article is about where exactly the line between the two sits, because you cannot see it in the brochure, and about how much work can be done without a crane.

What deepagents actually is

The first thing to get out of your head is that it is a system. It is a function.

The main factory assembles a list of middleware and calls LangChain’s agent factory, which is what builds the graph. What it returns is a compiled graph, with an added configuration on top that raises the recursion limit to a very high number and adds an integration tag in the metadata. The repository’s own architecture document states it: no new runtime is introduced.

Compiled with the default options, the graph has the nodes you would expect from a reasoning-and-action loop: start, a prior node that repairs incomplete tool calls, the model node, the tools node and the end. The conditional edges run from the model to tools, to the model itself or to the end. There is nothing more. Everything that looks like a system is middleware that adds nodes only when it declares hooks of its own.

The tools that ship by default are the filesystem ones, plus the subagent delegation one: list, read, write, edit, delete, search by pattern, search by content, execute, and the task tool.

The good consequence of this is portability. If something is a LangGraph graph and nothing else, it runs in any Python container, with the checkpointer you choose, against the model you choose. There is no hidden service behind it.

What is no longer there

It deserves its own section because it contradicts almost everything published. The planning tool, the one that wrote a task list and kept it in a state channel, was removed in 0.7.0 as a breaking change declared in the changelog. The tool is gone, the channel is gone, and the prompt fragment that went with it is gone.

It survives as LangChain middleware, and you have to ask for it by hand. With one detail that bites: you have to ask for it in each subagent too, because each subagent assembles its own stack. All that remains from the previous stage are archaeological leftovers, such as the state key that is still on the list of keys excluded when passing context to a subagent.

The plan, today, rests on files. Which is consistent with the rest of the design, and is another reason to look closely at where those files live.

Where state lives

This is the first architecture decision and the one that is most expensive to get wrong.

The agent’s state has two large channels. Messages, with a reducer of its own that deduplicates by identifier and treats deletions as tombstones. And files, with its own reducer where a null value means deleted. Both use a channel type that writes deltas and stores a full snapshot every fifty updates, and the code comment explains why: to take checkpoint growth from quadratic to linear with respect to the number of messages.

That channel type is marked beta in its own code, with a warning that the on-disk representation may change. Worth knowing before you rest a platform on top of it.

The backends

There is a common interface and several implementations. The ones that matter for deciding:

Backend	Where the files live	Persistence
State	Inside the graph state, that is, inside the checkpoint	Per thread, in the checkpointer’s database
Filesystem	In a real directory anchored to a root	Wherever you mount the volume
Store	In LangGraph’s store, with a namespace	Crosses threads, with a time to live
Composite	Routed by path prefix among the above	Mixed

The default backend is the state one. That is: by default, everything the agent writes ends up inside the checkpoint, and binaries go base64-encoded inside the same JSON. For a demo it is convenient, because you have nothing to set up. For a platform with real users it is a sizing decision taken by omission.

There is a detail that rounds the matter off. The filesystem middleware automatically evicts large tool results to a file when they exceed a token threshold, so that they do not occupy the context window. It is a good mechanism. But with the state backend, evicting to a file means moving the content from one place in the checkpoint to another place in the same checkpoint. It leaves the model’s window and it does not leave the database.

What grows in the database

The Postgres checkpointer creates four tables: one for migrations, one for checkpoints, one for blobs by channel and version, and one for writes by task. The primary keys all start with the thread identifier, and there is an index per table on that column.

What you have to internalise is the rhythm. One checkpoint row is written per engine superstep, not per conversation turn. A turn with four tool calls is several supersteps. None of that is recycled on its own.

And here comes the uncomfortable part. The checkpointer’s base class declares four maintenance operations: delete a thread, delete by run, copy a thread and prune with a strategy. In the Postgres implementation only the first is implemented. The other three inherit the not-implemented exception from the base class. Deleting a thread is three delete statements by identifier, and that is it.

In other words: retention is yours to build. And with a care that the code itself documents and that is worth quoting in full, because it is the kind of warning you read after the incident. A naive pruning that removes intermediate checkpoints and their writes can cut the delta chain; the surviving checkpoint is rarely a snapshot point, so its channels would rebuild empty without any error being raised.

Translated into operations: the periodic sweep deletes whole threads and only whole threads. Never loose rows. And since the checkpoints table has no date column, to know which thread is old you have to keep count outside or rely on the checkpoint identifier being a time-sortable UUID.

There is a variant of the checkpointer that stores only the last state and retains no history, which caps growth at the root. With one important reservation to verify before using it: it is not clear that it is compatible with the delta channels this harness uses by default for messages and files. Combining the two without checking is asking for a silent problem.

The store, which does have cleanup

Curiously, the sibling piece is better resolved. The store has a configurable time to live, with refresh on read, skipping of expired entries and a sweep interval, and the sweep is a delete by expiry date.

Two warnings. The sweeper is a thread inside the process, so with several replicas there are several sweepers competing for the same delete; it is idempotent, but it is free contention and you avoid it by switching it off and putting the delete in a scheduled cluster job. And the store’s semantic search requires the vector extension in the database, which constrains the managed Postgres image, which normally does not carry it.

The isolation that does not exist

If the platform is going to have more than one tenant, this is the section that decides the deployment topology.

The only thing separating one thread from another is the thread identifier. It is the first column of the primary key in all three tables. There is no owner check anywhere in the checkpointer. Whoever manages to send a thread identifier in the call configuration reads that thread. Authorisation is the responsibility of the layer you write on top, and since that layer also has to be written, it is worth noting down now.

By backend, the situation differs:

The state one inherits thread isolation, which is enough if the HTTP layer validates that the user owns the thread.
The store one computes the namespace per call, through a function that receives the runtime context. It is the correct option for multi-tenant.
The filesystem one fixes its root in the constructor, when the agent is built. There is no path in the code that recomputes it per request, per thread or per tenant. Sharing one deployment between tenants with this backend means everybody sees the same directory.

On that last point, do not confuse it with the protection that does exist. Virtual mode, which now comes enabled by default, blocks paths that escape the root. That protects against directory traversal. It does not protect against the neighbour. The project’s own threat document admits it: that mode exists to support the composite backend’s prefix routing, not as a security boundary.

There is also a documentation trap worth flagging because it costs an afternoon. The example the documentation proposes for computing the per-user namespace reads the identity from a server-information field of the runtime context. That field is annotated in the LangGraph code as metadata injected by the managed server, and null when running open-source LangGraph without managed deployments. On a cluster of your own with an HTTP layer of your own, that example fails. What you have to use is the context you fill in yourself, with the identifier that comes validated from the identity provider.

And one more boundary that gets crossed without warning: the memory and skills middleware interpolate file content into the system prompt as is, without sanitising. If two tenants share a directory that serves as the source for that, the first writes instructions that the second’s agent executes. It is prompt injection through shared storage, and it is avoided with the same measure as everything above: do not share the filesystem backend between tenants.

The topology conclusion is short. Real multi-tenant with files means one deployment per tenant, with its namespace, its volume and its quota, or else the store backend with a namespace computed per request. There is no third way.

The model, and the trap you need to know about

The default model is a specific commercial provider, and it is marked deprecated: passing an empty model warns and will stop working. You can inject any LangChain chat model, which is what anyone serving their own weights will do.

With two integration details that are not obvious.

The first. To point at an OpenAI-compatible endpoint, which is how a vLLM behind a gateway looks, you have to pass the already-built instance, not the string with the provider prefix. With the string, a provider profile is applied that forces the use of the responses API, which a vLLM normally does not implement. Passing the built object applies no profile and the agent stays clean.

The second is the trap, and in my view it is the most likely configuration failure in the whole deployment.

The compaction middleware computes its thresholds from the model profile. If the model declares its input window, it compacts on reaching 85 % of the window and keeps 10 %. If it does not declare it, it falls back to a fixed value: 170,000 tokens.

The chain that leads to not declaring it is the usual one in a deployment of your own. The OpenAI client resolves the profile by looking the model name up in a static table of the provider’s models. A model served as qwen3-30b-a3b is not in that table, so the profile comes out empty, and empty becomes null. The method that assigns it swallows any exception, so there is no warning.

Result: a vLLM with a 32,768-token window will not compact until 170,000. The server will return a context-length error long before that, and it will do so intermittently, only when conversations get long. There is a safety net that catches the error and trims, but that is reactive recovery after a failed call, not planning.

The fix is one line, because the profile is a public field and only fills itself in when it is empty: you pass it when building the model, with a value below the real window to leave room for generation. And it deserves an assert at start-up, because it is the kind of thing nobody looks at until it fails.

A related sizing note. With the default thresholds and a 32,768 window, compaction would trigger at 27,852 tokens, while eviction of large tool results is fixed at 20,000. That is, a single tool result can occupy almost the whole budget before anything evicts it. With 128,000 windows the defaults are proportionate; below 64,000 you have to lower those two thresholds by hand.

The tools, and the MCP that is not where it seems

This harness has its filesystem tools and its delegation tool, and the rest are passed as an ordinary list of LangChain tools.

The fact that matters to anyone with an MCP gateway in place: the SDK does not integrate MCP. There is no reference to the protocol in the package, nor any dependency on adapters. The integration lives in the command-line tool that accompanies the project, which does depend on the MCP adapters for LangChain, resolves configurations in the style of the desktop clients, and turns each remote tool into a LangChain tool that then goes through the ordinary list.

So the path exists and is proven, but you have to walk it yourself: load the gateway’s tools with the adapters and pass them in the list. Which, incidentally, fits well with what we already know about the catalogue: the credential-based filtering the gateway does is applied in the listing, so each agent receives the subset that belongs to it without the harness having to know anything.

The subagents

They are declared in three ways and invoked with a task tool that takes a description and a type. What you need to know to design with them:

The subagent receives the parent’s state except the messages and a few private keys, and it starts with a single human message which is the task description. Files are inherited, and it shares the same backend object, so parent and child work on the same logical filesystem. The result comes back as a tool message with the structured response or the child’s last text.

Depth is effectively one level. Verified by compiling the graph: the stack assembled for a declarative subagent does not include the subagent middleware, so the child does not have the task tool and cannot delegate in turn.

And there is no concurrency limit of its own. The parallelism is that of the engine’s parallel tool calls, and the task tool’s prompt explicitly invites launching them in parallel. Anyone with a per-tenant GPU quota will want to put the brake where it belongs, because it is not here.

Code execution

The sandbox protocol is well defined and the packaged implementations are nearly all paid services: four commercial providers, plus an embedded JavaScript interpreter and a sandbox from the platform vendor itself.

That leaves a local shell backend that is worth looking at closely before considering it. It runs the command with the system shell, and its own docstring lists what it does not do: no isolation, no process separation, no resource limits, and it lists production and multi-tenant environments as inappropriate use cases. It also has an option to inherit the process environment which, enabled, hands the model every variable, including the gateway credentials and the database connection string. It comes disabled, and it is an easy foot to shoot.

The reasonable way out on a cluster of your own is to implement the protocol yourself, and it is smaller than it looks. The sandbox base class requires four things: an identifier, execute, upload files and download files. Everything else, list, read, write, edit, delete and search, is built by the base class on top of execute. Looking at one of the commercial implementations, it is on the order of a hundred and fifty lines.

One image requirement that constrains the Dockerfile and is worth knowing beforehand: the base class helpers inject small encoded Python scripts to resolve searches and checks, so the sandbox image needs Python and a POSIX shell or half the calls fail.

On how to implement it, the shape that fits a Kubernetes of your own is an ephemeral container per session with a bounded time to live, resource limits, no service account token mounted and a network policy that only allows egress towards the inference gateway. Execute is resolved against the cluster’s exec API, and upload and download through the same channel. The alternative with less code is an isolated runtime class for the agent pod, one pod per tenant, and the shell backend inside; you lose multi-tenancy in a single pod and you have nothing to write.

Observability, and the package it goes through

Here there is a fact that surprises and that is worth being clear about before designing the trace pipeline.

LangChain’s core does not emit OpenTelemetry. Zero references in the whole package. Its native tracer talks to the vendor’s observability service and that is that.

The OTLP exporter does exist, but it lives inside that service’s SDK. And there is the good news: that SDK has a tracing mode that emits only over OTLP, without talking to the service, reading the destination and headers from OpenTelemetry’s standard environment variables. The transport is HTTP with protobuf, which is exactly what a self-hosted Langfuse accepts on its ingestion route.

That is: to take the agent’s traces to your own observability you have to install the vendor’s package and ask it not to talk to the vendor. It works, it is supported and it is documented, but it is a dependency you have to declare in the supply chain analysis, not a configuration detail. And if the OpenTelemetry packages are missing, it emits a warning and silently stops tracing, so start-up should check for it.

There is the alternative of the callback handler that Langfuse itself publishes, with fewer pieces. The practical difference is correlation: over the OTLP route the agent’s spans share a trace identifier with the gateway’s and the inference engine’s, and you see a whole request end to end. Over the callback route, you do not. For anyone who already has a collector deployed, the OTLP route is the one that pays.

The server: here is where the free part ends

Everything above is an architecture decision. This is a licence decision, and it is the one that gives the article its title.

The harness SDK is MIT. The graph engine is MIT. The memory, SQLite and Postgres checkpointers are MIT. All of that runs anywhere, with no key, no registration and without calling anybody.

The server that exposes a graph over HTTP is another matter. The package that implements it carries an Elastic 2.0 licence, whose relevant clauses forbid offering the software to third parties as a managed service and forbid modifying or circumventing the licence key functionality. The command-line tool’s own command prints the conditions: for local development it asks for a service API key, and for production use it asks for a licence key in an environment variable.

There is also usage reporting. The server code contains a beacon endpoint to which it sends metadata, with a header carrying the licence key. The self-hosting documentation confirms it from the other side, listing among the requirements network egress to that domain for licence verification and usage reporting if not running in isolated mode. Isolated mode is a contractual variant, not a box you tick.

And it drags infrastructure along: besides Postgres, it asks for Redis.

The development tool, which is the one that appears in every tutorial, describes itself as development mode with hot reload and an in-memory server. It is not a production server and it does not claim to be.

None of this is a reproach. It is a legitimate and fairly common business model: permissive core, commercial control plane. What is not legitimate is finding out late. Anyone building a platform with a sovereignty requirement, with no dependencies on external services and with the argument that the whole stack is open, has to know that the piece that turns the graph into a service does not meet that requirement.

What you have to build

The way out is to write the HTTP layer yourself, and the good news is that it is boring. A service that compiles the graph once with the checkpointer pointing at the database, and exposes an endpoint that validates the identity provider’s token, derives the thread identifier and the tenant context, and invokes the graph. Event streaming if needed.

What you additionally have to write, and which the commercial server gave you ready-made:

Per-thread authorisation. The engine does not have it. It is the most important and the easiest to forget, because nothing fails if it is missing.
Retention and deletion. A scheduled job that deletes whole threads, never loose rows, for the reasons in the state section.
Migrations. Schema setup has to be called explicitly and needs data-definition permissions, so it goes in a separate job with a different role from the runtime one. And since it creates indexes concurrently, it cannot go through a connection pooler in transaction mode; point it at the direct write service.
Health probes and draining. The engine has a cooperative draining mechanism, but wiring it to the container’s termination signal is your own work.
Run queue and cancellation, if you need long background runs. This is where the absence is most felt, and the reasonable answer is a queue on the same database rather than another system.
Durability decided deliberately. There are three modes: persist before the next step, persist in parallel, or persist only on exit. The last one is no good on Kubernetes: if the pod dies, the whole turn is lost.

On that last point it is worth being explicit, because it affects tool design. The engine stores each task’s writes as soon as it finishes, and on resume it reapplies those that were already there and does not repeat them. A tool that finished is not run again. A tool that was in flight when the pod died is, because its write never landed. The semantics are at-least-once, so every tool with an external effect has to be idempotent or carry an idempotency key. There is no exactly-once.

And the same applies to interrupts for human confirmation: on resume, the node is re-executed in full, so any side effect that sat before the interrupt inside the same node is repeated. The rule is that the interrupt goes first.

How it fits with activity logging

Two things about this setup touch compliance head on, and both come out of earlier sections.

The first is that the checkpoint is, de facto, a repository of personal data. It contains the whole conversation and, with the default backend, the files the agent has written. If the platform serves identifiable people, that database needs encryption, retention of its own and separate access control, exactly like the gateway’s spend table. The difference is that here there is no redaction switch that helps: the state is the state.

The second is traceability. An agent that delegates to subagents and executes tools produces a chain of actions that you have to be able to reconstruct, and the only place where that chain is complete is the trace. Traces going out over OTLP to your own observability stops being a technical preference and becomes the logging mechanism. It is worth designing it that way from the start, and not adding it afterwards.

As always in this series, the annex’s specific codes have to be checked against the current text before taking them into a compliance document; the approach is developed in the technical controls article.

Checklist

Decide the filesystem backend before the first demo, because the default one puts the content in the database.
Pass the model profile by hand with the real window, and check it at start-up.
Lower the eviction thresholds if the model’s window is below 64,000 tokens.
Build the model as an instance, never as a string with a provider prefix, if there is an OpenAI-compatible endpoint behind it.
Write per-thread authorisation before opening the service to more than one user.
One deployment per tenant if you use the filesystem backend; a namespace computed per request if you use the store one.
Compute that namespace from your own context, not from the server-information field, which is null outside the managed platform.
A scheduled retention job that deletes whole threads and only whole threads.
Schema migrations in a separate job, with a role of their own and against the direct write service.
Synchronous durability, and tools with external effects made idempotent.
Traces over OTLP with the mode that does not talk to the vendor’s service, and a start-up check that the packages are there.
Put a concurrency limit on subagents if there is a GPU quota involved.
If you need code execution, implement the sandbox protocol against an ephemeral container; the local shell backend is advised against by its own documentation.
Note in the supply chain analysis the hard dependencies on commercial providers that the package drags in even when unused.

Traps and things that are not what they look like

The planning tool was removed in 0.7.0. You have to add it by hand, and in each subagent too.
The default backend stores files inside the checkpoint, binaries included in base64.
Evicting a large result to a file does not get it out of the database with that backend, only out of the context window.
One checkpoint is written per superstep, not per turn.
Of the four declared cleanup operations, only delete-a-thread exists in Postgres.
A partial pruning can empty the history without raising any error.
The delta channel is in beta and its on-disk representation may change.
There is no owner check in the checkpointer. The thread identifier is not a credential.
The filesystem backend’s root is fixed when the agent is built and it separates no tenants.
The documentation’s example for the per-user namespace does not work outside the managed platform.
The filesystem middleware and the subagent middleware cannot be removed.
If the model does not declare its window, compaction does not trigger until 170,000 tokens, silently.
Passing the model as a string with a provider prefix forces an API that a vLLM does not implement.
The SDK does not integrate MCP; the integration lives in the command-line tool.
Subagents do not delegate: depth is one level.
LangChain’s core does not emit OpenTelemetry; the exporter lives in the vendor’s service SDK.
The HTTP server carries an Elastic 2.0 licence, asks for a licence key for production and reports usage unless there is an isolation agreement.
The development tool is for development, with an in-memory server.
Resumption is at-least-once for in-flight tools.

Closing

The question this article started with was whether deepagents fits into a platform of your own. The answer is that it does, and that it fits better than I expected, precisely because it is less than it appears. A middleware stack on top of a graph is easy to host, easy to understand and easy to replace. What does not fit is the piece next to it.

That asymmetry is the pattern I have been seeing all year across the ecosystem, and it deserves naming. The core is published under a permissive licence because the core is where you compete for adoption. The control plane is published under a restrictive licence because the control plane is where you charge. It happened with the gateways, it is happening with observability, and it happens here. Anyone building a sovereign platform cannot assess a whole project by the licence of its main repository: you have to look package by package, and look at which of them is the one you are going to need the day the thing has users.

The good part is that the bill, in this case, is paid in work and not in money. What you have to build to do without the commercial server is an HTTP service with no mystery to it, a retention job, a migration job and an authorisation layer. None of that is research. All of it is a week of an engineer who knows what they are doing, and in exchange you are left with a system that deploys the same way in a school as in a classified datacenter, with no internet egress and with nobody counting runs on the other side.

What I do recommend is making that list before the first demo and not after. Because the front-page example works in twenty lines, and the twenty lines have the default backend, the model without a profile and no authorisation at all.

Sources

langchain-ai/deepagents, código y documento de arquitectura: https://github.com/langchain-ai/deepagents.
langchain-ai/deepagents, registro de cambios de la rama del SDK (eliminación de la herramienta de planificación en la 0.7.0): https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/CHANGELOG.md.
langchain-ai/langgraph, motor, canales y checkpointers: https://github.com/langchain-ai/langgraph.
langgraph-checkpoint-postgres, esquema de tablas y operaciones de mantenimiento: https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint-postgres.
langgraph-checkpoint, clase base del checkpointer y aviso sobre poda con canales de deltas: https://github.com/langchain-ai/langgraph/tree/main/libs/checkpoint.
LangChain, despliegue de servidor autónomo (requisitos de licencia, Postgres, Redis y salida de red): https://docs.langchain.com/langsmith/deploy-standalone-server.
LangChain, trazado con OpenTelemetry: https://docs.langchain.com/langsmith/trace-with-opentelemetry.
Elastic License 2.0: https://www.elastic.co/licensing/elastic-license.
Langfuse, integración nativa OpenTelemetry (ruta de ingesta y autenticación): https://langfuse.com/integrations/native/opentelemetry.
Langfuse, integración con LangChain por retrollamadas: https://langfuse.com/integrations/frameworks/langchain.
langchain-ai/helm, chart del servidor: https://github.com/langchain-ai/helm.
Boletín Oficial del Estado, Real Decreto 311/2022, Esquema Nacional de Seguridad: https://www.boe.es/buscar/act.php?id=BOE-A-2022-7191.

Making the model prefer our tools: the priority that exists in no layer, the two primitives that do, and the `_meta` that crosses the gateway

Tue, 15 Sep 2026 03:30:00 +0200

A follow-up to LiteLLM’s MCP gateway, which treated the tool catalogue as cost and as surface. This one treats the next question, the one that arrives in the meeting afterwards: so then, how do I get the model to use mine. Verified against LiteLLM 1.102.0 and MCP specification 2026-07-28, with a test of our own run on 14 September 2026.

TL;DR

Tool priority does not exist as a concept in any layer of the stack. Not in the specification, not in the clients, not in the providers’ APIs. What exist are two distinct primitives: removing the alternative from the catalogue, and leaving it behind a search step. Everything else is persuasion, and the model ignores it when it suits.

The specification has no ranking field. The Tool object is name, title, icons, description, schemas, five annotations that are unreliable hints by their own declaration, and _meta. There is a trap I see repeated: MCP does define a numeric priority, but in another structure, the one that applies to content blocks, resources and prompts. It does not govern tool selection.

The only filtering the specification blesses is by credential. The current revision says the set of tools must not vary by connection, and that it may vary according to the authorisation presented. That is exactly what a gateway with per-key lists does.

The client is the one that decides, and only one of them has anything resembling priority. Claude Code lets you exempt a server from deferral with alwaysLoad, so that its tools load in full at start-up while the rest require a prior search. It is not called priority and it works as such.

We proved that the per-tool mark crosses the gateway. We set up an MCP server with one marked tool, served it through LiteLLM 1.102.0 and captured the wire: the _meta arrives whole and with the correct key. The chain is clean on purpose, with a comment in the code that says so.

And it is lost on exactly three routes, which are the gateway’s three catalogue-trimming modes. Proxy mode, tool search driven by key permissions, and the REST listing. In other words: the per-tool mark and LiteLLM’s catalogue trimming are incompatible. You have to choose one.

There is a library trap that makes the field disappear silently. The SDK’s Tool model declares the alias without allowing population by field name, so building it with the field name puts the dictionary in the extras and serialises it under the wrong key. There is no error. The field simply does not arrive.

The cheap lever is the description, not the name. Swapping descriptions shifts the selection distribution substantially; changing only the name has minimal and inconsistent effects. And the gateway’s overrides really do replace what is sent to the client.

Reordering the catalogue is a weak lever. The model is already attending to the correct tool eighty per cent of the time when it fails. Interventions on prompt order repair at most 23 % of the failures.

And the asymmetry you build is attack surface. Whoever controls the order controls the selection: with injection rates of 1.2 % you can take over the head of a tool ranking between 91 % and 97 % of the time.

You are here: the question that arrives after the third server

The previous article closed with a decision ladder for the catalogue: trim, rewrite, split by route, and use progressive disclosure when the catalogue grows. That ladder answers how much catalogue to show.

The question that arrives afterwards is a different one, and it is more uncomfortable. A real agent has native tools from the client hosting it, it has the in-house gateway with the house servers, and it has two or three third-party servers that somebody connected. All of them compete. And what you want is not to show less catalogue: you want that, faced with a query three tools could serve, yours wins. The audited one, the one with access control in place, the one that leaves a trace.

The answer everybody gives is to write a rule in the agent’s instruction file politely asking it to prefer the in-house server. There is even a rule published in a template marketplace that does exactly that. It is text in the prompt and the model follows it when it feels like it.

This article is what lies underneath.

The analogy: the counter with two trays

Let us go back to the switchboard operator from the previous article, the one who also hands out keys. Now the building has three key providers: the house cabinet, the maintenance contractor’s, and the cleaning service’s. All three have a key to the store room and all three open it.

The head of security wants the house one used, because it is the one with a log. And he discovers he can do three things, not one more.

He can take the other two off the counter. It always works and it annoys whoever needed them.

He can leave his own in the front tray and the other two in a drawer, so that to take one you have to ask. It works almost always and annoys nobody.

And he can change the label on his key so that it describes better when it is the right one. It works sometimes, it is the cheapest, and it is the only one that also protects against the contractor changing his label without warning.

What he cannot do is put a number from one to ten on each key and trust the operator to respect it. That number does not exist. The rest of the article is why it does not exist and what to do instead.

What the specification says: nothing

The current revision is 2026-07-28. Read against the source schema, the Tool object has name, title, icons, description, input schema, output schema, annotations and _meta. There is no field for priority, weight, rank, cost, group or tag.

The annotations are exactly five: title, and the read-only, destructive, idempotent and open-world hints. The schema itself warns that all of them are hints and that a client should not make tool-use decisions based on them when they come from untrusted servers.

The `priority` that exists and is no use

Here is the mistake I see repeated most. MCP does define a priority field, numeric between zero and one. It is in the annotations interface that applies to content blocks, to resources and to prompts, alongside the audience and the last-modified date.

It is not in Tool. It has no relation whatsoever to which tool the model picks. Anyone who finds it by searching the word in the schema and concludes that tool priority is standardised has the wrong structure.

The only precedence the specification defines for a tool is one of presentation: to display the name, first the title, then the annotations title, then the name.

The only blessed filtering is by credential

There is a new sentence in the current revision that is genuinely useful and that goes unnoticed. The set of tools must not vary by connection nor as a side effect of other requests, and it may vary according to the authorisation presented in the request.

Translated: segmenting the catalogue by key, by team or by token is the legitimate way to do it. Segmenting it by session state stopped being legitimate when the July revision removed protocol sessions.

Discovery does not discover tools

server/discover, which the current revision adds and which servers have to implement, does not return tools. It returns supported versions, capabilities, server instructions, identity and the cache freshness fields. It accepts neither filters nor a cursor.

Listing is still asking for everything and paginating. The listing request accepts only a cursor: there is no query, no filter, no limit, no groups, no tags.

And on collisions between servers, the specification explicitly and reasonedly washes its hands: clients or proxies that aggregate tools from several servers will encounter collisions and should implement a disambiguation strategy, for example prefixing. And it adds that the server name is not guaranteed to be unique and should not be used to disambiguate. There is no precedence rule between servers. There is not going to be one soon.

What there is in proposals

Nothing accepted. The official proposals index only lists those in a final state, and none of them deals with priority, groups or search. In draft there is one asking for a free-text query in the listing and a filtering capability; another on groups and tags that ended up superseded; and one carrying the word priority but which is per-tool model routing, which is another thing.

The interest group exploring the grouping of primitives declares in its own minutes that it is not going to pick a canonical pattern soon, and the documents in its repository are empty. The year’s roadmap does not mention the problem.

The layer that decides: the client

If the specification gives you nothing, what is left is whatever each client has built on its own. And here there is a clear winner.

Claude Code

Tool search is on by default, and what it does is defer: MCP tools are not loaded in full at start-up, the model sees just enough and discovers them when it searches. It requires a model that supports tool reference blocks, that is Claude Sonnet 4.5, Haiku 4.5, Opus 4.5 and later.

On top of that, the lever:

{
 "mcpServers": {
 "gateway-casa": {
 "type": "http",
 "url": "https://litellm.interna.svc/mcp",
 "alwaysLoad": true
 }
 }
}

The documentation describes it bluntly: if a server’s tools must always be visible without a search step, you set alwaysLoad to true and all of that server’s tools are loaded into context at the start of the session, regardless of the global search setting. And it recommends using it for a small number of tools that the model needs on every turn, because each tool loaded up front consumes context.

That is visibility asymmetry, and it works as priority even if it is not called that. Ours in front, the rest behind one step.

There is an operational consequence that the documentation mentions and that matters more in a gateway than in an ordinary server: setting alwaysLoad makes start-up wait for that server to return its tools, capped by the standard five-second connection timeout. A gateway that aggregates eight upstream servers and does not cache the listing, as is the case, lists live against all eight every time. If one of them is slow, the session’s start-up feels it.

There is also the fine-grained variant. An MCP server can mark individual tools as always loaded by including "anthropic/alwaysLoad": true in the tool’s _meta object, with the same effect for that tool alone. That would let you load three tools from our gateway up front and leave the other forty from the same gateway deferred. It is the lever that matters, and it is the one that motivated the test in the next section.

The rest of this client’s arsenal is pure exclusion, and it is worth knowing one detail that decides whether it works or not. A deny rule with the bare tool name removes it from the model’s context; with parentheses, it does not. The documentation puts it in a table: plain WebFetch removes the tool and the model cannot search at all, whereas WebFetch(domain:*) keeps the tool and rejects every request. The difference is not cosmetic: in the second case the model still sees the tool, still tries it and still spends the context its definition occupies.

The --tools flag is the scalpel: it accepts the empty string to disable all the built-ins, and it does not affect MCP tools. That is, --tools "" leaves the model with only what the gateway serves. It is a command-line flag and has no equivalent as a settings-file key; the functional equivalent there is deny rules.

The other clients

Client	Disable the native ones	Filter the MCP ones	Priority
Claude Code	`--tools ""`, deny by bare name	deny by pattern, subagents	`alwaysLoad`
Codex CLI	`features.shell_tool` to false	`enabled_tools` and `disabled_tools` per server	No
Gemini CLI	`tools.core` as an allowlist	`includeTools` and `excludeTools` per server	No
Copilot in VS Code	Not documented	picker and tool sets	No
Cursor	No	per-server switches	No

Two notes. Copilot cuts off at 128 tools per request and its virtualisation threshold does not go above that; its embedding-based routing is internal and has no configuration surface. And Cursor’s rules are purely indicative: they are text prepended to the context.

The API layer

If the client is in-house, the margin is wider, though narrower than it looks.

Forcing a set is not possible. In Anthropic’s case, tool choice accepts auto, any, a specific one by name, or none, and the documentation says explicitly that pointing at a set of MCP tools or at a member is not supported. In vLLM it is the same: a specific one, all of them or none. There is no way to say “any of mine from the gateway”. The proposal that would introduce grammars restricting tool names to the request’s set has been open for months and is not merged.

Filtering the catalogue is possible, in all three of the big ones. In Anthropic, with an MCP tool-set block where the default configuration disables and specific ones are enabled. In OpenAI, with the allowed tools list inside the MCP block itself, which the documentation justifies on latency and cost grounds, avoiding the model seeing unnecessary definitions. And in Gemini, the remote MCP server configuration accepts restricting which of the server’s tools the agent may call.

It is worth not confusing two things that are named almost identically in OpenAI: the allowed tools list inside the MCP block filters the catalogue, and that is what matters here; the identically named tool-choice type is another thing, it is a selection restriction, and there is evidence that it does not combine well with hosted tools, without the current documentation recording it. If anyone depends on that, let them test it against their model: it fails as a request error, so it shows up on a cold start.

And there is a 2026 lever that almost nobody is using. Anthropic has in beta a mechanism for mid-conversation tool changes, with add and remove blocks that accept referencing an entire MCP set. The reason it exists is in its documentation: the tools array sits even earlier in the chunked prefix than the system field, so editing it invalidates the cache for the whole conversation; by declaring the full set at the start and using the blocks, the array never changes and the cached prefix stays intact.

Applied to our case: you can remove a rival server’s set hot, mid-session, without paying for the whole prefix. It is not available on every model.

The test: the `_meta` crosses the gateway

The fine-grained variant of Claude Code’s lever depends on a question no documentation answers: whether a gateway that aggregates upstream servers propagates each tool’s _meta all the way to the client, or loses it along the way.

We checked.

The setup

A minimal MCP server with the Python SDK, serving two tools over HTTP, one of them with the mark in place:

types.Tool(
 **{
 "name": "always_loaded_tool",
 "description": "tool with _meta",
 "inputSchema": {"type": "object", "properties": {}},
 "_meta": {"anthropic/alwaysLoad": True, "probe": "UPSTREAM_META_MARKER"},
 }
)

In front of it, a LiteLLM from the main branch with that server declared in config.yaml, with no database, with a master key. And an MCP client querying the listing against /mcp.

The result

This is what comes out on the wire:

{
 "_meta": {"litellm.ai/server_outcomes": {"probe": {"status": "ok", "tool_count": 2}}},
 "tools": [
 {
 "name": "probe-always_loaded_tool",
 "description": "tool with _meta",
 "inputSchema": {"type": "object", "properties": {}},
 "_meta": {"anthropic/alwaysLoad": true, "probe": "UPSTREAM_META_MARKER"}
 }
 ]
}

The mark arrives whole and with the correct key. The client parses it without trouble.

Tracing the code, the chain is clean on purpose. LiteLLM keeps the SDK objects as they are when it lists against the upstream, instead of rebuilding them. The name prefixing does a deep copy and mutates only the name, with a comment in the code declaring the intention to preserve every field including the _meta by avoiding mutation. The two permission filters are list comprehensions that reuse the same objects. And the name and description overrides mutate in place, so they do not lose anything either. Somebody thought about this.

One operational detail: the name arrives prefixed with the server alias, governed by the configurable separator and the short prefix mode.

The three routes where it is lost

And here is the finding that changes the previous article’s recommendation.

Proxy mode returns only its three fixed tools, with no _meta and with no upstream tool at all. Verified against the wire as well.

Tool search activated by key permissions does the same with four virtual tools.

And the REST listing builds its response object by hand and discards the field: the tool that did carry a mark comes out with the field null. The class inherits from the type that has the field; it simply is not filled in. The fix fits on one line.

Those three routes are, exactly, the three ways LiteLLM has of trimming the catalogue. The operational conclusion is uncomfortable and it is worth saying plainly: either you use the gateway’s catalogue trimming, or you use the client’s per-tool mark. They cannot be combined. The previous article recommended proxy mode as the fifth rung of the ladder; with this in hand, that rung and the fine-grained mark are mutually exclusive.

The library trap

This deserves its own section because it takes out anyone writing a server or a proxy, and it gives no warning.

The SDK’s tool model declares the field with an alias, and does not enable populating it by name. The consequences, both checked by running them:

Building with the field name populates nothing. The dictionary slips into the model’s extras and comes out serialised under the wrong key, without the leading underscore, which is a key no client interprets.

And dumping and revalidating without asking for aliases loses the field, for the same reason.

There is no exception, no warning in the log, nothing. The field disappears. If someone marks their tools and does not see them marked in the client, this is the first place to look, before the gateway.

What we have not tested

For honesty’s sake, and because it is the link that remains: we have shown that the mark survives the gateway. We have not shown that the client acts on it when the tool arrives with the name prefixed by the gateway. Claude Code’s documentation describes the per-tool mark in a single sentence and says nothing about aggregating servers or about prefixes.

It is a half-hour test for anyone who has the setup in front of them: two tools from the same gateway, one marked, and look at which one appears loaded at the start of the turn. If someone does it before I do, I am interested in the result.

What LiteLLM can and cannot do

With the above, the gateway’s inventory of levers comes out like this.

Lever	Serves external MCP clients	Preserves the `_meta`
`allowed_tools` and `disallowed_tools` per server	Yes	Yes
Name and description overrides	Yes	Yes
Tool sets per route	Yes	Yes
Proxy mode and virtual tools	Yes	No
Search by key permissions	Yes	No
REST listing	Yes	No
Semantic filter	No	Not applicable

Two clarifications on the previous article’s table, now that the code has been read again.

The allowed and disallowed lists are applied in the listing, not only on the call. They are the blunt, effective instrument, and they do not break the cache because they are static.

And the overrides have a limit that was not accounted for: they are applied in the MCP protocol listing, but they are skipped in proxy mode and not applied on the REST route. Anyone rewriting descriptions and also turning on proxy mode is not serving what they think.

What the gateway cannot do is inject _meta. There is no setting equivalent to the ones for name and description. The mark has to be put there by the origin server, which for in-house servers is trivial because we write them. To mark third-party tools you would have to patch, and it is small: one field in the type and three lines in the overrides function if configuring it by file is enough.

There is also an ordering lever that did not appear in the previous article. In the proxy’s search mode there is a core tools setting that puts them at the front of the ranking and that also does not count against the results cap. It is the closest thing to a declarative priority in the whole stack, and it lives inside the one mode that discards the _meta.

And a nuance about proxy mode’s results cap. The client cannot ask for more than five, that is true, but the operator can raise it by configuration. The previous article implied it was immovable.

The cheap lever: the description, not the name

If you cannot exclude, what is left is to bias. And bias comes in through the description.

The work that measures selection bias between functionally equivalent tools puts the combined bias of the evaluated models between 0.25 and 0.38, that is, you would have to redistribute between 25 % and 38 % of the probability mass for equivalent tools to be picked equally. On that basis, swapping two tools’ descriptions shifts selection substantially, whereas perturbations that touch only the name produce smaller and more inconsistent effects.

Another piece of work measures that a single pass of automatic description rewriting improves the metric over a large corpus, almost as much as iterative refinement, and with two orders of magnitude less time. And it adds a warning worth retaining: descriptions tuned against a fixed set of candidates do not generalise to the dynamically retrieved set. You have to optimise for the regime you serve in.

Applied: the gateway’s description override is at once token trimming, selection bias and mitigation of description change after approval. It is the lever with the best effort-to-effect ratio in the whole article, and it is static, so it does not touch the prompt cache.

Name prefixing, by contrast, costs tokens and probably does not change which tool the model goes to.

What does not work

Reordering the catalogue. A June paper measures that, when the model fails, it was already attending to the correct tool eighty per cent of the time, well above chance. The bottleneck is not at the input but in the late layers. Interventions on prompt order recover at most 23 % of the failures, against the 59 % to 91 % of those acting on the final readout. Reordering is cheap and that is why it gets recommended a lot; it is also weak.

Rules and instructions. They are text. They help and they do not decide.

Your own per-request top-K filters. This is covered in the previous article and it still holds: four out of five measured strategies perform worse than not filtering, and on top of that rewriting the tool block on every turn invalidates the entire cached prefix.

The ladder, updated

Exclude in the client. It is the only deterministic thing. --tools "" or deny by bare name for the competing native tools.
Mark your own as always loaded. At server level with alwaysLoad, or per tool with the mark in the _meta if you control the origin server. Counting on start-up waiting for the server.
Trim with static lists per server and per key, and split a catalogue by agent profile across routes.
Rewrite the descriptions with the gateway’s overrides.
Remove hot the rival sets, if the client is in-house and the model supports it.
Choose: the gateway’s catalogue trimming, or the per-tool mark. Not both.
Do not: reorder, rename, or trust prompt rules.

The risk that has to be declared

The asymmetry you build is also a surface. Whoever controls which tools head a ranking controls the selection, and that can be attacked: there is work measuring that by injecting adversarial tools at rates of 1.2 % you take over the head of the ranking between 91 % and 97 % of the time.

In a system under ENS (Esquema Nacional de Seguridad, Spain’s national security framework) this fits under change management, not access control: the set of tools a model sees and the order in which it sees them are security configuration, and today nobody versions them. Neither does the specification fix a hash of the description or of the schema, nor does the gateway. The specific Annex II codes are worth checking against the current text before taking them into a compliance document; the approach is developed in the MCP gateway article.

There is a precedent within the ecosystem itself that points the way. The MCP skills extension, which is in a final state, requires a manifest with a per-file hash, mandatory verification before use, and approval tied to the set of files and their digests, so that any change revokes the approval. And it obliges hosts to prevent two skills with the same name from silently replacing one another. It is exactly the pattern missing for tools. Anyone who needs it today has to implement it in their gateway.

Checklist

Decide the strategy before touching anything: catalogue trimming in the gateway, or the per-tool mark in the client. They are mutually exclusive.
If you pick the mark, put it in the origin server, because the gateway cannot inject it.
Build the tool object with the alias key, never with the field name, or the field disappears without warning.
Do not revalidate tool objects from a dump without asking for aliases.
Count on marking a server as always loaded making session start-up wait for that server, and on a gateway listing live against all of its upstreams.
Exclude in the client the native tools that compete, by bare name and not with a pattern in parentheses.
Rewrite the descriptions of your own tools, and do not waste time renaming.
Do not turn on proxy mode if you depend on the description overrides, because they are not applied there.
Version the exposed tool set and its order as security configuration, with a hash of the description and the schema.
If you use the gateway’s REST route for anything, know that it discards the _meta.

Traps and things that are not what they look like

MCP’s priority exists, and it is not about tools. It lives in the annotations for content, resources and prompts.
Tool annotations are hints and the schema itself says they are not reliable from untrusted servers.
The specification gives no precedence rule between servers, and it says besides that the server name is no use for disambiguating.
The tool set may indeed vary by authorisation, and that is the only blessed segmentation.
server/discover does not return tools.
A deny rule with parentheses does not remove the tool from the context, it only rejects the calls.
--tools is a command-line flag, with no equivalent in the settings file.
Marking a server as always loaded delays start-up by up to five seconds per server.
Tool(meta=...) does not populate the field and serialises it under the wrong key.
Proxy mode, search by permissions and the REST listing discard the _meta.
Description overrides are skipped in proxy mode and are not applied on REST.
Proxy mode’s cap of five results can be raised by the operator, even though the client cannot ask for more.
The core tools of the proxy’s ranking are the only declarative priority in the stack, and they live in the mode that loses the _meta.
You cannot force “any of mine from the gateway” in any API.
In OpenAI, the allowed list inside the MCP block and the identically named tool-choice type are different things.
Gemini does accept a per-tool allowlist on its remote MCP servers.
Reordering the catalogue repairs at most 23 % of the failures.

Closing

The starting question had a trap in it, and the trap is the word. When someone asks how you prioritise an MCP server, they are assuming a dial exists somewhere. It does not, and I have spent the whole article showing the places where it is not.

What there is instead is poorer and more manageable: you remove what competes, you leave your own in front, and you write the description better. Three things, none of them elegant, all three effective in that order.

What does seem to me worth taking away is the shape of the problem. The tool catalogue a model sees is security configuration in the full sense, because it determines what the agent can do and which system it is going to talk to. And today it is managed like a list of connections: things get added, it is not versioned, it is not signed, and nobody detects a change. The ecosystem has already solved that problem once, for skills, with hashes and tied approval. For tools, not yet.

In the meantime, the asymmetry has to be built by hand, server by server, and knowing that it rests on the _meta of an object that a library can empty without saying anything.

Sources

Model Context Protocol, herramientas en la revisión 2026-07-28: https://modelcontextprotocol.io/specification/2026-07-28/server/tools.
Model Context Protocol, server/discover: https://modelcontextprotocol.io/specification/2026-07-28/server/discover.
Model Context Protocol, paginación: https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/pagination.
Model Context Protocol, caché de listados: https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/caching.
Model Context Protocol, esquema fuente de la revisión: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2026-07-28/schema.ts.
Model Context Protocol, extensión de habilidades: https://modelcontextprotocol.io/extensions/skills/overview.
Model Context Protocol, grupo de interés sobre agrupación de primitivas: https://modelcontextprotocol.io/community/interest-groups/primitive-grouping.
Anthropic, Claude Code y MCP (alwaysLoad, búsqueda de herramientas): https://code.claude.com/docs/en/mcp.
Anthropic, Claude Code, referencia de línea de comandos (--tools): https://code.claude.com/docs/en/cli-reference.
Anthropic, Claude Code, permisos (denegación por nombre pelado): https://code.claude.com/docs/en/permissions.
Anthropic, conector MCP y conjuntos de herramientas: https://platform.claude.com/docs/en/agents-and-tools/mcp-connector.
Anthropic, cambios de herramientas a mitad de conversación: https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages.
Anthropic, búsqueda de herramientas: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool.
OpenAI, MCP y conectores (lista de herramientas permitidas): https://developers.openai.com/api/docs/guides/tools-connectors-mcp.
OpenAI, búsqueda de herramientas y caché: https://developers.openai.com/api/docs/guides/tools-tool-search.
Google, llamada a funciones en la Interactions API: https://ai.google.dev/gemini-api/docs/function-calling.
vLLM, llamada a herramientas y decodificación restringida: https://docs.vllm.ai/en/latest/features/tool_calling.html.
vLLM, propuesta de decodificación guiada por regiones y gramáticas de herramienta: https://github.com/vllm-project/vllm/issues/39848.
LiteLLM, código del gateway MCP: litellm/proxy/_experimental/mcp_server/server.py, mcp_server_manager.py, rest_endpoints.py, tool_search.py, litellm/experimental_mcp_client/tools.py: https://github.com/BerriAI/litellm.
SDK de Python de MCP, modelo Tool y serialización por alias: https://github.com/modelcontextprotocol/python-sdk.
BiasBusters, sesgo de selección entre herramientas equivalentes y peso de la descripción frente al nombre: https://arxiv.org/html/2510.00307v2.
Looking Is Not Picking, atención frente a lectura final y techo de las intervenciones sobre el prompt: https://arxiv.org/html/2606.16364v1.
A Single Rewrite Suffices, reescritura de descripciones y generalización al conjunto recuperado: https://arxiv.org/html/2606.30775.
ToolFlood, saturación adversaria de la capa de recuperación: https://arxiv.org/html/2603.13950.

Completing Keycloak for MCP: the protected resource no SDK hands you ready-made, and the enterprise extension that skips the whole flow

Sat, 12 Sep 2026 09:00:00 +0200

A follow-up to Keycloak in an AI platform, which flagged the gap: resource indicators are not supported and protected resource metadata belongs to the MCP server. This post tries to close it. Verified against revision 2026-07-28 of the specification, the official Python and TypeScript SDKs, Keycloak 26.7.3 and LiteLLM 1.102.0.

TL;DR

The specification splits three obligations and the authorisation server covers only one. The MCP server must publish its protected resource metadata. The client must send the resource indicator in both requests, and must do so even if the authorisation server does not support it. The MCP server must validate that the token was issued for it. Keycloak does not understand the indicator and considers the metadata someone else’s, so all three end up in the resource layer.

The Python SDK mounts the metadata on its own, but degraded. As soon as the resource server URL is configured, the route appears. What that automatic route publishes carries a single authorisation server, reuses as its scope catalogue the ones the middleware requires, and leaves the name and the documentation null. To publish a complete document you have to mount the route by hand.

Audience validation comes switched off in Python and does not exist in TypeScript. In Python, if the resource URL is configured and the corresponding flag is not enabled, the SDK emits a deprecation warning and behaves as if it were disabled; the docstring itself promises that version 3 will set it to true. In TypeScript the bearer verification does three things, and none of them is looking at the audience. Neither of the two ships a signature verifier with public keys.

Token passthrough is forbidden in writing, and the substitute has a name. The specification says the MCP server must not accept or relay tokens that were not issued for it, and that if it calls upstream APIs the token must be a different one. The mechanism is token exchange, which Keycloak supports in its standard version with a limitation you need to know: the audience is a client identifier, not a resource URL.

There is an official extension that changes the whole picture, and it is stable. Enterprise-managed authorisation replaces the redirect to the MCP authorisation server with an exchange at the corporate identity provider, which evaluates the policy and issues a grant based on an identity assertion. It has been stable since June 2026 and there are servers in production.

Keycloak implements it halfway and in experimental. It only knows how to act as receiver, not as issuer, behind a feature flag, and against draft 01 when the working group is on 04. The official documentation literally says not to use it in production.

LiteLLM already implements it on the client side and does not document it. In 1.102.0 there is an authentication mode towards MCP servers that runs the two stages of that grant. There is not a single documentation file that mentions it.

You are here: the resource side

The previous post walked through the identity provider. This one walks through what sits on the other side of the token, which is where the MCP specification puts almost all its normative obligations.

The natural reading order is When MCP grows up for the basic setup, Keycloak in an AI platform for the identity piece, and this one for the missing layer. The MCP gateway seen from the inside is in its own post.

The analogy: the visa and the border checkpoint

A consulate issues visas. A border post checks them. They are two different offices, and the classic mistake consists of assuming that because the visa is genuine it is good for entering through any door.

The visa has written on it which country it is good for. That is the token’s audience, and here the problem appears: the consulate we work with does not know how to write the destination the traveller asks for, because it does not understand that field on the form. It knows how to write a destination if asked for it under a different name, by way of a pre-agreed stamp, which is the workaround of scopes and the audience mapper.

And then there is the other half, the one almost nobody builds. The border post has to exist, it has to announce where it is and from which consulates it accepts visas, and it has to read the destination written on the visa before letting anyone through. If the border post limits itself to checking that the stamp is genuine and does not look at the destination, any valid visa from the same consulate is good for entering. That is exactly what the two official SDKs do by default.

Part 1. The split of obligations

From revision 2026-07-28, with the normative words as they are:

Obligation	Whose	Status with Keycloak
Publish protected resource metadata (RFC 9728)	MCP server, MUST	Out of its scope, by design
Send the resource indicator (RFC 8707) in authorisation and in token	Client, MUST, even if the authorisation server does not support it	It does not understand it
Validate that the token was issued for oneself	MCP server, MUST	The resource’s responsibility
Not accept or relay other tokens	MCP server, MUST NOT	The resource’s responsibility
Validate the issuer of the authorisation response (RFC 9207)	Client, MUST; authorisation server SHOULD emit it	Supported
Consent for each dynamically registered client	MCP proxy with a static identifier, MUST	Configurable

The most confusing part of that split is the second line. The specification obliges the client to send the parameter regardless of whether the authorisation server supports it. With Keycloak, that parameter is lost: the official documentation says it cannot recognise it, and the standard behaviour towards an unknown parameter is to ignore it. The client complies, the token comes out, and what does not come out is the correct audience. The failure appears later and somewhere else, which is the worst kind of failure.

It is worth knowing where that work stands. The matter is issue 14355 of the project, open, with a milestone in 26.8.0. There was a complete implementation in pull request 35711, with a mapper of its own and an extension point for resolving resources, which went back to draft in October 2025 because of a total lack of tests and because it was decided to redo it in phases, starting with a single resource per client. In March 2026 a new issue was opened for experimental support, also with a milestone in 26.8.0 and with no associated pull request. In 26.7.x there is no feature flag that enables it.

What is new in the revision and affects the setup

Four things changed with respect to the previous revision and are worth collecting:

RFC 9207. A new section on validating the authorisation response. The client must record the issuer from the validated metadata document, and the comparison is literal: you are not allowed to normalise case, elide the default port, add or remove the trailing slash or re-encode characters before comparing.
Offline tokens leave the catalogue. A new section on refresh tokens: MCP servers should not include the corresponding scope either in the challenge header or in the supported scopes of their metadata.
Dynamic registration becomes deprecated. It goes from optional to optional and deprecated, retained for compatibility with authorisation servers that do not support client identifier metadata documents. And a new requirement is added to registration: the application type is mandatory, and a client must not reuse credentials from another authorisation server, it has to register again.
Step-up elevation is rewritten. The menu of three server strategies disappears and is replaced by two rules: the challenge’s scope attribute describes what is needed for the requested resource, with no obligation to include what has already been granted, and scope accumulation becomes the client’s responsibility. With a new requirement for the server: it must take scope hierarchies into account, where a broad one implies the narrow ones.

Part 2. What the SDKs give, and what they do not

Here is the uncomfortable part, and it is the main reason for writing this post. Verified by reading the code of the Python SDK and of the TypeScript 2.0.0-alpha one.

Protected resource metadata

In Python the complete model exists and it mounts on its own. The metadata class carries the RFC fields: resource, authorisation servers with a minimum of one, key set URL, supported scopes, bearer methods with a default value of header, name, documentation, policy, terms, and the client certificate and DPoP fields. The handler serves the document with a one-hour cache directive, and the URL is built by inserting the well-known path in front of the resource path, as the RFC requires.

As soon as the resource server URL is configured, the route appears with no further work. But what that automatic route publishes is degraded in three points: it passes a single authorisation server, it takes as its scope catalogue the ones the middleware requires (which are not the same as the ones the resource supports), and it passes neither the name nor the documentation, which come out null. To publish a complete document you have to call the route creation function by hand.

In TypeScript it exists and does not mount on its own. The function that builds the document emits only five fields: resource, authorisation servers, supported scopes, name and documentation. It does not emit the supported bearer methods, nor the key set URL, nor anything about DPoP. And serving it is explicit: either you call the response function from your own handler, or you mount the metadata router. There is no point in the SDK that does it on its own.

Audience validation

This is the one to fix on day one.

In Python it comes disabled. The token verifier is a single-method protocol, that is to say a hole the implementer fills. The access token’s resource field is the indicator you set yourself. And the comparison only happens if you ask for it: there is a function that normalises as a URL and ignores the trailing slash, but the resource server URL reaches it empty unless the validation flag is enabled.

The detail to read twice is in the configuration: if the resource URL is set and the flag is not, the SDK raises a deprecation warning and behaves as if the flag were false. The docstring says version 3 will set the default to true. Until then, a Python server configured with authorisation accepts tokens issued for another resource, unless the implementer enables the flag or validates the audience inside their own verifier.

In TypeScript it is not validated at all. Bearer token verification does exactly three things: strip the prefix, check the required scopes, and require that the expiry is present and not past. A search for audience or key set across the server and middleware packages returns no validation. It is all left in the hands of whichever verifier you plug in.

Neither of the two ships a signature verifier with public keys. In Python the only example is introspection against the authorisation server, and its audience check sits behind a flag that also comes out false. In TypeScript the interface is empty. That is: the component that validates the token, which is the one holding up the most important normative requirement of the specification, is your own code in both cases.

The authentication challenge

Python builds the challenge with the error and its description, and adds the metadata URL only if it is configured. It returns 401 with invalid token and 403 with insufficient scope, both from the same function, so both carry the metadata URL. What it never emits is the scope parameter, which revision 2026-07-28 asks to be included, and which is exactly what the client needs in order to know what to ask for.

TypeScript does emit the scope when there are required scopes, in addition to the metadata URL, and it correctly maps invalid token to 401 and insufficient scope to 403.

That is, each SDK gets a different half right. The Python one validates better and warns worse; the TypeScript one warns better and does not validate.

Scopes, which are not per tool

In both SDKs scopes are a static list at the transport mounting level, not per tool. There is no per-tool scope declaration and no step-up elevation help on the server side. Emitting a 403 with the specific scope that call requires, which is what the specification describes, is your own code.

That is the origin of almost all the fine-grained authorisation you have to build, and it is why there is a Part 6.

Which revision each one announces

Python is already on 2026-07-28. The revision appears in the known versions and in the list of modern versions, described as the ones that use the stateless envelope per request. The server discovery method is registered with a default handler, and the method and name headers are validated against the body.

TypeScript has it, but in a separate list. The latest protocol version constant is still 2025-11-25, because that list is only the one for the initial handshake. The modern era lives in a separate module, with a comment explaining the reason: keeping them deliberately separate so that adding a revision there never leaks a modern version string into a 2025-era handshake.

And it is worth recalling the mismatch that already came up in the MCP gateway post: LiteLLM 1.102.0 still announces 2025-06-18.

Part 3. Building the protected resource

With the above, the list of what you have to write is short and concrete.

1. A token verifier that validates the signature and the audience. Against the realm’s key set, checking issuer, expiry and that the audience contains the MCP server’s canonical URL and only things that concern it. Here the side effect of the Keycloak workaround comes in: if a client asks for two scopes from two different resources, out comes a token with two audiences, because each mapper contributes its own to the array. There is no client policy condition or executor in 26.7 that limits the number of audiences per token. The practical defence is the resource’s: reject tokens whose audience includes other resources, instead of merely checking that its own is present.

2. The complete metadata document, with all the authorisation servers you accept, the real catalogue of scopes the resource understands, and the name and documentation filled in. In Python, mounting the route by hand instead of leaving the automatic one. In TypeScript, mounting it, full stop.

3. The authentication challenge with the scope. In Python you have to add it, because the SDK does not emit it. And you have to take scope hierarchies into account, which is a new requirement of the revision.

4. The decision between local validation and introspection. Validating the signature locally costs no network, but revocation does not take effect until the token expires: there are no revocation lists for signed tokens. Introspection costs a round trip per request and only confidential clients can invoke it. The reasonable combination is a short token life and introspection on the operations that change state.

5. Binding state to the user. The new revision is explicit about this, because with protocol sessions gone, state is carried in handlers that travel as an ordinary tool argument. Servers must verify every incoming request and must not treat possession of a handler as authentication; and they should bind the handler to the user on the server side, for example storing the state under a key that combines the user identifier derived from the verified token with the handler, and reject the handler if someone else presents it. It is a change in the way of working compared with the sessions of before.

Part 4. The hop from the gateway to the MCP server

The real shape in an inference platform is not client against MCP server: it is client against gateway, and gateway against MCP server. That second hop is where it is decided whether the architecture is correct.

The specification leaves no room. The MCP server must not accept or relay tokens that were not issued for it. And if it makes requests to upstream APIs, it may act as an OAuth client of theirs, but the token it uses there is a different token, issued by the upstream authorisation server, and it must not forward the one it received.

The standard mechanism for that is token exchange, and here you need to know three Keycloak details.

First, the permission model changed. The old version required fine-grained administration permissions and an explicit exchange authorisation on the target client. The standard version, supported since 26.2, does not require them: it is enough for the requesting client to be confidential and to have the corresponding switch enabled. In exchange there is a surprising condition: the subject token has to carry the requesting client in its audience, unless it exchanges its own token. That is, the gateway needs to appear in the audience of the user token, which is achieved with an audience mapper in a default scope of the gateway. Only then can it narrow the audience to that of the specific MCP server.

Second, the audience is a client identifier, not a resource URL. The parameter filters audiences, that is to say it narrows them, which is what you want. But it takes the identifier of a client registered in the realm. The practical consequence is that the MCP server has to be registered as a client, and its identifier should be its canonical URL, so that the resulting audience matches what the resource validates. It is a naming trick, and it has to be documented for whoever comes after. The documentation itself acknowledges it: token exchange does not yet support the resource parameter.

Third, the subject token type is limited. The standard version only accepts access tokens as subject.

There is also a new experimental feature in 26.7 that adds a parameterised scope type for validating whether the requesting user is authorised to act on behalf of another. Interesting for delegation, but experimental.

What the gateway does today

In LiteLLM 1.102.0 the authentication modes towards MCP servers number twelve, with a default value of none. The ones that matter for this discussion are four.

oauth2_token_exchange implements the standard exchange. It sends the correct grant type, the subject token and its type, and the audience, never the resource. The omission is deliberate according to the code itself: fabricating a target risks an invalid target error. It caches the resulting token under a key that combines the subject token with the whole configuration, and with a lifetime equal to the token’s minus one minute. And it blocks, never degrades: with no incoming token it returns 401, which the edge turns into a challenge with the resource metadata URL; a rejection from the identity provider returns 401; a gateway configuration error returns 500; a transport failure, 503.

true_passthrough and oauth_delegate forward the client’s authorisation header as is. That is token passthrough, by the name the specification gives it, and its legitimate use is narrow: when the token the client presents was already issued for the target MCP server and the gateway is a mere transport. Outside that case, it is non-compliant.

oauth2_id_jag is the surprise, and it deserves a part of its own.

Part 5. The enterprise extension, which changes the picture

In June 2026 the MCP project published an authorisation extension that solves a different problem from the one the standard flow solves, and which in an organisation with an identity provider of its own is the real problem.

The normal flow is per user: each employee authorises each client against each MCP server. It works for consumer applications and it does not work in a company, because onboarding a person requires authorising dozens of services one by one and offboarding requires revoking them one by one.

The io.modelcontextprotocol/enterprise-managed-authorization extension inverts that. It is in the stable specifications directory of the extensions repository, it comes from SEP-990, and the flow is this:

The MCP client authenticates the user against the corporate identity provider through the normal flow, and stores the identity assertion, which may be an OpenID identity token or a SAML assertion.
When the server indicates that enterprise-managed authorisation is needed, the client exchanges that assertion at the corporate provider for an authorisation grant based on an identity assertion. The provider evaluates the organisation’s policy there: group membership, roles, conditional access.
The client presents that grant to the MCP authorisation server and obtains an access token.
The sentence that defines the extension, verbatim: the user is not redirected to the authorisation endpoint of the MCP authorisation server.

The MCP authorisation server validates the signature against the corporate provider’s key set, plus audience, issuer and expiry, and uses the subject as the user’s stable identifier, with the email as a fallback for linking earlier accounts.

What that buys is exactly what a compliance file asks for: policy in a single place, an auditable decision at the identity provider, and centralised revocation that takes effect across all clients at once. The employee who loses access stops receiving grants, without touching any server.

The underlying standard is a draft from the IETF’s OAuth working group, under the name of JWT identity assertion authorisation grant, revision 04 of May 2026, signed by people from Okta, Ping Identity and an independent author. It profiles identity chaining across trust domains by combining token exchange with the JWT profile.

And here comes the problem

Keycloak implements it only halfway. It has its own documentation page, behind a feature flag. And three limitations you need in front of you before designing anything:

It only acts as receiver. It accepts assertions issued by an external provider and issues local tokens. Native support for acting as issuer, the documentation says, is not yet fully implemented. In the extension’s flow, the issuer is the corporate provider: if that provider is Keycloak, the missing piece is exactly the one you need.
It is based on draft 01 while the working group is on 04.
The official documentation says not to use it in production.

The asymmetry is striking and worth pointing out: Keycloak does not support a standard published eight years ago such as resource indicators, and does partially support a draft from a few months back.

What is already in the gateway, undocumented

In LiteLLM 1.102.0, the oauth2_id_jag mode runs the two stages of the flow. In the first it asks the corporate provider for a token exchange with the requested token type specific to this grant, sending the user’s identity token as subject and, optionally, audience, resource and scope. In the second it presents the resulting assertion to the resource’s authorisation server with the JWT bearer grant type. In both the gateway authenticates as a client with a JWT signed by private key.

Two operational warnings that come out of the code and are nowhere else:

The subject comes from the caller’s identity token, or from the one captured at login. And only the generic OIDC provider captures assertions: with Google, Microsoft or SAML there is none, and all users fail. The code raises a warning when loading the configuration.
A badly configured server refuses with a 500 instead of falling back to the static credential. It is the right decision, and it is worth knowing before it happens.

And the main warning: there is no documentation. Not a single file in the repository that mentions this mode. Anyone using it is reading code, like this post.

Part 6. Per-tool authorisation

None of the previous pieces answers the question the business ends up asking: whether this person may call this tool with these arguments. The identity provider gives roles and scopes, and with that you do not model a graph of relations, as was already argued in the previous post.

What is published today, with sources:

OpenFGA is the only one with a dedicated product guide, updated on 9 September 2026. The pattern is a tool type with an invocation relation, checked on each call, and a listing query so the client only sees the tools it may invoke. It is a pattern and a modelling language, not a reference implementation.
Pomerium ships a per-tool policy criterion, with exact, prefix, suffix and list matching.
Kong offers it as a product, with per-tool control lists.
Traefik Hub goes as far as parameter-level restrictions, which is the finest published grain.
Envoy has an MCP filter that extracts protocol attributes for fine-grained access control, declared to be in active development and with no OAuth of its own: the hook is external authorisation towards a policy engine.

The lowest-friction option in a platform that already has a service mesh is external authorisation against a policy engine. The most expressive one, the relations model.

Part 7. What still has no standard

Two gaps the specification does not cover and that have to be closed from outside.

Tool definition change. Neither revision 2026-07-28 nor the SDKs pin a hash of the description or of the input schema. The best practices page covers confused deputy, token passthrough, server-side request forgery in discovery, state handler hijacking, server confusion and validation of the authorisation URL scheme, but there is no integrity or pinning requirement. The tool that does it is the Invariant Labs scanner, under the Apache 2.0 licence, which pins hashes to detect definition change after approval and also ships a proxy mode with guardrails. It already came up in the MCP gateway post and it remains the only answer.

The public guidance that does get into this is the NSA’s on MCP security design considerations, from May 2026, done with Carnegie Mellon’s software engineering institute. Two of its observations are directly actionable: that authorisation in MCP is optional and that the specification imposes no requirement on token lifecycle management, so expiry and rotation are left in the organisation’s hands; and the warning against dynamic tool discovery with no origin verification and no authorisation checks, which is the most direct acknowledgement of the risk in a state guidance document.

Part 8. Who covers what

With all of the above, the decision table for the layer you put in front of the MCP server:

Piece	Publishes resource metadata	Validates audience	Token exchange	Per-tool authorisation
Python SDK, automatic route	Yes, degraded	Not by default	No	No
TypeScript SDK	Does not mount on its own	No	No	No
Traefik Hub (commercial)	Yes, automatic	Not documented	Not documented	Yes, down to parameter
Kong, OAuth plugin for MCP	Not documented	Yes	Not documented	Yes, per-tool lists
Pomerium	Partial	Not documented	Not documented	Yes, per-tool criterion
agentgateway (Solo.io)	Yes	Yes, by JWT policy	Yes, including the assertion grant	Yes, with expressions
mcp-context-forge (IBM)	Not in release notes	Not documented	Yes, since 1.0.6	Yes, per-role control
Envoy, MCP filter	No	No	No	Via external authorisation
LiteLLM 1.102.0	Yes, and authorisation server metadata too	Not on the incoming JWT	Yes, and the assertion grant	Yes, per-key and per-team permissions

Two warnings about that table. The Kong plugin requires a minimum version of 3.12, is in technical preview and needs a licence for its AI edition; it also introduces a breaking change in 3.13, which starts treating all traffic as MCP in order to close a possible authentication bypass. And on oauth2-proxy I found no primary documentation either for or against protected resource mode: I am not claiming it does not have it, I am claiming it is not documented where I could look.

Reference configuration

Keycloak: the per-resource scope, optional, with its audience. That it is optional and not default is the key piece, because it is what makes the client have to ask for it explicitly and makes it work as a substitute for the resource indicator:

kcadm.sh create client-scopes -r plataforma \
 -s name=mcp:inventario -s protocol=openid-connect \
 -s 'attributes."include.in.token.scope"=true'

kcadm.sh create "client-scopes/<id>/protocol-mappers/models" -r plataforma \
 -s name=aud-mcp-inventario \
 -s protocolMapper=oidc-audience-mapper \
 -s 'config."included.custom.audience"=https://mcp.ejemplo.es/inventario' \
 -s 'config."access.token.claim"=true'

And the MCP server registered as a client with its canonical URL as identifier, so that token exchange produces the right audience:

kcadm.sh create clients -r plataforma \
 -s clientId=https://mcp.ejemplo.es/inventario \
 -s enabled=true -s publicClient=false -s consentRequired=true

The gateway, with token exchange instead of token passthrough:

mcp_servers:
 inventario:
 url: "https://mcp.ejemplo.es/inventario"
 transport: "http"
 auth_type: "oauth2_token_exchange"
 client_id: "litellm-gateway"
 client_secret: os.environ/GW_SECRET
 token_exchange_endpoint: "https://sso.ejemplo.es/realms/plataforma/protocol/openid-connect/token"
 audience: "https://mcp.ejemplo.es/inventario"
 subject_token_type: "urn:ietf:params:oauth:token-type:access_token"
 token_exchange_profile: "rfc8693"

The resource verifier, which is what nobody hands you ready-made. The essential bit is the last check, the one that rejects other resources’ audiences instead of settling for finding its own:

RECURSO = "https://mcp.ejemplo.es/inventario"

async def verificar(token: str) -> AccessToken | None:
 claims = jwt.decode(
 token, await jwks(),
 algorithms=["RS256"],
 audience=RECURSO, # validates that I am there
 issuer=ISSUER,
 )
 aud = claims["aud"]
 aud = [aud] if isinstance(aud, str) else aud
 # and that nobody else is: the scopes workaround allows
 # tokens with two audiences, and that reopens the confused deputy
 if set(aud) - {RECURSO, CLIENTE_GATEWAY}:
 return None
 return AccessToken(
 token=token,
 client_id=claims["azp"],
 scopes=claims.get("scope", "").split(),
 expires_at=claims["exp"],
 resource=RECURSO,
 )

And when mounting the server, the flag that does not come set:

auth = AuthSettings(
 issuer_url=ISSUER,
 resource_server_url=RECURSO,
 validate_token_resource=True, # without this there is only a warning
 required_scopes=["mcp:inventario"],
)

Checklist

Enable audience validation in the Python SDK, or write it into the verifier if it is TypeScript. Without that, the central normative requirement is not met.
Reject tokens with other resources’ audiences, not just check that your own is present.
Mount the metadata document by hand, with all the authorisation servers and the real catalogue of scopes.
Add the scope parameter to the challenge, in Python, and account for scope hierarchies.
Register each MCP server as a Keycloak client with its canonical URL as identifier, so that token exchange produces the right audience.
Replace any token passthrough mode with token exchange, except the narrow case where the token was already issued for the target.
Check that the gateway appears in the audience of the user token, or the exchange will fail.
Bind state handlers to the user on the server side, and never treat them as authentication.
Decide between local validation and introspection knowing that the first delays revocation until expiry, and shorten the token life accordingly.
Pin a hash of the description and the input schema from outside, because the specification does not cover it.
Put a policy engine in for per-tool authorisation, and do not try to model it with roles.
If you are considering the enterprise extension, check first who issues the grant: Keycloak today only knows how to receive it, in experimental and against an earlier draft.

Traps and things that are not what they look like

The Python SDK mounts the metadata document on its own, and that is why it looks solved. What it publishes carries a single authorisation server and no name and no documentation.

The audience validation deprecation warning does not enable anything. It warns and carries on behaving as disabled.

The TypeScript SDK does not validate the audience at all. It is not configuration, it is that there is no code for it.

Python’s challenge does not carry the scope, so a client that receives a 403 does not know what to ask for.

The scopes workaround allows two audiences in the same token. Each mapper contributes its own, and there is no client policy that limits it. The defence is in the resource.

The token exchange audience is a client identifier, not a URL. If the MCP server is not registered with its URL as identifier, the resulting audience will not match what the resource validates.

Token exchange requires the gateway to be in the audience of the user token. It is the condition that wastes the most time the first time round.

Dynamic client registration is deprecated as of this revision, and the substitute, client identifier metadata documents, is experimental in Keycloak and has an open bug with documents carrying unknown fields, which blocks login with real clients.

LiteLLM’s identity assertion grant depends on the generic OIDC provider. With Google, Microsoft or SAML no assertion is captured and all users fail.

Step-up elevation is no longer the server’s responsibility. Scope accumulation moved to the client in this revision.

The authentication elevation signal goes in a 401, not a 403. Insufficient scope is 403; asking for a higher authentication level is a different thing and a different code.

Closing

The summary of this post fits in one sentence: the identity provider is the cheap half of the problem, and the expensive half is the protected resource, which no SDK hands you ready-made and which in the two official ones comes with audience validation disabled or absent.

From that comes an order of work. First the token verifier, with the audience validated in both directions, because without it everything else is decoration. Second, the complete metadata document, mounted by hand. Third, replacing any token passthrough with exchange, with the MCP server registered with its URL as identifier. Fourth, a policy engine for what roles do not model.

And a scheduling decision worth taking with the information in front of you. The enterprise-managed authorisation extension is the right route for an organisation with a provider of its own, it is stable and it has servers in production behind it. What is not ready is Keycloak as issuer. Anyone who wants that flow today has two honest options: delegate the mechanics to a gateway that implements it, or wait. Putting it into production with a feature the official documentation marks as experimental and expressly advises against is not one of them.

Sources

Especificación MCP, revisión 2026-07-28: autorización, registro de clientes y buenas prácticas de seguridad.
Extensión de autorización gestionada por la empresa y su especificación estable, del SEP-990. Anuncio de 18 de junio de 2026.
draft-ietf-oauth-identity-assertion-authz-grant, revisión 04 de 21 de mayo de 2026, grupo de trabajo OAuth del IETF.
Código de los SDK oficiales de MCP: python-sdk y typescript-sdk 2.0.0-alfa, clonados el 12 de septiembre de 2026.
Integración de Keycloak con Model Context Protocol, intercambio de tokens y concesión de autorización por aserción de identidad, consultados el 12 de septiembre de 2026.
Incidencias de Keycloak 14355, 47117 y 51039, y petición de cambios 35711.
Código de LiteLLM 1.102.0, commit 9071ca50 del 11 de septiembre de 2026.
NSA y SEI, Model Context Protocol: Security Design Considerations, mayo de 2026.
OpenFGA, autorización de servidores MCP, actualizado el 9 de septiembre de 2026.
mcp-scan de Invariant Labs, Apache 2.0.
Documentación de agentgateway, Traefik Hub, Kong y Pomerium, consultadas el 12 de septiembre de 2026.

Keycloak in an AI platform: where it fits, what it solves and the two standards MCP requires and it does not implement

Sat, 12 Sep 2026 07:30:00 +0200

This post opens the identity block of the operations track. The previous one covered the gateway side: the JWT that does not validate audience, the user who never reaches the trace. This one covers the piece on the other side. Verified against Keycloak 26.7.3, revision 2026-07-28 of the MCP specification and the text of Royal Decree 311/2022 in the BOE.

TL;DR

Keycloak 26.7.3 was released on 31 August 2026 and is still incubating at the CNCF, which it entered in April 2023. The cadence is four minor releases a year and support in practice covers a single branch: the twenty security bugs fixed in 26.7.3 were not backported to the 26.4, 26.5 or 26.6 branches at the time of release.

The Quarkus-based distribution separates build and runtime configuration. What is set in the build phase is frozen into the image, and changing it at startup forces a rebuild. In containers, the pattern is to build into the image and start with the optimised flag.

Storage is relational and only relational. The alternative engine that was in development was withdrawn in version 25.0. Since 26.0 sessions are persisted to the database by default, which changes the load profile: the dominant cost in the official benchmarks is database CPU.

Organisations solves multi-tenancy inside a realm, fully supported since 26.0. It groups members, associates email domains and links identity providers per organisation. It is the alternative to replicating realms per customer.

The measured bottleneck is password hashing. Since 25.0 the default algorithm outside FIPS environments is Argon2, with around 7 MB of memory per operation. The official sizing guide gives one vCPU for every 15 password logins per second, against 120 per second for client credentials and for refreshes.

Keycloak does not implement two standards the MCP specification marks as mandatory. Protected resource metadata belongs to the MCP server, not the authorisation server, so there is nothing to hold against it there. Resource indicators do belong to it and are not supported. Keycloak’s own documentation declares partial conformance with the last three MCP revisions for that reason. The practical substitute is scopes plus an audience mapper.

There is a recent critical bug worth looking at today. CVE-2026-18963, scored 9.1, allowed resetting any user’s password without authenticating, administrators included. Fixed in 26.7.2, released on 19 August 2026.

You are here: the cross-cutting layer

Identity is not a stage of the pipeline, it is a layer that crosses all of them. It shows up in stack hardening as one of the seven layers of defence, in the model’s chain of trust as workload identity, in the gateway as token validation, and in the post about authenticating MCP servers as authorisation server.

What was missing was the post about the piece itself, and above all the decision of where to put it and what to expect from it.

The analogy: the civil registry and building permits

A small town hall has a population register, which says who lives there, and it has permits, which say who can do what. They are two different things and it is worth not confusing them, because the register is good for the whole town while a permit is good for one specific job on one specific street.

Keycloak is the register. It knows who each person is, identifies them reliably, knows which groups they belong to and issues a credential document that expires. What it does not do is decide whether this person can modify this particular file: that is the permit, and it lives in each service.

Confusing the two produces the most expensive design mistake in platforms of this kind, which consists of putting into the token everything that will need to be decided later. The register document grows, gets handed out everywhere, and when a permission changes you have to wait for everyone’s document to expire.

There is a third element the analogy captures well. A credential document issued for presenting at the tax office should not be good for entering the municipal depot. That is the token’s audience, and it is the central subject of the second half of this post.

Part 1. What Keycloak is today

Project status

Item	Value
Latest stable version	26.7.3, released on 31 August 2026
Previous ones	26.7.2 (19 August), 26.7.0 (9 July), 26.6.0 (8 April)
Cadence	four minor releases a year
CNCF	incubating since 10 April 2023, not graduated
Support	the current branch; earlier ones do not receive fixes reliably

That last point deserves underlining because it conditions the upgrade policy. The analysis of 26.7.3 shows that its twenty security fixes were not backported to earlier branches at release time. Operating Keycloak means keeping up to date with the current branch, not staying on a “stable” version for a year.

Since 26.0 there is a backward compatibility guarantee across minor versions for features marked as fully supported, and breaking changes are opt-in.

The internal architecture in five pieces

Two startup modes. The development one enables HTTP, does not resolve the hostname strictly and disables the theme cache. The production one requires a hostname and TLS, or it will not start. Confusing them in production is the first antipattern on the final list.

The build phase. The build command materialises the optimisations into the image. Build options, such as the database engine, the enabled features or metrics, are frozen. Runtime ones, such as the database password or the hostname, are applied at startup. Changing a build option at startup forces a rebuild with the corresponding latency cost. The correct pattern in containers is to build into the image and start with the optimised flag.

Extensions via SPI. Authenticators, protocol mappers, user storage, event listeners, hashing algorithms and secret vaults. They are packaged as JARs and resolved in the build phase.

Infinispan cache. Embedded by default, with database-based discovery as the recommended mechanism. The discovery alternatives via Kubernetes DNS, TCP and UDP are deprecated. There are local caches, with default capacities of 10,000 entries in several of them, and replicated caches for sessions, client sessions, offline sessions, authentication sessions, login failures and action tokens. Remote mode, with an external Infinispan, is needed for first-generation multi-site deployment.

Relational storage. JPA over a database. The alternative engine was removed in version 25.0. The databases supported today include PostgreSQL from 14 to 18, MariaDB and MySQL in their extended support versions, SQL Server 2019 and 2022, Oracle 19c and 23.x, and the managed variants Aurora PostgreSQL and Azure SQL.

The minimum conceptual model

Before touching anything you need to be clear on eight concepts, and the order in which they relate:

Realm: the isolation boundary. Its own users, its own signing keys, its own policies. Two realms share nothing.
Client: an application that asks for tokens. Public if it cannot keep a secret, such as a browser application; confidential if it can, such as a service; and bearer-only if it merely validates tokens without requesting them.
Client scope: a reusable bundle of scopes and mappers, assigned to clients as default or as optional. It is the unit with which you bound what a token carries.
Protocol mapper: what projects an attribute, a role or an audience into the token. The audience mapper is the one that solves the central problem of this post.
Role, realm or client, and composite role, which aggregates others.
Group, hierarchical, with inherited roles and attributes.
Identity provider: federation towards another external OIDC or SAML. User federation: LDAP, Active Directory and Kerberos, with synchronisation and attribute mapping.
Authentication flow: a sequence of executions with required, alternative, conditional or disabled requirements, and subflows. It is where you build a second factor or a check of your own.

And one feature that changes architectures: organisations, fully supported since 26.0. It solves multi-tenancy inside a single realm, grouping members, associating email domains and linking identity providers per organisation, so that provider discovery is done by the user’s email domain. The classic alternative, one realm per customer, multiplies administration and shares no configuration.

Part 2. Who can authenticate against it

This is the table you need before drawing anything. The right-hand column is usually the one that decides.

Piece	Protocol	Cost
Kubernetes API	native OIDC, or the structured authentication configuration file	Free
LiteLLM	OIDC and JWT, plus UI SSO	JWT and SSO above five users: Enterprise
vLLM	static key only	No OIDC
Langfuse	generic OIDC and Keycloak provider	SSO free; per-project access control: Enterprise
Grafana	generic OAuth yes in the open edition	Team synchronisation: Enterprise
Backstage	generic OIDC and community-maintained Keycloak provider	Free
Open WebUI	OIDC, with role management by claim	Free
LibreChat	generic OIDC, with Keycloak documented	Free
Argo CD	native OIDC or Dex, with groups into its RBAC file	Free
MinIO	OIDC with role assumption via web identity	See the note below

Two clarifications that change decisions.

Kubernetes. The modern mechanism is structured authentication configuration, which allows several JWT issuers plus validations and mappings with CEL expressions. The corresponding proposal, KEP-3331, went alpha in 1.29, beta in 1.30 and is stable since 1.34. It is the route to use today, and it replaces the loose API server flags.

vLLM has no identity. All there is is a static key via environment variable. This is not a defect to fix, it is an architectural fact: the engine sits behind the gateway and its access control is network-based, not identity-based. Any design that exposes vLLM directly to users is giving up per-person traceability.

About MinIO a note of honesty is in order: the public documentation now redirects to the commercial edition, so the detail of how it maps policies from a claim is verified there and not in the open edition. Anyone depending on that mechanism should confirm it against their own version before designing on top of it.

Part 3. Humans and machines

They are two different problems and it is worth solving them separately.

People

Authorization code with PKCE, with the S256 method. The MCP specification requires it when the client is technically capable, and it goes further: it mandates rejecting the flow if the authorisation server metadata does not publish the supported challenge methods.

Workloads with no person behind them

Here the obvious option is client credentials with a Keycloak service account, authenticated with a secret or, better, with a JWT signed by private key.

But there is a less known and better option for workloads inside the cluster: federated client authentication, introduced in January 2026 under the banner of doing away with secrets. It lets a client authenticate with a token issued by an external provider, and one of those providers is Kubernetes. The announcement placed full support for the Kubernetes service account variant and for OIDC in version 26.6; the SPIFFE variant, by contrast, expressly says it will stay in preview until the SPIFFE client authentication standard is finalised at the IETF.

That means a pod can authenticate against Keycloak with the token the kubelet already projects into it, with no additional secret to rotate. It is worth confirming the exact status and the flag name against the release notes of whichever version you have deployed, because the feature is recent and has changed status between 26.5 and 26.6. It is preferable to token exchange, whose standard version is supported but is internal-to-internal only, while the old one, which covered external-to-internal and impersonation, is deprecated and in preview.

Keycloak against SPIFFE

The question always comes up and the answer is that they solve different things with a small overlap.

SPIRE attests the node and the process, and issues short-lived identity documents with no prior secret. Keycloak does not attest workloads: it trusts a credential someone had to place there, except in the federated authentication case just mentioned, where the one attesting is Kubernetes. In exchange, Keycloak federates people, issues tokens with business data and governs consent, things SPIFFE does not do.

The practical rule: SPIFFE for service-to-service identity inside the perimeter, Keycloak for anything that has a person behind it or crosses the perimeter. The SPIFFE detail is in the close of the chain of trust series.

Part 4. MCP, and the two missing standards

This part has the most consequences and is the worst documented outside the primary sources.

What the specification requires

From revision 2026-07-28, with the normative words as they appear:

The MCP server must implement RFC 9728 protected resource metadata, and the client must use it to discover the authorisation server.
The client must implement RFC 8707 resource indicators, including the resource parameter in both the authorisation request and the token request, and must send it regardless of whether the authorisation server supports it.
The MCP server must validate that the access token was issued specifically for it as the audience, and must not accept or relay any other token.
Authorisation servers and clients should support client identifier metadata documents. RFC 7591 dynamic registration becomes optional and is declared deprecated, retained for compatibility.

The revision also adds the issuer in the authorisation response, from RFC 9207, and a stateless model with state handlers where it is expressly stated that holding a state handler is not equivalent to being authenticated.

What Keycloak supports

From its own MCP integration guide:

Standard	Keycloak
OAuth 2.1 and authorisation server metadata	Supported
RFC 9207, issuer in the response	Supported
RFC 7591, dynamic registration	Supported
Client identifier metadata document	Supported, experimental, after enabling the feature
RFC 8707, resource indicators	Not supported
RFC 9728, protected resource metadata	Out of scope, it belongs to the MCP server

The conformance declared by the project itself is “partially supported, without resource indicators” for the last three MCP revisions.

Two practical conclusions:

The protected resource metadata document is published by the MCP server or a proxy in front of it, never by Keycloak. That is correct and there is nothing to fix, but you have to remember to implement it, because the client needs it to discover where to go.
Without resource indicators, the audience is bounded with scopes. The official route is to use the scope parameter instead of resource, and to hang from that client scope an audience mapper with the MCP server URL as the included custom audience.

It is a workaround, it works, and it has to be documented in the design because anyone coming after will look for the standard parameter and will not find it.

Part 5. The confused deputy

With the above on the table, the classic mistake becomes obvious on its own. A token with a generic audience turns any compromised service into a master key: whoever obtains the token a user presented to the dashboard can present it to the gateway, and from there to the MCP server.

The MCP specification is explicit in three sentences worth quoting verbatim in any architecture document:

MCP servers must not accept tokens that were not explicitly issued for them.
If the MCP server calls upstream APIs, it must not forward the token it received from the client.
MCP proxies that use static client identifiers must obtain user consent for each dynamically registered client before forwarding to third-party authorisation servers.

Translated into the specific figure this track has been dealing with: the gateway must not forward the user’s JWT to third-party MCP servers. It has to obtain a different token with the right audience, or act as an OAuth client in its own right. By default, as already documented in the MCP gateway post, the behaviour is to use the server’s own credential, which is the correct one; there are two modes that forward the caller’s token and both have a name in the specification.

Part 6. Two hours of task against five minutes of token

The specification pushes towards short-lived tokens and mandatory refresh token rotation in public clients. A two-hour agentic task comfortably exceeds the life of an access token and may also exceed session idle time if nobody refreshes.

Three real options, with their cost:

Offline tokens. They survive session expiry, and expire through their own idle timeout or through a maximum if that limit is enabled. The risk is obvious: a near-permanent credential, hard to inventory. And the MCP specification adds that MCP servers should not include that scope either in the authentication header or in the supported scopes of their metadata.

Automatic refresh in the client. It is the right answer when there is a client that can implement it, with refresh token rotation and secure storage. For an agent with no person behind it, it is better to renew via client credentials.

Long-lived virtual keys in the gateway. It works, and it is what most people end up doing. The price has to be written down in the risk analysis: identity ends up decoupled from the provider, so deactivating someone in Keycloak does not invalidate their key, and traceability back to the real person depends on the discipline with which the keys were created. The levers that compensate are expiry, automatic rotation and a mandatory alias, covered in the virtual keys post.

A note of honesty about the default values. The numbers going around (five minutes of access token, thirty of session idle time, ten hours of maximum) do not appear published in the administration guide and I did not locate them in the code. Treat them as a console observation and confirm them in your own realm before quoting them in a document.

Part 7. Sizing and operating

On Kubernetes

The operator exposes three custom resources: the server, the realm import and the OIDC client. Probes and metrics live on management port 9000, with the health and readiness paths, and metrics in Prometheus format provided the corresponding option was enabled in the build phase. That port is not exposed publicly.

For high availability there are three shapes. A single cluster spread across zones, with no additional infrastructure. First-generation multi-cluster, with an external load balancer and an external Infinispan at each site. And second-generation multi-cluster, introduced in 26.7.0 and still in preview, which connects clusters without external Infinispan, using the synchronously replicated database as the source of truth, with less cache and more database load.

The official sizing figures

From the CPU and memory sizing concepts guide, which is still published:

1 vCPU for every 15 password logins per second, tested up to 300 per second.
1 vCPU for every 120 client credential grants per second, tested up to 2,000.
1 vCPU for every 120 token refresh requests per second, tested up to 435.
Leave a 150 % CPU headroom for spikes, startup and failover.
1,250 MB of memory per pod with realm data and 10,000 cached sessions. Keycloak allocates 70 % of the limit to the heap and around 300 MB outside it, so the limit comes from subtracting those 300 MB from the expected usage and dividing by 0.7.

The stated assumptions behind those figures include Argon2 with five iterations, sessions in the database and the default cache of 10,000 entries.

The difference between 15 and 120 is the whole story of Keycloak’s performance: the cost is in password hashing. Since 25.0, the default algorithm outside FIPS environments is Argon2, with around 7 MB of memory per operation. Before it was PBKDF2, whose iterations were multiplied by ten in version 24. In FIPS mode PBKDF2 is still used.

From that comes an architectural consequence for an AI platform: machine workloads, which go through client credentials, cost eight times less than a human login. Sizing by number of services is cheap; sizing by morning login peaks is the expensive part.

The benchmark

From the 26.4 performance report, published on 1 October 2025: up to 2,000 logins per second and 10,000 refreshes per second with three pods, 74 vCPU in total and 8 GB per pod, over an Aurora PostgreSQL database, with almost linear vertical scaling.

Two useful findings from that report. With 20 ms of round-trip time between sites, the 99th percentile rises from 51 to 130 ms, and the project advises against deploying across different regions. And raising the cache from 10,000 to 200,000 entries brought the database CPU peak down from 77.77 % to 63.77 %, in exchange for somewhat longer garbage collection pauses.

Security

The urgent matter, if the deployment is below 26.7.2:

CVE-2026-18963, score 9.1, critical. A bypass of the email action token in the credential reset flow allowed resetting any user’s password with no prior authentication, administrators included. Fixed in 26.7.2, released on 19 August 2026. The temporary mitigation, if you cannot upgrade, is to disable password recovery in all realms. No known exploitation was recorded as of the end of August.

In 26.7.3 there are another nineteen, among them the missing hostname verification in the TLS certificate towards LDAP with a score of 8.8, two tenant restriction bypasses in token exchange with Microsoft and Google brokers, and two access control bypasses in organisations.

Official hardening comes down to four decisions:

Strict hostname, which is the default value since the second generation of that configuration. The server does not infer the URL from headers, which prevents poisoning email links and redirects.
Administration console on a different hostname, and network-restricted.
Proxy headers declared explicitly, trusting only a controlled reverse proxy.
Separate management port, not exposed.

Part 8. The mapping to the ENS

The codes and titles below are verified against the official text of Royal Decree 311/2022 published in the BOE, Annex II.

Code	Literal title	What a central IdP contributes
op.acc.1	Identificación	A unique identifier per entity, user or process that gains access
op.acc.2	Requisitos de acceso	Permissions are granted by role and group, not by loose credential
op.acc.3	Segregación de funciones y tareas	It supports it with roles, but the control is organisational
op.acc.4	Proceso de gestión de derechos de acceso	Least privilege and a specific remote access policy
op.acc.5	Mecanismo de autenticación (usuarios externos)	Flows and factors configurable per flow
op.acc.6	Mecanismo de autenticación (usuarios de la organización)	Reinforcements required already at the low level
op.exp.8	Registro de la actividad	It contributes part of the events, not all of them
op.exp.10	Protección de claves criptográficas	Management and rotation of the realm signing keys

Two nuances an auditor is going to look for.

The first, about op.acc.1: the text requires every entity that accesses the system, whether user or process, to have a unique identifier. That includes agents. A virtual key shared between several agents does not comply, and that is exactly what usually happens when JWT authentication falls outside the budget.

The second, about op.exp.8: the control requires recording the identifier of the user or entity associated with the event, the date and time, what information it is performed on, the type and the result. Keycloak contributes the authentication events. The usage events are contributed by the gateway and the MCP servers, and there the two already documented gaps reappear: adding and removing MCP servers generates no audit log and the trace user is set by the client.

The correspondence between control and product in this table is my own interpretation and must be validated by the certification body. The codes and titles are not: those are literal from the BOE.

Part 9. The configuration to leave written down

Three concrete pieces, so as not to stay at the level of concepts.

Hardened startup, as container arguments:

kc.sh start --optimized \
--hostname=https://sso.ejemplo.es \
--hostname-admin=https://sso-admin.interna.ejemplo.es \
--proxy-headers=xforwarded \
--health-enabled=true \
--metrics-enabled=true \
--http-management-port=9000 \
--cache=ispn --cache-stack=jdbc-ping \
--db=postgres

The metrics, health, cache and database options are build options: they go into the image, and passing them here forces a rebuild if they do not match.

The client scope with audience, which is the workaround forced by the lack of resource indicators. Created with the administration tool:

# one scope per protected resource
kcadm.sh create client-scopes -r plataforma \
 -s name=mcp-inventario -s protocol=openid-connect \
 -s 'attributes."include.in.token.scope"=true'

# the mapper that sets the token audience
kcadm.sh create "client-scopes/<id>/protocol-mappers/models" -r plataforma \
 -s name=aud-mcp-inventario \
 -s protocol=openid-connect \
 -s protocolMapper=oidc-audience-mapper \
 -s 'config."included.custom.audience"=https://mcp.ejemplo.es/inventario' \
 -s 'config."access.token.claim"=true'

The client asks for that scope and receives a token whose audience is only that MCP server. The MCP server validates the audience and rejects any other token, as the specification requires.

Realm import via GitOps, with the operator’s custom resource, so that the configuration does not live only in the console:

apiVersion: k8s.keycloak.org/v2beta1
kind: KeycloakRealmImport
metadata:
 name: plataforma
 namespace: identidad
spec:
 keycloakCRName: sso
 realm:
 realm: plataforma
 enabled: true
 # without this, the recovery email is attack surface
 resetPasswordAllowed: false
 bruteForceProtected: true
 sslRequired: all

Part 10. What Keycloak does not solve

Fine-grained authorisation over resources. The question “can this person see this particular trace” is a relation between objects, not a role. That problem is solved by Zanzibar-style engines, with OpenFGA and its object, relation and user tuples, or a policy language such as Cedar. Keycloak gives roles and scopes, and with those you do not model a graph of relations.

Machine secrets. Storage credentials, provider keys, database passwords. That is a secrets manager, covered in stack hardening.

Cryptographic workload identity with attestation. That is SPIFFE and SPIRE. In Keycloak it exists as an identity provider in preview, which is a different thing.

Authorisation inside the model. Which MCP tool an agent may invoke, and with what arguments. The specification offers scopes, the insufficient scope error and step-up elevation, but the per-tool and per-argument decision is taken by the MCP server or a policy engine, not by the identity provider.

Antipatterns

Forwarding the user’s token from the gateway to third-party MCP servers. Explicitly forbidden by the specification.
Static client identifier with dynamic registration and no per-client consent, which is the exact recipe for the confused deputy.
General scopes, of the full-access kind, and publishing the entire catalogue of supported scopes in the metadata.
Treating a state handler as authentication, which the new revision expressly forbids.
Following OAuth discovery towards any URL, which opens the door to requests towards internal addresses. It also applies to the authorisation server when it downloads a client metadata document.
Trust headers badly exposed in chat front ends. The Open WebUI documentation warns that an incorrect configuration allows authenticating as any user.
Starting in development mode in production, with the hostname not resolved strictly.
A single shared static key as the only control between the gateway and the engine.

Startup checklist

Check the version. Below 26.7.2 there is a critical password reset bug.
Build the image with the build phase done and start with the optimised flag.
Strict hostname, administration console on another hostname, separate management port and not exposed.
Decide between organisations and one realm per tenant before creating the second tenant.
One client scope per resource, with an audience mapper, because resource indicators are not supported.
In the gateway, define the two audience and issuer variables. Without them none of that is validated.
For workloads inside the cluster, look at the Kubernetes identity provider before handing out client secrets.
Size by login peaks, not by number of services: the difference is eightfold.
Export the Keycloak events to the same place the gateway’s go, because the activity logging control needs them together.
Write into the design what the system does with a two-hour task, before someone solves the problem with an offline token.

Closing

Keycloak is a mature piece that solves one bounded problem well: knowing who the caller is, and saying so verifiably in a document that expires. In a sovereign inference platform that is worth a lot, because the alternative is an inventory of static keys spread across ten services that no audit can walk through.

What is not advisable is asking more of it. Fine-grained authorisation lives in each service, workload identity with attestation lives in SPIFFE, and the decision of which tool an agent may call lives in the MCP server.

And there is one concrete gap worth noting down, because it does not close on its own: the MCP specification marks two standards as mandatory, and of the two that would fall to an authorisation server, resource indicators are not implemented. The workaround with scopes and an audience mapper works, but it is a workaround, and whoever comes after will look for the standard parameter. Leaving it written in the design saves an afternoon.

Sources

Keycloak 26.7.3, 31 de agosto de 2026, y descargas.
Configuración del servidor, caché, bases de datos y nombre de host.
Integración con Model Context Protocol, intercambio de tokens y autenticación federada de clientes, 27 de enero de 2026.
Dimensionado de CPU y memoria e introducción a alta disponibilidad.
Bancos de pruebas de rendimiento de Keycloak 26.4, 1 de octubre de 2025.
Especificación de MCP, revisión 2026-07-28, autorización y buenas prácticas de seguridad.
KEP-3331, configuración estructurada de autenticación.
Real Decreto 311/2022, Anexo II.
Registro de CVE-2026-18963 en la base de datos de Red Hat y notas de la versión 26.7.3 en GitHub.
CNCF, proyecto Keycloak.

The gateway does not live alone: the JWT that does not validate the audience, the user who never reaches the trace, and the seams you have to write by hand

Sat, 12 Sep 2026 06:30:00 +0200

Eighth article in the operational track of the control layer. The previous seven deal with the gateway from the inside: the pair with Langfuse, day 2, virtual keys, humans and agents, prefix routing, the MCP gateway and sizing for agents. This one deals with what surrounds it. Verified against LiteLLM 1.102.0 and Langfuse 4.35.0, both with a commit of 11 September 2026.

TL;DR

The gateway has five neighbours: a database, a cache, an identity provider, a trace backend and a collector. Each neighbourhood has its own physics, and these are the seven things it decides.

The proxy starts without Postgres, but then only the master key works. The DATABASE_URL variable is optional (proxy_server.py:1163); without it, any key other than the master one returns a 400 for a missing connection (user_api_key_auth.py:1886). With a database configured but down, the default behaviour is to return 503, unless general_settings.allow_requests_on_db_unavailable is switched on.

Redis is never mandatory, and that is precisely the trap. There is a circuit breaker with a threshold of five failures and a recovery of sixty seconds (constants.py:456). When it opens, the proxy fails no request: it degrades to local memory. What is lost silently is that rate limits stop being global and become per pod.

No observability backend can bring a request down. All callbacks are launched with asyncio.create_task and their exceptions are caught and logged (litellm_logging.py:3235). If Langfuse does not respond, events are discarded as the queue fills up. There is no added latency, and there is no reliable record either: the pair’s observability is a statistical figure, not an audit record.

JWT authentication validates neither the audience nor the issuer unless two variables are defined. In _build_decode_kwargs (handle_jwt.py:1003) the audience comes from JWT_AUDIENCE and the issuer from JWT_ISSUER; if they are empty, the code sets verify_aud=False and verify_iss=False and emits a warning once only. Any valid token signed by that provider, issued for another service, is accepted.

Role-based access control ships disabled. enforce_rbac has a default value of False (_types.py:4848 onwards). With that value, a token whose role resolves to nothing does not produce a 403: it carries on through the flow. Real authorisation, then, comes from team membership, if there is a team claim configured at all.

The user identifier that reaches Langfuse is not the one from Keycloak. The user_id field of the trace is filled in with user_api_key_end_user_id (integrations/langfuse/langfuse.py:604), that is, with the user field of the OpenAI body, which the client sets. The subject of the token and the owner of the key do not travel. Anyone who wants per-person traceability needs to configure end_user_id_jwt_field or make the client send that field.

Langfuse provisions nothing from a claim. There is no variable that maps an OIDC claim to an organisation or to a project. The only thing available is static assignment at sign-up with LANGFUSE_DEFAULT_ORG_ID and LANGFUSE_DEFAULT_PROJECT_ID, the same for everyone. On top of that, per-project access control sits behind the Enterprise licence in the self-hosted edition, as do audit logs and per-project retention.

You are here: between the four pieces

The LiteLLM and Langfuse pair walked through the seam between the gateway and the trace backend: integration routes, cost that arrives as zero, correlation and queues with discarding. This article widens the focus to the other three neighbourhoods, with identity at the centre, because that is the one that orders everything else and the one an auditor asks about.

The identity piece itself, that is, Keycloak, is dealt with in the next article. Here we deal with the gateway side.

The analogy: the building site with five trades

On a small building site, the problem is rarely inside each trade’s work, it is at the joins: where the plumber leaves the pipe sleeve and the bricklayer closes up the partition wall, where the electrician wants to run through the same gap. Each trade does its part well and the join ends up badly resolved because it belongs to nobody.

An inference platform has five trades. The gateway knows about tokens, the identity provider knows about people, the trace backend knows about events, the database knows about spend and the cache knows about counters. Each one has good documentation. The joins have nobody’s documentation, and that is where the user’s identity gets lost between the token and the trace.

There is one more detail of the analogy that is useful. On a building site, the part that causes the most problems is not the one that looks badly finished, it is the one that gets covered up. The same happens here: the five seams in this article fail silently.

Seam 1. What brings things down and what degrades them

It pays to have written down what happens when each neighbour falls over, because intuition fails in almost every case.

Neighbour	Does it start without it?	If it falls over
Postgres	Yes, master key only	503 by default; degraded with `allow_requests_on_db_unavailable`
Redis	Yes	Circuit breaker after 5 failures; limits become per pod
Langfuse	Yes	Events discarded as the queue fills; no impact on latency
OTel collector	Yes	Same as the previous one
Identity provider	Yes	Access to the interface and the JWT flow goes down; virtual keys carry on

Postgres

Without DATABASE_URL, _setup_prisma_client returns None without error (proxy_server.py:10375). The proxy serves /chat/completions with the master key. Any other key gets a 400. There is no global budget either, and start-up itself warns about it: Redis does not replace the database (proxy_server.py:9240).

With a database configured and down, the exception handler re-raises unless the degradation flag is active (db/exception_handler.py:56). There is also a DISABLE_PRISMA_HEALTH_CHECK_ON_STARTUP and a watcher that reconnects. The detail that matters for diagnosis: a transient database failure returns 503, not 401. If during an incident you see 401s, the problem is credentials; if you see 503s, it is the database or admission.

Redis

The circuit breaker is enabled by default, with a threshold of five failures, a recovery of sixty seconds and a minimum duration of five (constants.py:456, logic in caching/redis_cache.py:153). The socket has a timeout of 0.1 seconds (constants.py:453). With the circuit open, DualCache serves from memory without propagating an exception (dual_cache.py:215).

The consequence has to be measured, not assumed: with four workers and three replicas, a limit of one hundred requests per minute becomes one thousand two hundred. It is a failure mode that generates no errors and that can last for days without anyone noticing, until the bill arrives or the engine saturates.

The right alert is not about Redis, it is about litellm_service_latency labelled by service (integrations/prometheus_services.py:119), which exposes Redis and database latency separately.

The callbacks

Everything behind, that is, Langfuse and the collector, is launched outside the response path and its failures are caught. The classic integration uses the v2 SDK with its own background thread and a flush interval of one second, adjustable with LANGFUSE_FLUSH_INTERVAL (langfuse.py:198). There is a cap of fifty instantiated Langfuse clients (constants.py:554), because each client is a thread.

The OTLP integration uses the batch processor of the OpenTelemetry SDK (opentelemetry.py:3060) with its default values. In both cases, saturation means discarding, and discarding generates no error towards the client.

Seam 2. Identity: the three doors and what each one validates

Everything goes through a single authentication constructor (user_api_key_auth.py:1245), in this order:

Custom authentication from the enterprise edition.
Public routes.
Opaque OAuth2, if enabled, with a licence check.
JWT, if general_settings.enable_jwt_auth is active and the token has three parts.
Master key, with constant-time comparison.
Virtual key, with SHA-256 hash and lookup in the verification table.

A JWT works for /chat/completions, not just for administration: the routes allowed by default for a team include openai_routes (_types.py:4886), which contains the chat endpoint. Administration, on the other hand, is only reachable by a token with an administrator role.

The first thing to know: it is paid for

The JWT branch carries an explicit licence check, with the literal message that JWT authentication is an enterprise-only feature (user_api_key_auth.py:1416). SSO for the administration interface is free up to five billable users and requires a licence above that (ui_sso.py:976).

This conditions the architecture of any sovereign deployment that does not want to pay for a licence: the Keycloak integration is left for the administration interface and for provisioning, while inference traffic authenticates with virtual keys. Virtual keys are not worse, but they are a different thing, and it has to be said in the risk analysis: they are credentials decoupled from the identity provider, so removing a person from Keycloak does not invalidate their key.

The `litellm_jwtauth` fields that decide security

From the LiteLLM_JWTAuth class (_types.py:4848 onwards), these are the ones that matter, with their default values:

Field	Default	What it does
`enforce_rbac`	`False`	If false, an unresolved role does not produce a 403
`enforce_scope_based_access`	`False`	Without this, `scope_mappings` is not applied
`enforce_team_based_model_access`	`False`	Model access by team
`team_id_jwt_field`	`None`	Claim the team comes from
`team_id_upsert`	`False`	If false, a team that does not exist gives a 404
`user_id_upsert`	`False`	Same with the user
`public_key_ttl`	`600`	Cache of the public keys
`public_key_stale_ttl`	`3600`	Extra margin if the provider is down
`admin_jwt_scope`	`litellm_proxy_admin`	Scope that grants administration
`user_allowed_email_domain`	`None`	Restriction by email domain

The accepted algorithms are RS256/384/512, PS256/384/512, ES256/384/512 and EdDSA (handle_jwt.py:163). There is no symmetric one, which eliminates the algorithm confusion class of attack. It is a good design decision and it deserves recognition.

Key download supports several comma-separated URLs in JWT_PUBLIC_KEY_URL, resolves discovery if the URL points to the well-known OpenID configuration, retries three times with increasing waits and memoises the failure for thirty seconds (handle_jwt.py:680, :751, :88). If the provider is down, it serves the stale copy up to the sum of the two TTLs, that is, up to seventy minutes. For availability that is fine; for revocation it is not, and it has to be written down.

One detail of key rotation: with more than one key in the set, an exact match of the key identifier is required, but with a single key and no identifier it is accepted without checking (handle_jwt.py:913).

The validation that does not happen

This is the part to fix on day one. In _build_decode_kwargs (handle_jwt.py:1003), the audience is taken from the JWT_AUDIENCE environment variable and the issuer from JWT_ISSUER. If they are not defined, the code sets verify_aud=False and verify_iss=False, and emits a warning once only.

What that means in a real deployment with Keycloak: a token issued for the Grafana client, or for the Backstage one, signed by the same realm, is accepted by the gateway as a valid credential. Expiry is always validated, with zero margin. So is the signature. The audience is not.

There is a second route, issuers, with per-issuer configuration, which does validate issuer and audience unless explicitly disabled (handle_jwt.py:1186). That is the one to use when there is more than one provider.

The minimum fix is two lines of environment:

JWT_AUDIENCE=litellm-gateway
JWT_ISSUER=https://sso.ejemplo.es/realms/plataforma

And on the Keycloak side, an audience mapper in a dedicated client scope that injects that audience. The detail is in the Keycloak article, because the standard that would resolve this cleanly, resource indicators, is not supported.

From claim to permission

The administrator role comes from admin_jwt_scope appearing in the scope claim, and it returns a result without going through a team (handle_jwt.py:309, :1373). The rest is resolved by team.

If the team in the claim does not exist in the database, with team_id_upsert false a 404 is returned with the message that the team has to be created (auth_checks.py:3035). With the flag active, it is created by invoking team creation with a synthetic administrator identity (auth_checks.py:2874). That is the only automatic provisioning route that exists from Keycloak towards the gateway, and it works well. It pays to know that it creates teams with no budget and no limits, so a default value is needed in the configuration.

The vulnerability worth knowing about

CVE-2026-35030, scoring 9.1 on CVSS 3.1 and 9.4 on CVSS 4.0, advisory GHSA-jjhc-v7c2-5hh6. With JWT authentication active, the cache of the OIDC user info endpoint used the first twenty characters of the token as the key, so that two tokens with the same prefix were confused with each other. Fixed in 1.83.0.

In 1.102.0 the code uses the full SHA-256 hash (handle_jwt.py:962). A search for similar patterns across the tree finds no authentication cache indexed by token prefix: the truncations that remain are masked for logging. And it is worth recalling what has already been published about the MCP gateway: below 1.83.14 there is unauthenticated remote execution or SQL injection.

Seam 3. Identity does not reach the trace

Here lies the most expensive design flaw in the arrangement, because it is discovered at the first audit.

The user_id field of a Langfuse trace is filled in with user_api_key_end_user_id (integrations/langfuse/langfuse.py:604 and :724), which comes from the user field of the OpenAI request body or from end_user_id_jwt_field (litellm_pre_call_utils.py:1584). It is not the subject of the token nor the owner of the virtual key.

The knock-on consequences:

If the client does not send user, the trace has no user.
If the client does send user, the trace has whatever value the client cares to put there, unverified.
An agent calling with a service key leaves traces with no person behind them.

There are three ways to fix it, in order of robustness:

Configure end_user_id_jwt_field so that the end user comes from a token claim and not from the body. It is the only option in which the value is not controlled by the client, and it requires JWT authentication, that is, a licence.
Force the trace_user_id metadata field, which overwrites the field (langfuse.py:726; on the OTLP route, langfuse_otel.py:96). It can be set per team.
Contractually require the client to send user and validate it in a guardrail. It works, but it is a client declaration, not a proof.

Something similar happens towards the engine. The caller’s identity does not travel to vLLM unless litellm.add_user_information_to_llm_headers is switched on, whose default value is None (litellm/__init__.py:223). With it, x-litellm-* headers are injected with user identifier, team identifier and key hash (litellm_pre_call_utils.py:1356). Forwarding client headers requires general_settings.forward_client_headers_to_llm_api, and the authorization header is always filtered out, which is correct.

Towards MCP servers, by default the server’s own credential is used, not the user’s token. Only two modes forward the caller’s token, and doing so has a name in the MCP specification: token passthrough, which is explicitly forbidden. It comes up again in the Keycloak article.

Seam 4. Langfuse as a neighbour

What can be automated and what cannot

The exact list of variables for SSO in Langfuse 4.x, taken from web/src/env.mjs:

With the Keycloak provider: AUTH_KEYCLOAK_CLIENT_ID, AUTH_KEYCLOAK_CLIENT_SECRET, AUTH_KEYCLOAK_ISSUER, AUTH_KEYCLOAK_ALLOW_ACCOUNT_LINKING, AUTH_KEYCLOAK_CLIENT_AUTH_METHOD, AUTH_KEYCLOAK_CHECKS, AUTH_KEYCLOAK_ID_TOKEN_SIGNED_RESPONSE_ALG, AUTH_KEYCLOAK_SCOPE, AUTH_KEYCLOAK_ID_TOKEN, AUTH_KEYCLOAK_NAME.

With generic OIDC: the same set with the AUTH_CUSTOM_ prefix, plus AUTH_CUSTOM_FETCH_USERINFO and claim mapping with LANGFUSE_CUSTOM_SSO_SUB_CLAIM, LANGFUSE_CUSTOM_SSO_EMAIL_CLAIM, LANGFUSE_CUSTOM_SSO_NAME_CLAIM and LANGFUSE_CUSTOM_SSO_IMAGE_CLAIM.

Global ones: AUTH_DISABLE_USERNAME_PASSWORD, AUTH_DISABLE_SIGNUP, AUTH_DOMAINS_WITH_SSO_ENFORCEMENT, AUTH_SESSION_MAX_AGE.

And now what is missing. There is no variable that maps a claim to an organisation or a project. The only thing available is static assignment at sign-up with LANGFUSE_DEFAULT_ORG_ID, LANGFUSE_DEFAULT_ORG_ROLE with a default value of VIEWER, LANGFUSE_DEFAULT_PROJECT_ID and LANGFUSE_DEFAULT_PROJECT_ROLE (features/auth/lib/createProjectMembershipsOnSignup.ts:61). The documentation itself confirms it: enterprise SSO does not provision roles automatically at sign-up.

On top of that, in the per-edition permissions table (features/entitlements/constants/entitlements.ts:139), the open and self-hosted professional editions do not include per-project access control or the administration API. They belong to the enterprise edition, as do audit logs and per-project retention. In the open edition, every user inherits the role of their organisation.

The declarative bootstrap, which does exist

For on-premise without a licence, the workable route is bootstrapping through variables (web/src/initialize.ts), which is idempotent: LANGFUSE_INIT_ORG_ID (mandatory, if missing the rest is ignored with a warning), LANGFUSE_INIT_ORG_NAME, LANGFUSE_INIT_PROJECT_ID, LANGFUSE_INIT_PROJECT_NAME, LANGFUSE_INIT_PROJECT_RETENTION, LANGFUSE_INIT_PROJECT_PUBLIC_KEY, LANGFUSE_INIT_PROJECT_SECRET_KEY, LANGFUSE_INIT_USER_EMAIL, LANGFUSE_INIT_USER_NAME, LANGFUSE_INIT_USER_PASSWORD.

With that, one project per tenant is created from GitOps with one initialisation container per tenant and the keys in Kubernetes secrets.

Langfuse credentials per team

This part is well resolved on the gateway side and few people use it. TeamCallbackMetadata.callback_vars (_types.py:2152) accepts langfuse_public_key, langfuse_secret_key, langfuse_host and langfuse_environment, with an allow list in initialize_dynamic_callback_params.py:67. The gateway caches one logger per credential set (langfuse_handler.py:24) and, on the OTLP route, builds a full exporter per key (langfuse_otel.py:400).

That is to say: one Langfuse project per LiteLLM team is possible today, without a licence, and it is the correct way to isolate traces between tenants. What does not exist is automatic project creation, nor the correspondence between the team and the project. That is glue you have to write.

The ingestion route

Langfuse accepts only OTLP over HTTP, in http/protobuf or http/json. gRPC is not supported. The base route is /api/public/otel and the signal lives at /api/public/otel/v1/traces, verified in the repository. Authentication is Basic with the project’s key pair, plus the x-langfuse-ingestion-version: 4 header for the version 4 route.

The gateway builds it exactly like that (langfuse_otel.py:328, :347, :359) and then normalises the endpoint by adding the signal suffix (opentelemetry.py:3237). The result matches the real route, so the integration works without touching anything. The detail matters when a collector is put in the middle and somebody copies the endpoint by hand.

And the calendar warning that already appeared in the operational pair still stands: the classic callback is tied to the v2 SDK and the date marked is 16 November 2026. With a nuance worth reading before scheduling an emergency migration, which is detailed in the data model article: that date applies to Langfuse Cloud, and in the code of the self-hosted version the old route is not switched off, it changes behaviour according to the write mode.

When to put a collector in

Direct if Langfuse is the only trace destination. Via a collector if there is more than one consumer, or if any of these three things is needed that the proxy’s batch processor does not provide:

Retries with increasing waits and an on-disk queue, with the sending_queue and file_storage processors. With that, a Langfuse maintenance window stops losing traces.
Tail sampling, which lets you keep 100 % of errors and 1 % of the rest. The proxy cannot sample by outcome, because at the point it decides it does not yet know how things ended.
Attribute redaction before they leave the namespace. It is the only layer where you can delete the MCP tool arguments which, as has already been documented, are written in the clear, bypassing the message redaction switch.

Seam 5. Postgres, Redis and the memory policy

Separate Postgres, always. Each piece applies its own Prisma migrations over the public schema of the database it is given. Two Prisma clients migrating the same schema collide over table names and over migration history. On top of that, Langfuse 4.x requires Postgres 15 as a minimum, recommends 16 and wants UTC by default. The load profile is also the opposite: the gateway writes spend records at high frequency, while Langfuse does light transactional work because trace data goes to ClickHouse.

Separate Redis, and the argument is not the one it looks like. There is no key collision by design: the gateway uses hash tags of the form {api_key:...}:requests and an optional namespace, and Langfuse uses the BullMQ prefix plus its own prefix for its key cache. The decisive argument is another one: Langfuse requires maxmemory-policy=noeviction because its queues are data, not cache, while the gateway assumes a disposable cache. Sharing an instance means that a spike of rate limit keys can fill the memory and cause write errors in the ingestion queues instead of a harmless eviction.

If it is shared anyway, two minimum measures: REDIS_KEY_PREFIX in Langfuse, namespace in the gateway, and different logical databases.

And a reminder about surface area: Langfuse 4.x does not start without ClickHouse or without an S3-compatible bucket. CLICKHOUSE_URL and LANGFUSE_S3_EVENT_UPLOAD_BUCKET are mandatory and have no default value (packages/shared/src/env.ts:120 and :271). Its failure surface is far larger than the gateway’s, and that changes where to put the high availability effort.

Ports, for the NetworkPolicy

Piece	Port
LiteLLM (API, interface and metrics)	4000
Langfuse web	3000
Langfuse worker	3030
ClickHouse	8123 HTTP, 9000 native
S3-compatible storage	9000
Redis	6379
Postgres	5432
OTel collector	4317 gRPC, 4318 HTTP

The pairs to allow under a default-deny policy, following the method from hardening the stack:

litellm → postgres:5432, redis:6379
litellm → collector:4318 (or langfuse-web:3000 if going direct)
litellm → vllm:8000
litellm → keycloak:8443 (interface and JWT flow only)
collector → langfuse-web:3000
langfuse-web → postgres:5432, redis:6379, clickhouse:8123, s3:9000
langfuse-worker→ postgres:5432, redis:6379, clickhouse:8123, s3:9000
langfuse-web → keycloak:8443
ingress → litellm:4000, langfuse-web:3000
prometheus → litellm:4000

The Langfuse worker needs no inbound traffic beyond the health probe.

The glue you have to write

Put into a table, the real state of the tenant chain:

Segment	Automatic?	How
Keycloak → LiteLLM team	Yes	`team_ids_jwt_field` plus `team_id_upsert: true`
Keycloak → LiteLLM user	Yes	`user_id_jwt_field` plus `user_id_upsert: true`
Keycloak → Langfuse organisation	No	Static assignment at sign-up only
Keycloak → Langfuse project	No	Same
LiteLLM team → Langfuse project	No	`callback_vars` by hand, or an operator of your own
Keycloak user → trace `user_id`	No	`end_user_id_jwt_field`, or a contract with the client

The minimum viable architecture without a licence, then, is this:

One Langfuse project per tenant, created with the initialisation variables from GitOps.
That project’s keys in a Kubernetes secret.
A periodic job of your own that reads the teams through the gateway’s administration API and writes callback_vars with the corresponding keys.
People entering Langfuse through Keycloak, but assigned by hand to their organisation.
The end user identifier resolved by contract with the clients, and validated.

That is about one hundred and fifty lines of your own code. It pays to budget for them from the start, because the gap does not close by itself.

Reference configuration

general_settings:
 # only with a licence; without one, virtual keys
 enable_jwt_auth: true
 litellm_jwtauth:
 team_ids_jwt_field: "groups"
 team_id_upsert: true
 user_id_jwt_field: "sub"
 user_id_upsert: true
 end_user_id_jwt_field: "preferred_username"
 user_allowed_email_domain: "ejemplo.es"
 admin_jwt_scope: "litellm_proxy_admin"
 # the three that ship switched off
 enforce_rbac: true
 enforce_scope_based_access: true
 enforce_team_based_model_access: true
 allow_requests_on_db_unavailable: false
 proxy_batch_write_at: 60

litellm_settings:
 callbacks: ["langfuse_otel", "prometheus"]
 # without this, the engine does not know who is calling
 add_user_information_to_llm_headers: true
 turn_off_message_logging: true
 cache: true
 cache_params:
 type: redis
 host: os.environ/REDIS_HOST
 namespace: litellm

# the two that enable the validation that by default does not happen
JWT_AUDIENCE=litellm-gateway
JWT_ISSUER=https://sso.ejemplo.es/realms/plataforma
JWT_PUBLIC_KEY_URL=https://sso.ejemplo.es/realms/plataforma/.well-known/openid-configuration

LANGFUSE_HOST=http://langfuse-web.observabilidad.svc:3000
LANGFUSE_PUBLIC_KEY=...
LANGFUSE_SECRET_KEY=...

And on the Langfuse side:

AUTH_KEYCLOAK_CLIENT_ID=langfuse
AUTH_KEYCLOAK_ISSUER=https://sso.ejemplo.es/realms/plataforma
AUTH_KEYCLOAK_ALLOW_ACCOUNT_LINKING=true
AUTH_DISABLE_USERNAME_PASSWORD=true
AUTH_DISABLE_SIGNUP=true
LANGFUSE_DEFAULT_ORG_ID=plataforma
LANGFUSE_DEFAULT_ORG_ROLE=VIEWER
ENCRYPTION_KEY=... # 64 hexadecimal characters

Checklist

Define JWT_AUDIENCE and JWT_ISSUER on day one, or use the per-issuer configuration. Without that, neither audience nor issuer is validated.
Set enforce_rbac, enforce_scope_based_access and enforce_team_based_model_access to true, and test that a token from another client of the same realm is rejected.
Decide where the end user of the traces comes from and write it into the design. If it is not decided, traces come out with no person.
Separate Postgres. Separate Redis. If Redis is shared, different prefix and logical database, and review the memory policy.
Check that the proxy starts with Postgres down only if that is what you want, and that the on-call team can tell an admission 503 from a credential 401.
Alert on litellm_service_latency per service, not on Redis availability, because the circuit breaker hides the problem.
One Langfuse project per tenant with the initialisation variables, and the per-team keys in callback_vars.
Put a collector in the middle if you need an on-disk queue, tail sampling or attribute redaction.
Check that the gateway version is above 1.83.14 because of the earlier critical vulnerabilities.
Write into the risk analysis that virtual keys are credentials decoupled from the identity provider, and define the offboarding procedure.

Traps and things that are not what they seem

A properly signed JWT is not a JWT addressed to this service. Without the two environment variables, the audience is not checked.

enforce_rbac set to false does not mean there is no authorisation, it means that authorisation comes only from team membership, if there is a team claim. With no team claim and without the flag, a valid token reaches /chat/completions.

The stale copy of the public keys lasts up to seventy minutes, adding the two TTLs. Revoking a key at the provider does not take effect immediately.

With a single key in the JWKS and no key identifier, the identifier is not checked.

The trace user is set by the client. Any per-person spend report built on that field is a declaration, not a measurement.

Redis going down generates no errors, it generates per-pod limits. It is the most expensive of the failures that give no warning.

Langfuse does not start without ClickHouse or without an S3 bucket. Its failure surface is bigger than the gateway’s, and that changes how the high availability effort is shared out.

Langfuse’s per-project access control is paid for in self-hosted, as are audit logs. For an ENS file, that gets decided before building, not after.

Sharing Redis does not break through key collision, it breaks through memory policy. It is a failure that shows up under load and gets diagnosed badly.

Langfuse’s ingestion route is OTLP over HTTP only. A collector configured with the gRPC exporter points at somewhere that does not exist.

Closing

The five seams share a common pattern: they fail without warning. The token from another service gets in, the trace user comes from the client, the rate limit stops being global, the spend queue discards on reaching 64 MB and the Langfuse project does not create itself. None of those five things produces a visible error.

Day 2 work, then, consists above all of turning silences into signals. Two environment variables so that the audience is validated, three flags so that authorisation is real, an alert on service latency instead of on Redis availability, and an explicit contract on where the end user’s identity comes from.

And one decision worth taking early, before the budget is closed. The gateway’s JWT authentication and Langfuse’s per-project access control are both behind a licence. A sovereign platform can live perfectly well without either, with virtual keys and one project per tenant, but it is a different architecture and it has to be drawn as such from the start.

Sources

Código de LiteLLM 1.102.0, commit 9071ca50 del 11 de septiembre de 2026.
Código de Langfuse 4.35.0, commit 39e3cd7d del 11 de septiembre de 2026.
Autenticación y SSO en Langfuse, consultado el 12 de septiembre de 2026.
SCIM y API de organización, consultado el 12 de septiembre de 2026.
Integración OpenTelemetry de Langfuse, consultado el 12 de septiembre de 2026.
Postgres y caché en la documentación de self-hosting, consultados el 12 de septiembre de 2026.
Autenticación por token en LiteLLM y ajustes de configuración, consultados el 12 de septiembre de 2026.
GHSA-jjhc-v7c2-5hh6 y registro de CVE-2026-35030 en NVD.

LiteLLM's MCP gateway: the second front door, the tool catalogue nobody bills, and why filtering it can make selection worse

Fri, 11 Sep 2026 01:45:00 +0200

Sixth post in the operational track on the control layer. The previous five treat the gateway as the piece the tokens pass through: the pair with Langfuse, day 2, virtual keys, humans and agents and prefix routing. This one is about the other door. Verified against LiteLLM 1.102.0, commit of 10 September 2026.

TL;DR

The MCP gateway is not a module, it is a complete second surface. A native MCP endpoint with four route spellings, a proxy mode with three fixed tools, four REST routes, some thirty-five administration routes and a long set of OAuth discovery endpoints. It still lives under _experimental and it is nearly 20,000 lines.

I correct what I said in the previous post: access is NOT open by default. In 1.102.0, a key with no declared permissions and no team resolves zero servers. What does open things up is a per-server flag, allow_all_keys, and that flag overrides the key’s explicit scope unless you enable a setting that is off by default.

Permissions are enforced on execution, not just on the listing. Calling a tool that did not appear in tools/list returns 403. There are three chained checks before the call, including one on the allowed arguments. The same predicate governs listing and calling, by declared design.

The hierarchy is built out of intersections, with two escapes and a fail-open. The key’s access groups are additive on top of the key and team ceiling. The organisation ceiling replaces rather than intersects when there is nothing below it. And on an indeterminate error while resolving tool permissions, the code returns “unrestricted”. It is a deliberate decision and it has to be declared in the risk analysis.

Per-tool cost is worth zero and that is why its metric disappears. There are exactly two Prometheus metrics for MCP, and the spend one is only incremented if the cost is greater than zero. With the default configuration, that series never exists. There is no listing metric, no latency metric, no error metric, no server health metric.

The cost that does matter is not attributed to MCP anywhere. It is the tokens of the tool definitions, resent on every turn inside the prompt_tokens of the model call. Five typical MCP servers add up to 58 tools and some 55,000 tokens. The tool’s spend row, with its zero cost, has nothing to do with that.

And the gateway’s semantic filter does not act on the MCP door. It only applies when it is LiteLLM calling the model. A client connected to /mcp receives the whole catalogue, filter enabled or not. And even if it did act, filtering per request rewrites the cached prefix of the prompt, which is the opposite of what Anthropic and OpenAI do with their own tool searches.

The good observability ships switched off. Without LITELLM_OTEL_V2, a tool call comes out as a generic span with the model set to MCP: name. With it enabled there is a dedicated span and correct attributes, and the arguments and the result stay hidden unless you opt in. And in neither case is trace context propagated towards the upstream MCP server: the trace is cut at the gateway.

Tool arguments are written, and they are written in the clear. They go in full into the metadata column of the spend table, without passing through the switch that governs prompt storage nor through the redaction function, which only knows about messages and response. Whoever enabled redaction for GDPR probably believes they are covered.

The 1.83 branch concentrated four serious vulnerabilities, and one of them belongs to the MCP gateway itself. The endpoint for testing a connection before saving accepted the stdio transport’s command, args and environment in the request body. A low-privilege key got command execution on the proxy host.

And the specification moved underneath. The revision in force since July 2026 removed protocol sessions, the initialisation handshake and the session header. LiteLLM 1.102.0 advertises the June 2025 revision and its version enumeration does not even contemplate the two later ones.

You are here: the door nobody chose

The gateway was chosen for the reasons in the switchboard post: licence, fit inside the cluster, maturity. What was evaluated was the inference traffic.

Later, somebody connects an agent, the agent needs tools, and the same process that is already authenticated and deployed turns out to speak MCP too. The decision to turn it into the tool door is almost never taken: it is inherited. And that door has neither the same controls, nor the same observability, nor the same cost model.

When MCP grows covered the identity of your own MCP servers. MCP from the inside covered the protocol and its instrumentation. This post covers the piece in between.

The analogy: the switchboard that also hands out keys

An office building’s telephone switchboard. Its original job is to route calls: it decides who can call outside, how much each department spends, and it leaves a record of every conference call.

Over time, the switchboard operator is also given the key cabinet. They are already at reception, they already know who everybody is, it looks like the natural place. And from that moment there are two services at the same desk with very different rules.

Calls are priced by the minute and show up on the bill. Keys have no tariff, so on the department’s bill they come out at zero, and somebody might conclude that the key cabinet costs nothing. It does cost: it costs the operator’s time, it costs having to read the whole key catalogue every time somebody asks what is available, and it costs that nobody checks that the label on a key still says what it said the day its loan was authorised.

The analogy ends at the interesting spot. When somebody takes a key, the record says which key it was and what they said they wanted it for. That record is simultaneously the evidence of the action and a piece of data that perhaps should not be stored in the clear.

The real routes

The first thing that surprises you when you look at the code is how many spellings get you to the same place.

The native endpoint

The MCP sub-application is mounted at /mcp and inside it has four mounts: the root as a wildcard, /mcp, /{name}/mcp and /sse.

And there is also a hand-declared route for bare /mcp on the main application, with a comment that explains why: the mount cannot match its own bare prefix, and the resulting 307 redirect breaks MCP clients sitting behind a proxy that terminates TLS. It is the kind of detail you discover in production on a Friday.

/mcp/sse holds a surprise. It does not use the classic SSE transport: it uses the same HTTP session manager in stateless mode. The SseServerTransport object is constructed and is not referenced on any other line of the file. It is dead code, and the /mcp/sse/messages endpoint that this object advertises does not exist as a working route.

The /{name}/mcp route resolves in a documented order: server alias, comma-separated list with a maximum of 16 elements, tool set, access group. If nothing matches, 404.

And /mcp/proxy exposes a fixed surface of three tools. It is the progressive disclosure pattern, and it will come up again further down because it is the most important mitigation in this post.

The REST routes

Four, under the /mcp-rest prefix:

Method	Route	Authentication
GET	`/mcp-rest/tools/list`	Virtual key
POST	`/mcp-rest/tools/call`	Virtual key
POST	`/mcp-rest/test/connection`	Key plus administrator role
POST	`/mcp-rest/test/tools/list`	Key plus administrator role

The variants without -rest that appear in the internal types have no router registering them. The /mcp/* wildcard absorbs them as JSON-RPC.

The last two are the stars of the security section.

Administration and discovery

Some thirty-five routes under /v1/mcp, almost all of them with virtual key authentication. Three details worth knowing:

GET /v1/mcp/registry.json carries no authentication dependency. It returns 404 if the public registry is not enabled, which is the real protection.

POST /v1/mcp/server requires the proxy administrator role. POST /v1/mcp/server/register does not: it is the proposal path, which requires a key with a team, explicitly forbids the stdio transport and leaves the entry pending review.

And on top of that there is a long set of OAuth .well-known endpoints, with dynamic client registration, authorisation, token, revocation and introspection, plus their per-server variants.

Configuration and transport

The mcp_servers schema in config.yaml has fifty-odd fields, all of them optional. A warning for anyone coming from earlier versions: spec_version no longer exists in 1.102.0.

The default transport when omitted is http, that is, streamable HTTP. The other two values are sse and stdio. The string streamable_http is not valid in the configuration file, although it is accepted as a synonym when importing connector files.

Tool prefixing uses the format {server}{separator}{tool} with - as the default separator, configurable through an environment variable read at import time. The prefix chosen is the alias, or the name, or the identifier, in that order. There is an optional short mode that derives three characters from the hash of the server identifier and resolves collisions by rehashing.

Access control, and the correction to the previous post

In the humans and agents post I closed the list of traps with this one: “access to MCP servers is open by default if no level defines a list”. Verified in 1.102.0, that is false.

The function that resolves the allowed servers does the opposite. If the team declares nothing, it inherits from the key; if the key declares nothing either, the base set is empty and the scope is marked as unbounded with zero servers. There is no branch that expands to “the whole registry” other than the administration role one.

What does open things up, and this is the important part, is something else.

`allow_all_keys`

It is a per-server flag, in configuration, in the API and in the database, defaulting to false. When set to true, that server joins the set of open servers and any key can see it.

The detail to know: by default it overrides the key’s explicit scope. A key that declares access only to server A will also see server B if B has the flag. The key’s scope is only respected if you enable general_settings.mcp_allow_all_keys_respects_mcp_scope, which is off by default.

There is a second opening case: anonymous subjects, with no user identifier, role or key, additionally receive the servers configured with authentication delegation towards the upstream and the pass-through ones. It is consistent with the design of those two modes, and it is a surface you have to know about.

`require_key_mcp_access_defined`

It lives in general_settings, defaults to false, and needs no licence. What it inverts is only the empty-key inheritance towards the team: with the flag on, a key with no list of its own gets an empty set instead of inheriting the team’s.

It does not affect keys that do declare servers, which still intersect with the team. And it does not close off the access group grants, which are additive and are the escape route you have to audit separately.

There is a sibling, require_end_user_mcp_access_defined, with the same shape and applied to the end user.

The hierarchy

The function’s docstring is normative and says that all the rules are intersections. In detail:

Key and team: intersection when both declare. Inheritance in one direction when one is empty.
Key access groups: additive union on top of the previous result.
End user: intersection if it declares anything.
Agent: intersection.
Internal user: ceiling that only narrows.
Organisation: ceiling that intersects if there are restrictions below, and that replaces by becoming the ceiling when there are none.

For subjects with no key, admitted by SSO or by the gateway, the model changes to a per-source union instead of an intersection.

The fail-open

This is the point you have to take to the risk analysis and not leave in a technical note.

On an indeterminate failure while resolving the tool permissions of a key or a JWT, the code returns “unrestricted”, that is, all tools allowed. The organisation ceiling is skipped in the same situation. For subjects with no key the behaviour is the opposite, fail-closed.

There is a well-resolved intermediate case: when a permission is named but cannot be read, a specific error is raised and it is denied in both cases.

The doctrine is documented in the class docstring, which is appreciated. And it remains a behaviour that, in a system under the ENS, you have to declare in writing instead of discovering it during an audit.

What is done well

Permissions are enforced on the call, not just on the listing. The execution path chains three checks before contacting the server: allowed or forbidden tools, per key and team tool permission, and validation of the arguments against the allowed ones. All three return 403.

Listing and calling share the same predicate, and the docstring declares it as an explicit invariant. A client that calls a tool directly when it did not appear in its listing receives 403, it does not execute. The same over REST and over the responses API route.

The x-mcp-servers and x-mcp-access-groups headers only narrow, and they fail closed if they do not resolve.

Header forwarding towards the upstream is an explicit per-server allowlist, with a centralised decision about when to strip the caller’s Authorization, and a protection against cross-forwarding: in a multi-server listing, the global header is withheld if more than one server would consume it. That is RFC 9700 applied.

The bill that never shows up

Here is, in my opinion, the most important thing in this post, and it has nothing to do with security.

Every tool the gateway aggregates takes up space in the model’s context. Name, description and parameter schema travel in the request’s tools block, on every turn, and they are paid for as input tokens of the real model.

The figures published by Anthropic in November 2025 are the best public reference there is. Five connected MCP servers add up to 58 tools and some 55,000 tokens. The breakdown: GitHub, 35 tools and some 26,000 tokens. Slack, 11 tools and some 21,000. Sentry, five and some 3,000. Grafana, five and some 3,000. Splunk, two and some 2,000.

With tool search enabled, that set drops from some 72,000 to some 8,700 tokens, and the usable context goes from 122,800 to 191,300.

The second cost of a large catalogue is not economic and is not billed: it is that the model chooses worse. It has its own section further down, because of the two it is the one that decides whether the agent is any good.

How to measure it with what is already there

The gateway stores enough data, even if it does not cross-reference it for you.

In the listing’s spend row, with call type list_mcp_tools, it enriches the metadata with allowed_server_count, tool_count_total, per_server_tool_counts and per_server_list_outcomes.

In the model call rows, the proxy_server_request column keeps the request body with the tools block inside it.

The practical method: pair the listing rows with the LLM rows of the same session by session_id, read the total number of tools from the first, and pass the tools array of the second through litellm.token_counter(model=..., tools=...), which accepts that argument. Multiply by the number of turns, because the block is resent on all of them.

For the relative cost, a quicker comparison: mean prompt_tokens of keys with MCP enabled against those without, same model and same period.

Tool selection

The previous section treats the catalogue as a bill. This one treats it as what determines whether the agent gets it right. This is ground where the talk runs well ahead of the measurement, so it is worth separating what has been measured from what gets repeated.

How many tools a model can take

Anthropic’s official figure is that Claude’s ability to pick the right tool degrades when going from 30 to 50 available tools. The same documentation gives the inverse criterion, which is the more useful one: the full catalogue with nothing else is the right option with fewer than ten tools, when all of them are used on every request, or when the definitions add up to fewer than a hundred tokens.

There is also an administrative ceiling before the semantic one. VS Code with Copilot cuts off at 128 tools per request and returns an error when you exceed it.

The full curve gets cited far more than it has been measured. The soundest primary data I found is from May 2025: varying the number of candidates from 1 to 11,100 over a registry of more than 4,400 servers, below some 30 tools the success rate is above 90 %, between 31 and 70 intermittent failures appear, and past the hundred mark the degradation becomes dominated by retrieval. It is a qualitative heat map, not a numeric table.

The figure that circulates most (78 % with ten tools, 40 % with a hundred, 13.6 % with seven hundred) comes from a conference talk with no paper, no repository and no published methodology. Do not take it to a client presentation.

And there is a warning that affects everything else. An audit of 496 tasks from four tool calling benchmarks found 18.5 % misalignment between the label and reality. In the BFCL v4 subset, 80 % of the failures assigned to the agent came from fragile state comparisons. In one of the benchmarks with an automatic judge, 23 identical re-runs gave a range from 57.9 % to 76.8 %, almost 19 points of spread, enough to reorder the ranking. Any absolute figure in this section deserves a generous margin of error.

How it fails

The work with the cleanest taxonomy evaluates 36 servers, 220 tools and 1,000 tasks against twenty frontier models, with an average of 15.2 tools exposed per task of which 4.1 are relevant.

Failure mode	Share
Not using a tool when one was needed	10.5 %
Choosing the wrong tool	9.0 %
Malformed parameters	6.9 %
Not recovering from an error	10.3 %
Cognitive failures, not tool failures	63.3 %

The interesting part is in the per-model breakdown: the dominant failure mode changes with the model, not with the size of the catalogue. In one of them, 40.1 % of the failures are simply not calling any tool. In others the malformed parameter dominates. In another, the wrong tool. There is no canonical failure to attack.

On tools that do the same thing, which is the real case of a gateway with fifteen servers, there is a good measurement. A study with ten groups of five functionally equivalent tools and a thousand query pairs puts the selection bias between 0.3 and 0.4, that is, you would have to redistribute between 30 and 40 % of the probability mass for equivalent tools to be chosen equally. The same work shows that a biased continued training takes the selection of a specific endpoint from 0.6 % to 12.8 %.

That study contributes another figure that reorders priorities: shuffling a tool’s description moves the selection distribution substantially, whereas changing only the name has minimal and inconsistent effects. Applied to the gateway’s server-tool prefixing: it costs tokens and probably does not change which tool the model goes to. There is no study isolating the effect of name spacing, and it is a real gap in the literature.

If the description is what carries weight, the state of the estate is the problem. An audit of 856 tools from 103 MCP servers found undeclared limitations in 89.8 %, missing usage guidance in 89.3 % and opaque parameters in 84.3 %. Only 2.9 % were free of problems across all their components.

The optimum is not a number

The May 2026 work I cited above proposes a chance-corrected metric and uses it to size the list adaptively. Over 370 functions it reaches 90.3 % coverage while seeing an average of 7.4 tools, against 90.8 % seeing a fixed 50.

But the same paper publishes its own counterexample, and it is honest to cite it: over another benchmark of 3,251 tools, the fixed K of 5 wins in aggregate, 64.7 % against 61.9 %. The adaptive advantage concentrates in the hard queries, where the right tool sits between sixth and twentieth by similarity: there it finds 16.7 % of the cases where the fixed K finds 0 %.

The March 2026 work over 121 tools puts the plateau at K=3, with 97.1 % that does not improve going up to K=5. With the caveat that it measures retrieval against labels, not model accuracy.

And a July 2026 work gives the formulation that seems to me the right one: ranking by score is inconsistent with optimal acquisition when costs are heterogeneous, so the optimal K is a function of cost, not a constant. Trimming from 7 to 4.4 exposed tools while keeping success is possible; fixing a universal number is not.

Filtering can make the result worse

This is the part that appears in no product blog. A June 2026 benchmark with three registry sizes (25, 100 and 250 tools), six filtering methods, seven models and 26,460 runs:

Strategy	Success	Visible tools	Tokens
Expose the whole catalogue	32.1 %	125.00	56,062
Keyword, top-5	22.1 %	4.80	3,200
Keyword, top-10	22.4 %	9.54	5,356
State-aware	24.0 %	25.95	13,522
Full causal path	24.0 %	26.24	13,697

Four of the five filtering strategies perform worse than not filtering. The fifth, which does win comfortably, exposes 0.99 tools per step and requires hand-written precondition and effect contracts for every tool, plus a search of the causal path to the goal state. It is a planner with the goal given, not a retrieval filter, and it is not comparable with anything a gateway offers.

There is more evidence in the same direction. A work over a corpus of 43,000 tools measured that the agent’s completion rate drops when using retrieved sets against hand-annotated sets: the filter introduces its own recall ceiling. And top-K breaks the tasks that need several tools: on a benchmark of 16,464 endpoints, a fine-tuned retriever reaches a Recall@3 of 68.6 % but only 39.7 % of the queries have their complete tool set within the first three. Almost 29 points of gap between “the one I needed is there” and “all the ones I needed are there”.

Filtering is not free on security either. A March 2026 work attacks the retrieval layer by injecting adversarial tools that saturate the top-k: with injection rates of 1.2 % it manages to dominate the top-k between 91 % and 97 % of the time. It is an attack surface that exposing the whole catalogue does not have.

The most elegant counterpoint comes from Anthropic’s own numbers. With the same catalogue of more than fifty tools, the gain from tool search drops from 25 points on one model to 8.6 on the next, because the unfiltered baseline rises from 49 % to 79.5 %. The margin left by filtering shrank to a third in one generation of models. Any architecture decision taken here has a short shelf life.

The prompt cache trap

Here is what makes a homemade top-K filter a bad idea even if it worked.

Tool definitions do not go just anywhere in the prompt: they go at the beginning. Anthropic documents the order of the cacheable prefix as tools, then system, then messages, with a hierarchy where each level rests on the previous one. And the invalidation rule is explicit: modifying tool definitions, be it names, descriptions or parameters, invalidates the entire cache, and a change at one level invalidates that level and all subsequent ones.

OpenAI says the same and adds a detail: the prefix must remain unchanged, and order counts. The same set of tools served in a different order is a cache miss.

With vLLM serving an open model there is no tool block of its own. The tools parameter is serialised by the chat template inside the first system message, behind the system prompt text. For automatic prefix caching the effect is identical, because it is still near the absolute start of the prompt.

The consequence is the one that matters. A filter that returns a different set of tools on the next turn does not just invalidate the tool block: it invalidates everything behind it, which is the system prompt and the whole conversation, which is exactly the part that grows with the turns. At list prices, a prefix token goes from costing 0.1 times when read from cache to 1.25 times when written. An agent with sixty thousand tokens of stable prefix goes from some six thousand equivalent tokens per turn to some seventy-five thousand, plus the prefill that gets paid again in latency.

The two big providers have separately arrived at the same solution, and it is the opposite of filtering in the prefix. Anthropic excludes deferred tools from the prefix and, when the model discovers one through search, injects it inline inside the conversation: “the prefix stays intact, so prompt caching is preserved”. OpenAI: “all tools are loaded at the end of the model’s context window (…) this allows the cache to be preserved from one request to the next”. Anthropic’s operational recommendation is the stable core pattern: leave the three to five most used tools undeferred.

The closest academic work, from January 2026, states the problem without measuring it and recommends exactly that, keeping a fixed set of reusable general-purpose functions and implementing dynamic capability through code generation.

The July 2026 MCP specification picks up both halves of the matter. Servers “should return the tools from tools/list in a deterministic order to allow caching in the client and improve the hit rate of the model’s prompt cache”. And it adds mandatory ttlMs and cacheScope in listing results, so that the client can freeze the catalogue for a known window instead of re-querying it and propagating any variation to the prompt.

Nobody has publicly measured the cost in euros of this effect. The only attempt I found is a self-published audit of ten thousand turns that puts it at 2.4 % to 3.5 % of cache misses, with non-reproducible methodology. It is a gap in the literature, and the order of magnitude in the previous paragraph comes from applying list prices, not from a measurement.

And now, LiteLLM

With all of the above in mind, the gateway’s levers read differently.

The semantic filter does not act on the MCP endpoint. It is registered as a generic LiteLLM callback, and its only dispatcher is the proxy’s precall hook, which additionally discards anything that is not completion, acompletion or aresponses. The tools/list path does not invoke that hook at any point; there is a comment in the code that admits it in passing, when explaining why the listing’s JWT signature is done separately. An external MCP client connected to /mcp receives the whole catalogue, filter enabled or not.

Lever	Serves external MCP clients	Breaks the prompt cache
Per-server `allowed_tools`	Yes	No, it is static
Name and description overrides	Yes	No, it is static
Selection by route or header	Yes	No, if it is stable per agent
`/mcp/proxy` and virtual tools	Yes	No, the surface is fixed
Semantic filter	No	Yes, it rewrites the block per request

When it does act, the filter has details you need to know before enabling it. It embeds only each tool’s description, with the name as a fallback if it is missing; the parameter schema does not go in. Of the query it embeds only the last user message: on turn twelve of an agent conversation, that might be “yes, go ahead”. The tool embeddings are cached and indexed at start-up; the query’s is computed on every request, with a synchronous call inside a coroutine.

Its failure modes are almost all open, which is the reasonable thing: if the embedding model does not respond, if nothing passes the threshold, if the names do not match the catalogue, it returns all the tools. The exception is context overflow, which fails closed with a 400, and which if it happens while building the index during start-up is memoised and makes all subsequent requests fail until you restart. The defaults are text-embedding-3-small, top_k of 10 and a threshold of 0.3, under litellm_settings.mcp_semantic_tool_filter.

/mcp/proxy does serve external clients, and that is where its real value lies. It replaces the catalogue with three tools with opaque identifiers. How search_tools searches deserves a line, because it is not what you would assume: by default it is neither a regular expression nor a semantic match, it is a keyword counter, how many tokens of the query appear as a substring in the concatenated name and description. It only moves to embeddings if you configure a model in mcp_tool_search. The result cap is hard-coded at five in this mode, and the client cannot ask for more. In exchange, call_tool goes through the same permission checks as a normal call plus a validation of the argument schema that the normal route does not do at that point.

There is a related variant: with mcp_tool_search_enabled in the key’s permissions, the catalogue is replaced by four virtual tools, and there the search one does expose top_k to the client.

The catalogue order is not deterministic, and that breaks the client’s cache without anybody filtering anything. The list of allowed servers comes from iterating a Python set of strings, so with the random hash seed the order differs between processes, between uvicorn workers and between restarts. There is no sorting anywhere in the listing path, and there is no tool cache: every tools/list queries the upstreams live, so the order within each server also depends on what the upstream returns that time. The gateway does not offer today the guarantee that the July specification recommends. The fix, sorting the catalogue before serving it, fits on one line.

Nor is there any pagination towards the client. The catalogue is returned whole, always.

And the lever almost nobody uses is the static one. Every MCP server accepts tool_name_to_display_name and tool_name_to_description, and those overrides really do replace what is sent to the client in tools/list, not just what the administrator sees in the interface. The tools/call routing translates from the new name to the real one before any permission check. With that you can trim a four-hundred-token description written by a third party, rename an ambiguous tool so it does not compete with a similar one, and do it without touching the prompt cache, because it is static and holds for all turns.

It is also the rug pull mitigation left pending from the security section: if the description the model sees is the one the operator wrote, whatever the upstream server changes stops reaching the context. Two limits. They are configured through the database or the management API, not through config.yaml. And the reverse name translation is by exact equality and is not disambiguated between servers, so two servers with the same display name route unstably, made worse by the non-deterministic order of the previous paragraph.

Alongside that, per-server allowed_tools remains the blunt and effective instrument: it filters the listing the client sees, reduces tokens, and is static.

The ladder, in order

Trim. Per-server allowed_tools, plus a per-key allowlist. Cheap, static, does not break the cache and reduces the permission surface at the same time.
Rewrite the descriptions with the overrides. That is where the evidence is, because the description carries weight and the name almost none, and along the way it pins the contract against the rug pull.
Split by route. Each agent to /{server}/mcp or to a tool set, never to the aggregated endpoint. Stable per agent, so the cache survives.
Sort the catalogue before serving it if you control the deployment, while the gateway does not do it.
/mcp/proxy when the catalogue goes past thirty or fifty tools. It is progressive disclosure and it works with external clients, which is more than you can say for the semantic filter.
The semantic filter, only when the one calling the model is LiteLLM. With a generous top_k, knowing that it embeds only the last user message and that context overflow is a closed and sticky failure.
What not to do: a home-grown top-K filter that rewrites the tools array on every turn. It costs the whole prefix and, according to four of the five measured strategies, probably makes selection worse.

The declared cost, which is worth zero

The calculation has four precedence steps: cost set by a post-call hook, per-tool cost in tool_name_to_cost_per_query, server default cost, and 0.0.

Without configuring mcp_server_cost_info, all MCP traffic is accounted at zero and consumes neither key nor team budget.

There are exactly two Prometheus metrics for MCP:

litellm_mcp_tool_calls_total
litellm_mcp_tool_call_spend_metric

Both with the same eight labels: tool name, server name, key hash, key alias, team, team alias, user and end user.

And the second is only incremented if the cost is greater than zero. With the default configuration, that time series never appears in Prometheus. It is not that it is worth zero: it is that it does not exist.

Nor is there a tools/list metric, or MCP latency, or MCP errors, or upstream server health. For that you are left with the generic request metrics.

In the reports, /spend/calculate has no MCP branch: it accepts a model and messages, or a completion response, and it always calls the LLM cost calculation. The per-team report does include MCP calls, grouped by the model column, which for these rows is worth MCP: tool_name. That is: every tool appears as if it were a model, with zero input and output tokens. Only the sessions endpoint separates the two call types explicitly.

Observability, and the trace that gets cut

There are two OpenTelemetry stacks in LiteLLM and which one runs depends on an environment variable.

Without LITELLM_OTEL_V2=true, the old logger runs, and it has no MCP handling: the only appearance of MCP in the whole file is the metadata key in a list. The tool call comes out as a generic litellm_request span with the model set to MCP: name.

With v2 enabled there is a dedicated span, with a dedicated role, client kind and a parent in the proxy’s request span. The span name is tools/call tool-name. The attributes are correct and follow the conventions:

Attribute	Value
`gen_ai.operation.name`	`execute_tool`
`mcp.method.name`	`tools/call`
`mcp.session.id`	MCP session identifier
`gen_ai.tool.name`	Tool name
`gen_ai.tool.call.arguments`	Only with content capture enabled
`gen_ai.tool.call.result`	Only with content capture enabled
`server.address`, `server.port`	From the upstream URL, redacted
`litellm.cost.total`	The cost that is probably worth zero

Content capture is off by default. Without it you see neither the arguments nor the result in the trace.

A note for anyone working with semantic conventions: mcp.tool.name does not exist. The MCP registry has exactly four attributes (mcp.method.name, mcp.session.id, mcp.protocol.version and mcp.resource.uri), all four in development, and the tool name goes in gen_ai.tool.name. LiteLLM gets it right. And the GenAI conventions were extracted into their own repository which as of today has no release at all, so there is no version number to cite.

In Langfuse, the vendor mapper returns an empty dictionary for any span that is not an LLM call. An MCP call appears as a raw span with its attributes, with no native input, output or model fields.

The trace is cut at the gateway

Incoming context is read. The traceparent the client puts in params._meta, following the specification’s propagation proposal, is extracted and turned into a link on the span, never into its parent. The reason is documented in the code: parenting to the remote trace would leave the span hanging off a trace whose root never reaches the backend. The client’s baggage is discarded on purpose to avoid forging identity attributes.

Outgoing context is not propagated. There is no propagator injection call anywhere in the tree. The headers that go out towards the upstream MCP server are built with authentication and the authorised extra headers, and nothing else.

The operational consequence: there is no end-to-end trace. If the upstream MCP server is instrumented, its spans live in another trace and there is no way to correlate them automatically.

Auditing and the conflict with privacy

A tool call leaves a normal spend row, with call type call_mcp_tool, spend equal to the cost per query, model MCP: name, zero tokens in the three token columns, a dedicated mcp_namespaced_tool_name column, and the usual key, team, user and session fields.

And in the metadata column, in JSON, the complete structure of the call: name, arguments, result, server, namespaced name, MCP session identifier, authentication mode and server resource with the URL redacted.

The problem

That structure is written into the metadata column without passing through the privacy switch. The assignment is direct and is not conditioned by the function that governs whether prompts and responses are stored, which does control the messages and response columns.

And the redaction function does not cover it either: it only touches messages and response. A search for MCP in the redaction file returns nothing.

The practical result: an operator who enables turn_off_message_logging for GDPR keeps sending the full arguments of every tool to every logging destination they have configured. To the SIEM, to Langfuse, to S3.

If an argument carries a national ID number, an address, a case number or a medical record, it has been exported.

There is an aggravating factor that does not depend on LiteLLM. The revision of the specification in force introduces an extension that allows mirroring tool arguments into HTTP headers visible to load balancers, proxies and web application firewalls. The specification recommends not marking sensitive parameters that way, and it is a recommendation, and the upstream server decides.

The fit with the ENS

The conflict is real and has a familiar shape: activity logging (op.exp.8) requires the call to be traced and non-repudiable; protection of personal data (mp.info.1) requires that log not to become a secondary repository of personal data with a different purpose. The tool argument is simultaneously the evidence of the action and the data. Redacting it destroys non-repudiation; storing it in the clear creates the repository.

The defensible way out you can build today: a hash of the argument in the audit log, the argument in the clear with encryption (mp.info.3), separate retention and its own access control. The hash sustains non-repudiation and the clear text is only opened under procedure.

There are two other measures this material touches directly. Change management (op.exp.5) because registering an MCP server and, above all, changing the description of an already approved tool are changes to the security configuration. And maintenance and updates (op.exp.4) because, as you can see in the next section, an old version of the gateway is a non-compliance with a name and a number.

Two honesty warnings. The codes follow the numbering of Annex II of RD 311/2022 and you have to check them against the text in force before citing them in a compliance document. And on NIS2: as of the date of this post the directive is still not transposed in Spain, with the draft bill on cybersecurity coordination and governance going through the process and a reasoned opinion from the Commission over the delay. What is enforceable today in the public sector and its suppliers is the ENS.

What is not logged

An administrative gap: registering, modifying and deleting MCP servers generates no audit log. There are three TODO comments in the management code that say so, one of them with an if is_audit_logging_enabled(): pass. In the same deletion block there are two more TODOs about not cleaning up orphaned permissions on keys and teams.

Security

The vulnerability you need to know about

CVE-2026-42271, published on 8 May 2026. Affects LiteLLM from 1.74.2 up to versions prior to 1.83.7. CVSS 3.1 of 8.8.

The POST /mcp-rest/test/connection and POST /mcp-rest/test/tools/list endpoints, which exist to preview an MCP server before saving it, accepted the stdio transport’s command, args and env in the request body. A low-privilege key executed arbitrary commands on the proxy host. It also affects Red Hat OpenShift AI on several branches.

It is the story of this post condensed into one line: the gateway you put in to contain MCP was the hole.

It does not come alone. The 1.83 branch concentrates three more serious ones:

CVE	Component	CVSS	Fixed in
`CVE-2026-42208`	SQL injection in key validation, with no prior authentication	9.8	1.83.7
`CVE-2026-35030`	OIDC userinfo cache keyed on `token[:20]`, collision and impersonation	9.1	1.83.0
`CVE-2026-40217`	Remote execution through bytecode rewriting in the guardrails test endpoint	8.8	no version recorded

Plus two privilege escalations fixed in 1.83.10 and 1.83.14.

The operational conclusion is short: a deployment below 1.83.14 is exposed to remote execution or to an unauthenticated SQL injection. The current branch is 1.102.0.

And a note for context: the whole MCP ecosystem has the same pattern. The unauthenticated remote execution in MCP Inspector, the command injection in mcp-remote when connecting to an untrusted server, DNS rebinding disabled by default in the Python and TypeScript SDKs until late 2025, the directory escapes in the reference servers. Connecting to an untrusted MCP server compromises the client, not just the other way round.

The rug pull nobody covers

Documented since April 2025: a server can change a tool’s description after the client has approved it. The description is what the model reads to decide when and how to use it, so changing it is changing the behaviour without asking for permission again.

The specification in force does not address it. It defines list change notification and cache freshness fields, which are recency mechanisms, not integrity ones. The closest normative warning is that clients must treat tool annotations as untrusted unless they come from trusted servers.

LiteLLM does not cover it either. The only “pinning” in the code is of the configuration’s server identifier, so that it does not change when you edit the YAML. There is no hash or comparison of the description or the input schema between successive listings. A search for related terms in the MCP module: nothing functional.

The control exists outside the gateway. mcp-scan, from the same researchers who documented the attack, implements description hash pinning precisely to detect this.

In ENS terms it is an unauthorised change to the security configuration that today goes undetected. And the home-made fix fits in a cron job: store the hash of the description and schema of every approved tool, compare against tools/list periodically, alert on the difference.

Three more holes in the code

No URL validation towards the upstream. A new server’s url field has no validator. The SSRF protection utilities exist in the tree and are used in OAuth discovery and in downloading OpenAPI specifications, but not in the egress of tools/call. A server pointing at a private range or at the cloud metadata IP is accepted as is.

The stdio transport is local execution on the proxy host. There is a command allowlist: npx, uvx, python, python3, node, docker, deno, extendable through an environment variable. The code’s own comment admits the residual risk: the permitted runtimes can execute code through arguments. With docker and npx in there, it is de facto arbitrary execution for any proxy administrator.

Two server modes skip the gateway’s authentication. Pass-through and authentication delegation to the upstream completely omit virtual key validation. They are well hardened (fail-closed if the target is mixed or unresolvable, strict comparison against truthy values, explicit blocking of the client credentials flow so as not to lend out the proxy’s service account), and the result is still that those servers have no gateway access control.

The limit that truncates in silence

The tools/list pagination stops and returns what it has accumulated in three cases: repeated cursor, one thousand pages, or expiry of a global deadline. The docstring declares it: a slow or faulty upstream produces a partial catalogue instead of an error.

The first two log a warning. The third, the deadline, exits without logging anything at all. A slow server makes part of its tools disappear from the catalogue with no trace left behind.

Correction on the slot leak

In the previous post I took issue 34534 at face value, according to which every MCP tool call acquires a max_parallel_requests slot and does not release it. Tracing the 1.102.0 code, that diagnosis no longer holds: the release path exists, on both success and failure, and the limiter is registered as a litellm callback and not just as a proxy hook.

With one honest caveat: I found no regression test covering the full cycle for MCP, and the definitive confirmation is a real proxy with max_parallel_requests: 2 and five MCP calls in a row. If anybody reproduces it today, I would like to know.

The specification moved underneath

The MCP revision in force is 2026-07-28, published on 28 July 2026, and in between there was another one, 2025-11-25. The changes in the latest one are not cosmetic:

Protocol sessions and the session header are removed. Cross-request state becomes an explicit identifier in the tool arguments.
The initialisation handshake is removed. Every request carries version and capabilities in _meta. MCP becomes stateless.
server/discover appears as a mandatory call.
Elicitation changes shape: out go server-initiated requests, in comes a multi-round pattern where the server returns an “input required” result and the client retries with the answers.
ping, logging/setLevel and the roots change notification are removed. SSE stream resumption is removed.
Standard HTTP headers are mandatory on POST, which lets a gateway or a web application firewall decide without parsing the JSON.
On authorisation: mandatory issuer validation in the client, and dynamic client registration is deprecated in favour of client identifier metadata documents.
Roots, sampling and logging are deprecated, with a minimum window of twelve months.

LiteLLM 1.102.0 advertises 2025-06-18. Its version enumeration has three values and none of them is later than that date. The literal is sent in the initialize against the upstream.

One nuance that is not entirely bad: the version the gateway advertises to its clients is not hard-coded in LiteLLM, the SDK negotiates it. And there is partial implementation of the intermediate revision, because the elicitation and sampling handlers reference it in their docstrings. That is: partial implementation of one revision while advertising an earlier one.

In practical interoperability it does not hurt yet, because the client ecosystem is still mostly on the 2025 revisions. It hurts in planning: July’s stateless redesign invalidates the gateway’s session model, and that is work ahead.

Two ecosystem notes for anyone choosing. There are clients that speak remote streamable HTTP natively (Claude and Claude Code, ChatGPT with OAuth and dynamic registration, VS Code with Copilot, Cursor, Zed, Kiro) and others that still demand stdio or a local bridge with mcp-remote, among them Windsurf, Cline and Continue.

Tool execution from the proxy itself

Besides serving MCP outwards, the proxy can consume it itself. It is enabled with an mcp block in the body, with server_url equal to the litellm_proxy sentinel, and it works both on /v1/responses and on /chat/completions.

The flow: it separates the gateway’s tools, lists them, filters by allowed, deduplicates, translates them into OpenAI function format and concatenates them. It calls the model. If there are tool calls and auto-execution is permitted, it runs them against the MCP servers. It builds the follow-up and makes one second call.

Two limits you need to know before designing on top of this.

The loop is a single hop. There is no multi-step iteration. The calls from the first response are executed and the follow-up is returned. A plan that chains tools requires the client to call again.

Auto-execution fails closed and as a block. It requires all MCP references to have approval set to “never”; a single one requiring approval disables auto-execution for the whole request.

And a third one, which is the one that bites: the multi-turn state of /v1/responses is rehydrated from the spend table. The query is literal, it looks up the session of the previous request_id and retrieves all the rows of that session ordered by time.

With disable_spend_logs: true nothing is written, the query comes out empty and the history is lost in silence, with no 4xx error. The code itself acknowledges it: it does not expect retries because deployments that do not write spend logs have nothing to wait for. It is a coupling between a performance option and a conversation feature that nobody expects to find.

Health and day-to-day operation

Health checks exist, they are on demand and they are not periodic. GET /v1/mcp/server/health accepts repeated identifiers and returns per-server status. The implementation opens a client and runs an empty operation inside the session, with a ten-second timeout.

It skips the check entirely if the server requires per-user authentication, and those always return unknown status.

The surprising part: the status, last check and error columns have existed in the database since a May 2025 migration, and the check function returns an object without writing to the database. Status is recalculated on every request. There is no periodic MCP health job.

When an upstream server is down, the behaviour is to degrade and not block. The listing fans out in parallel and each failing server contributes an empty list plus a result classified into six categories. Those results reach the client in the response’s _meta under a vendor key, without filtering the upstream’s text or URL. The reason for the design is in the code: an empty contribution with no signal makes a broken upstream indistinguishable from a healthy server with no tools.

There is no cache of the previous list. A server that is down disappears from that turn’s tools.

On registering and deregistering without restarting, there are two worlds. Database servers can be created, edited and deleted through the API, and every operation reloads the registry with an atomic swap. Propagation between replicas goes through Redis publication on the configuration change channel, if there is Redis, and through polling every 30 seconds if there is not.

Servers declared in config.yaml are loaded once, at start-up. There is no re-read. Changing them requires a restart.

And there is a precedence trap between the two worlds, with two different warnings in the code. A database row with the same identifier as a configuration entry hides the configuration one entirely. And the other way round, a configuration identifier that matches the name or alias of a database server captures its permissions, because identifiers are resolved before names. Both cases emit a log warning, once.

A hardened `config.yaml`

general_settings:
 # Access is not open by default, but this closes the empty-key
 # inheritance towards the team, which is the one that surprises people.
 require_key_mcp_access_defined: true
 require_end_user_mcp_access_defined: true
 # Without this, allow_all_keys overrides the key's explicit scope.
 mcp_allow_all_keys_respects_mcp_scope: true

litellm_settings:
 # Does not cover MCP arguments. See the auditing section.
 turn_off_message_logging: true
 callbacks: ["langfuse_otel"]

mcp_servers:
 inventario:
 url: https://mcp-inventario.interna.svc/mcp
 transport: http
 auth_type: bearer_token
 auth_value: os.environ/MCP_INVENTARIO_TOKEN
 # Explicit allowlist. Also enforced on tools/call.
 allowed_tools:
 - buscar_articulo
 - consultar_stock
 # Never true on a server with data.
 allow_all_keys: false
 access_groups: ["operaciones"]
 timeout: 20
 max_concurrent_requests: 8
 mcp_info:
 description: "Inventario de almacen, solo lectura"
 # Without this, MCP spend is zero and its metric does not exist.
 mcp_server_cost_info:
 default_cost_per_query: 0.0005
 tool_name_to_cost_per_query:
 consultar_stock: 0.0002

And in the process environment:

# Without this there is no MCP span, only a generic litellm_request.
LITELLM_OTEL_V2=true
# Full block hashes, not truncated, if correlating
# with engine events.
LITELLM_MCP_CLIENT_TIMEOUT=45
LITELLM_MCP_TOOL_LISTING_TIMEOUT=20

For clients, the rule is not to use the aggregated endpoint. Each agent points at /{server}/mcp or at a tool set, or at the three-tool proxy mode if the catalogue is large.

Checklist

Check the version. Below 1.83.14 there is remote execution and an unauthenticated SQL injection with an assigned CVE.
Inventory which servers have allow_all_keys and enable the setting that makes it respect the key’s scope.
Audit the access groups separately, because they are additive on top of the key and team ceiling.
Declare in writing the fail-open behaviour on tool permission resolution errors.
Measure the real cost: number of tools per server from the listing row, and tools block tokens from the stored request body.
Choose a catalogue strategy before connecting the third server: three-tool proxy mode, semantic filter, or selection by route. Not the aggregated endpoint.
Declare mcp_server_cost_info even with a token value, or the spend metric will not exist.
Enable the OTel v2 logger, and decide deliberately whether to enable content capture.
Assume the trace is cut at the gateway and plan correlation with the upstream by other means.
Treat the spend table’s metadata column as a personal data repository: encryption, its own retention and separate access control.
Set up the rug pull check, because nobody does it: hash of the description and schema of every approved tool, periodic comparison against the listing.
Restrict egress towards MCP servers at the network level, because the gateway does not validate the destination URL.
Do not enable the stdio transport unless you need it, and if you do, review what is on the command allowlist.
If you use /v1/responses with multi-turn state, do not enable disable_spend_logs.

Traps and things that are not what they seem

MCP access is not open by default in 1.102.0. I got that wrong in the previous post. What opens things up is per-server allow_all_keys.
allow_all_keys overrides the key’s explicit scope unless you enable a setting that ships disabled.
require_key_mcp_access_defined only closes key-to-team inheritance. Access group grants remain additive.
On an indeterminate failure resolving tool permissions, the code fails open for keys and JWTs.
The default cost of an MCP call is 0.0, and the spend metric is only emitted if the cost is greater than zero, so the series does not exist.
MCP calls appear in the per-team report as if they were models, named MCP: tool and with zero tokens.
The OTel logger with MCP support is off by default. Without the environment variable there is no MCP span.
Trace context is not propagated towards the upstream MCP server. There is no end-to-end trace.
mcp.tool.name does not exist in the semantic conventions. The name goes in gen_ai.tool.name.
Message redaction does not cover tool arguments. They are written in the clear into the spend table.
Registering, modifying and deleting MCP servers generates no audit log. There are three TODOs in the code.
The semantic tool filter is not applied on tools/list. Only on /chat/completions and /v1/responses.
The catalogue order is not deterministic, because it comes from iterating a set of strings. It breaks the client’s prompt cache even though nobody filters anything.
search_tools in proxy mode counts keywords by default, it uses neither regular expressions nor embeddings, and its cap of five results is hard-coded.
Description overrides really do replace what the client sees, and they are the only catalogue lever that does not break the cache. They are only configurable through the database or the API.
spec_version no longer exists in the configuration schema.
/mcp/sse does not use the SSE transport, and the messages endpoint its object advertises is dead code.
Listing pagination truncates in silence when the deadline expires, without leaving a single log line.
A database row hides a configuration entry with the same identifier, and the other way round a configuration identifier can capture the permissions of a database server.
Servers declared in config.yaml require a restart. Only the database ones reload hot.
The health check does not write its result to the database even though the columns exist, and there is no periodic job.
The gateway does not validate the upstream MCP server’s URL. The anti-SSRF utilities exist and are not used on that path.
docker and npx are on the stdio command allowlist.
The /v1/responses tool loop is a single hop, and disable_spend_logs: true breaks its multi-turn behaviour with no error.
LiteLLM advertises the June 2025 revision of the protocol, two behind the one in force.

Closing

There is a thread running through the six posts in this track that is more visible here than anywhere else. The gateway is chosen for one job and ends up doing five, and each new job arrives with its own defaults, which are almost never the ones you would have chosen.

In the case of MCP the asymmetry is twofold. On one side, the part that looks dangerous is better built than you would assume: access control is enforced on execution and not just on the listing, the hierarchy is built out of intersections, header forwarding is an allowlist, and default access is closed, contrary to what I myself wrote two days ago. On the other, the part nobody looks at is worse: tool arguments come out in the clear bypassing the privacy switch, spend is worth zero and its metric never gets to exist, the trace is cut, and a change to the description of an approved tool goes undetected by anybody in the whole chain, neither the specification nor the gateway.

The architecture decision that comes out of this is that the MCP door has to be treated as what it is, an interconnection of systems with third parties, and not as one more function of the LLM proxy. That means its own inventory, formal registration, change control over every tool’s description, network isolation towards the upstream and a log designed knowing that it is going to contain personal data.

And it means accepting that the cost you really pay for connecting fifteen MCP servers is in no column of the spend table. It is spread across the prompt_tokens of every model call, on every turn, and across the accuracy you lose when the catalogue is too large for the model to choose well. That number can be computed with what the gateway already stores. The first step is wanting to compute it.

Sources

LiteLLM, MCP Gateway: https://docs.litellm.ai/docs/mcp.
LiteLLM, código: litellm/proxy/_experimental/mcp_server/server.py, mcp_server_manager.py, rest_endpoints.py, auth/user_api_key_auth_mcp.py, cost_calculator.py, faults/list_outcomes.py, litellm/proxy/management_endpoints/mcp_management_endpoints.py, litellm/proxy/spend_tracking/spend_tracking_utils.py, litellm/litellm_core_utils/redact_messages.py, litellm/integrations/otel/, litellm/responses/litellm_completion_transformation/session_handler.py: https://github.com/BerriAI/litellm.
LiteLLM, incidencia 34534, fuga de slot de concurrencia en llamadas MCP: https://github.com/BerriAI/litellm/issues/34534.
NVD, CVE-2026-42271, ejecución de comandos por los endpoints de prueba de MCP: https://nvd.nist.gov/vuln/detail/CVE-2026-42271.
NVD, CVE-2026-42208, inyección SQL sin autenticación en la validación de clave: https://nvd.nist.gov/vuln/detail/CVE-2026-42208.
NVD, CVE-2026-35030, colisión de clave de caché de userinfo OIDC: https://nvd.nist.gov/vuln/detail/CVE-2026-35030.
NVD, CVE-2025-49596, ejecución remota en MCP Inspector: https://nvd.nist.gov/vuln/detail/CVE-2025-49596.
NVD, CVE-2025-6514, inyección de comandos en mcp-remote: https://nvd.nist.gov/vuln/detail/CVE-2025-6514.
NVD, CVE-2025-66416, protección de DNS rebinding desactivada por defecto en el SDK de Python: https://nvd.nist.gov/vuln/detail/CVE-2025-66416.
Invariant Labs, MCP Security Notification: Tool Poisoning Attacks (tool poisoning, rug pull, shadowing): https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks.
Invariant Labs, Introducing mcp-scan (fijado de herramientas por hash): https://invariantlabs.ai/blog/introducing-mcp-scan.
Model Context Protocol, changelog de la revisión 2026-07-28: https://modelcontextprotocol.io/specification/2026-07-28/changelog.
Model Context Protocol, changelog de la revisión 2025-11-25: https://modelcontextprotocol.io/specification/2025-11-25/changelog.
Model Context Protocol, Security Best Practices (confused deputy, indicadores de recurso, validación de audiencia): https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices.
NSA, Model Context Protocol: Security Design Considerations for AI-Driven Automation, mayo de 2026: https://media.defense.gov/2026/Jun/02/2003943289/-1/-1/0/CSI_MCP_SECURITY.PDF.
CISA y agencias aliadas, Careful Adoption of Agentic AI Services, mayo de 2026: https://www.cisa.gov/resources-tools/resources/careful-adoption-agentic-ai-services.
Anthropic, Advanced tool use (coste en tokens de las definiciones, búsqueda de herramientas, precisión de selección): https://www.anthropic.com/engineering/advanced-tool-use.
Anthropic, Code execution with MCP: https://www.anthropic.com/engineering/code-execution-with-mcp.
Anthropic, Prompt caching (jerarquía tools → system → messages e invalidación): https://platform.claude.com/docs/en/build-with-claude/prompt-caching.
Anthropic, Tool search tool (herramientas diferidas fuera del prefijo, umbral de 30 a 50 herramientas): https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool.
OpenAI, Prompt caching (el orden de las herramientas cuenta): https://developers.openai.com/api/docs/guides/prompt-caching.
OpenAI, Tool search (las herramientas descubiertas se cargan al final del contexto): https://developers.openai.com/api/docs/guides/tools-tool-search.
vLLM, Automatic Prefix Caching: https://docs.vllm.ai/en/latest/features/automatic_prefix_caching.html.
Microsoft, Use tools in chat (límite de 128 herramientas por petición en VS Code): https://code.visualstudio.com/docs/copilot/agents/agent-tools.
RAG-MCP, prueba de estrés de 1 a 11.100 servidores candidatos, mayo de 2025: https://arxiv.org/abs/2505.03275.
Benchmarking the Benchmarks, desalineación del 18,5 % entre etiqueta y realidad, junio de 2026: https://arxiv.org/html/2607.02577v1.
MCP-Atlas, taxonomía de fallos sobre 220 herramientas y veinte modelos, febrero de 2026: https://arxiv.org/html/2602.00933v3.
BiasBusters, sesgo de selección entre herramientas equivalentes y peso de la descripción frente al nombre: https://arxiv.org/html/2510.00307.
MCP Tool Descriptions Are Smelly, auditoría de 856 herramientas de 103 servidores, febrero de 2026: https://arxiv.org/html/2602.14878v1.
ToolMenuBench, seis estrategias de filtrado y 26.460 ejecuciones, junio de 2026: https://arxiv.org/html/2606.15508.
Retrieval Models Aren’t Tool-Savvy (ToolRet), corpus de 43.000 herramientas, marzo de 2025: https://arxiv.org/abs/2503.01763.
Tools Are Not Islands, brecha entre Recall@3 y conjunto completo, julio de 2026: https://arxiv.org/html/2607.25718.
ToolFlood, saturación adversaria de la capa de recuperación, marzo de 2026: https://arxiv.org/html/2603.13950.
Scores Are Not Decisions, el K óptimo como función del coste, julio de 2026: https://arxiv.org/html/2607.27083v1.
Don’t Break the Cache, caché de prompts en tareas agénticas de horizonte largo, enero de 2026: https://arxiv.org/html/2601.06007v2.
How Many Tools Should an LLM Agent See? A Chance-Corrected Answer, mayo de 2026: https://arxiv.org/html/2605.24660v1.
Semantic Tool Discovery for LLMs, marzo de 2026: https://arxiv.org/abs/2603.20313.
OpenTelemetry, convenciones semánticas de GenAI y MCP: https://github.com/open-telemetry/semantic-conventions-genai.
Boletín Oficial del Estado, Real Decreto 311/2022, Esquema Nacional de Seguridad: https://www.boe.es/buscar/act.php?id=BOE-A-2022-7191.
IBM ContextForge, gateway y registro MCP: https://github.com/IBM/mcp-context-forge.
Docker MCP Gateway: https://github.com/docker/mcp-gateway.
agentgateway: https://github.com/agentgateway/agentgateway.

Virtual keys, budgets and limits in LiteLLM: the layer that decides who gets the GPU, and the four things the documentation gets wrong

Tue, 08 Sep 2026 07:30:00 +0200

Third article in the operational track of the control layer. The pair with Langfuse covered observability, and day 2 of the proxy covered availability. Here it is governance: who can call, which model, how much and on what budget. The economic model behind those figures is in FinOps and multi-tenancy with LiteLLM.

TL;DR

On a platform running on your own GPUs there is no provider invoice to put consumption in order. Capacity is fixed, known and shared, so someone has to impose the allocation, and that someone is the gateway.

The hierarchy has six levels: organisation, team, team member, internal user, key and end customer, plus the project and tag scopes. Each level’s budgets are evaluated independently and all of them have to pass. They neither add up nor cancel each other out, with one exception.

The exception is in the code and it is the most important governance trap in the system. A key that belongs to a team suppresses the check of its owner’s personal budget, unless apply_user_budget_to_team_keys is enabled. A user with a hundred-euro cap who works with their team’s key spends whatever the team allows.

Rotating a key preserves its spend. /key/regenerate does an UPDATE on the same row changing the hash, so spend, max_budget and the budget window remain intact. It accepts a grace period, stored in a table of its own, and if the period’s format is wrong it is ignored without blocking anything.

The v3 limiter is already the default in 1.100.0, and you go back to the previous one with an environment variable. Its window is sliding, sixty seconds, anchored to the first request, and the counters are incremented with Lua scripts inside Redis using Redis’s own timestamp to close the race between replicas.

And four points where the official documentation does not match the code, verified against tag v1.100.0: an exhausted budget returns 429, not 400; the audited actions are six, not three; /key/info and /key/list are GET, not POST; and the v3 limiter carries a docstring saying it is not production-ready while it is the one loaded by default.

You are here: the gateway as an administrative boundary

Without this layer, an in-house inference platform has a single mode of operation: whoever knows the URL consumes. It works while there is one team. It stops working the day there are three, or the day someone connects an agent that fires twenty calls per interaction and wrecks everyone else’s time to first token.

The two questions this layer answers are different and have to be kept apart. The capacity one is instantaneous: how many requests and how many tokens per minute each consumer can push, so the fleet does not saturate and latency stays within the service agreement. The cost one is cumulative: how much each consumer has spent this month against its budget. They are configured in the same place, applied at different moments and fail in different ways.

The analogy: the building’s key ring

An office building hands out keys at three levels. The master opens everything and the building manager has it. The floor keys open a whole floor and each tenant company has one. And the office keys open one office.

Three properties of that system are the ones that matter here. A key is replaced without changing the lock of the whole building, and the tenant keeps their parking space and their electricity meter: that is rotation preserving the spend. A lost key is cancelled from the central panel without collecting anything physical: that is blocking from the interface. And the record of who took out each key and when lives in a separate book, which is what you show an inspector: that is the audit table.

The analogy breaks at one point, and that point is where this system’s governance flaw lives. In the building, having a floor key does not cancel the office’s consumption limit. In LiteLLM, it does.

The hierarchy, and the line that breaks it

The levels and their management endpoints:

Level	Endpoints	Budget
Organisation	`/organization/new`, `/organization/member_add`, …	`max_budget`
Team	`/team/new`, `/team/member_add`, `/team/block`, …	`max_budget`
Team member	`/team/member_add` with `max_budget_in_team`	Its own row in the budgets table
Internal user	`/user/new`, `/user/update`, …	`max_budget`
Key	`/key/generate`, `/key/update`, …	`max_budget`, `soft_budget`
End customer	`/customer/new`, and the parallel `/end_user/*` set	`max_budget`

The default behaviour is the right one for a multi-tenant platform: each scope carries its own counter and the check of each one is independent of the rest. A request passes if all of them pass.

And then there is this condition, which lives in the authorisation checks:

is_team_key = team_object is not None and team_object.team_id is not None
if is_team_key and general_settings.get("apply_user_budget_to_team_keys") is not True:
 return

Translated: when the key belongs to a team, the check of the budget of the user who owns that key returns without evaluating anything. The personal cap exists in the database, is visible in the interface, and is not applied.

For a deployment where personal budgets are decorative, it makes no difference. For one where the per-person cap is the control that was shown to someone as a guarantee that a user cannot overrun the platform, it is a hole. The line that closes it is one:

general_settings:
 apply_user_budget_to_team_keys: true

Virtual keys: the complete life cycle

The endpoints all exist and some of them are not where you expect:

Route	Method	What for
`/key/generate`	POST	Create
`/key/update`	POST	Modify
`/key/info`	GET	Query one
`/key/list`	GET	List
`/key/delete`	POST	Delete
`/key/regenerate`	POST	Rotate
`/key/block`, `/key/unblock`	POST	Suspend and reactivate
`/key/health`	POST	Check that key’s callbacks

The two marked in bold are GET, and several examples in the documentation suggest otherwise. /key/health is not what its name suggests either: it does not validate the key or its budget, it checks the logging callbacks associated with it.

There are many creation parameters, and these are the ones that govern:

curl -X POST 'https://gateway.interno/key/generate' \
 -H 'Authorization: Bearer sk-...' \
 -d '{
 "key_alias": "equipo-datos-notebooks",
 "team_id": "t-datos",
 "models": ["llama-70b", "qwen-30b"],
 "max_budget": 250,
 "budget_duration": "30d",
 "tpm_limit": 400000,
 "rpm_limit": 600,
 "max_parallel_requests": 8,
 "duration": "90d",
 "tags": ["produccion", "notebooks"]
 }'

Alongside those there are controls that are rarely used and solve specific problems: model_max_budget to set a per-model cap within the same key, model_tpm_limit and model_rpm_limit for the same thing with capacity, enforced_params to require certain keys to always arrive with given fields, allowed_routes so an application key cannot touch the management endpoints, and blocked to be born suspended.

How they are stored

A key’s hash is a single-pass hexadecimal SHA-256, with no salt and no derivation function:

hashed_token = hashlib.sha256(token.encode()).hexdigest()

The row lives in LiteLLM_VerificationToken, with the hash as primary key, and it contains the accumulated spend, the limits, the expiry, the allowed models and the rest of the configuration.

Two consequences to be clear about before an audit. The first is that this hash is not designed to resist a dictionary attack against the database, and the code itself acknowledges it in a comment about encryption key derivation, where it admits that a single-pass unsalted SHA-256 is not a derivation function and that moving to HKDF would be more defensible in an audit. The real mitigation is that virtual keys are generated with enough entropy, not the strength of the hash. The second is that LITELLM_SALT_KEY plays no part here: that variable encrypts the stored provider credentials, not the virtual keys.

There is a trap around that variable that takes down a whole deployment. If it is not defined, it falls back to the master key. Rotating LITELLM_MASTER_KEY without having first set your own LITELLM_SALT_KEY leaves every stored provider credential unreadable, and the failure does not block: it logs an error and returns null, so the symptom shows up as models that stop authenticating with no explanation. Setting LITELLM_SALT_KEY on day one, and never touching it, is one of the things that saves the most grief.

Rotation

/key/regenerate does not create a new key and delete the old one. It updates the same row changing the hash, so the accumulated spend, the maximum budget and the reset window are preserved. For a monthly chargeback this is exactly what you want: rotating mid-month does not zero the counter.

It also accepts a grace period, so the old key remains valid while consumers update:

curl -X POST 'https://gateway.interno/key/sk-vieja/regenerate' \
 -H 'Authorization: Bearer sk-...' \
 -d '{"grace_period": "24h"}'

The old hash is stored in a separate table with its revocation date. Without that parameter, revocation is immediate, and the default value can be set with LITELLM_KEY_ROTATION_GRACE_PERIOD.

A detail with teeth: if the period’s format is wrong, the system logs a warning and continues with no grace period. The rotation completes, the old key dies on the spot, and all that is left is a log line. In an automated rotation procedure, that combination of “carry on” and “warn in the log” is what produces the outage at three in the morning.

What exactly happens when a budget runs out

The code raises BudgetExceededError with status 429. The documentation says 400 in one place, and there the code wins. Its being a 429 has a practical implication: OpenAI clients retry automatically on a 429, so an exhausted budget turns into a retry storm against a gateway that is going to keep rejecting. Internal clients should distinguish the reason, which travels in the message.

The messages are templates and state the scope, the spend and the cap:

Budget has been exceeded! Key=<clave> Current cost: <gasto>, Max budget: <tope>
Budget has been exceeded! Team=<equipo> Current cost: <gasto>, Max budget: <tope>
ExceededBudget: User=<usuario> over budget. Spend=<gasto>, Budget=<tope>
ExceededBudget: End User=<cliente> over budget. Spend=<gasto>, Budget=<tope>
Budget has been exceeded! Organization=<org> ...
Budget has been exceeded! Tag=<etiqueta> ...

Two clarifications about the comparison. It is spend >= cap, with the equals sign included, so landing exactly on the cap already blocks. And the soft budget, soft_budget, blocks nothing: it only writes a log line when it is crossed. It serves to warn, not to contain, and building an alert on top of it is the right way to use it.

The rest of the rejections, with their codes:

Situation	Code	Behaviour
Budget exhausted	429	Message with scope, spend and cap
Expired key	401	It also deletes the cache entry, so the expiry takes effect across the whole fleet without waiting for the TTL
Model not allowed	403	Different error type depending on the scope: key, team, user, organisation or project
Blocked key	Generic exception	`Key is blocked. Update via /key/unblock if you're an admin.`

The last row is an inconsistency in the project worth knowing about: blocking raises an exception with no explicit type or code, while expiry and model access do carry them. Any alert that discriminates by error type will not see blocks the way it sees the rest.

A useful note about allowed models: the check accepts both the alias and the underlying model, so a key authorised for llama-70b can call it by its alias or by its real name with no additional configuration.

Capacity limits: the v3 limiter

This is the most significant silent change of the year in this layer. In 1.100.0, the limiter loaded by default is the third version. Going back to the previous one has to be asked for explicitly:

LEGACY_MULTI_INSTANCE_RATE_LIMITING=true

There is no flag to turn it on, only to turn it off. And it carries a contradiction worth knowing before trusting it: the file itself still opens with a comment saying it is under development and not production-ready, while it is the one running. The design is avowedly inspired by Envoy’s.

The window is sliding and lasts sixty seconds, configurable with LITELLM_RATE_LIMIT_WINDOW_SIZE. It is not an exact rolling log nor a clock-aligned window: it anchors to the first request and resets once the window size has elapsed from that moment. For one-minute limits, the difference from a calendar window shows up at the edges and rarely matters.

What does matter is Redis. The counters are incremented with Lua scripts executed inside Redis, using Redis’s own timestamp and not the pod’s, precisely so window resets are deterministic across replicas and to close the race between checking and counting. Without Redis, each pod counts on its own and the effective limit is multiplied by the number of pods. A limit of 600 requests per minute with five replicas is a limit of 3,000.

There is an inherent imprecision in the token limits that Redis does not solve. The number of output tokens is not known until the response finishes, so the limiter counts with an estimate before the call and reconciles afterwards. The possible excess is, per in-flight request, the difference between the estimate and the real figure. With high concurrency and long responses, that allows the cap to be exceeded within a window. To protect the fleet, the concurrent request limit (max_parallel_requests) is a more direct instrument than tokens per minute.

What the client sees

When limited, a 429 with the message giving the scope, the current limit, what is left and when it resets. And three headers: retry-after with the window size, that is 60 by default, plus rate_limit_type and reset_at.

On the success path, the informational headers use a nested format of their own:

x-ratelimit-api_key-remaining-requests
x-ratelimit-api_key-limit-tokens
x-ratelimit-team-remaining-requests

They are not the standard names x-ratelimit-limit-requests that OpenAI and compatibles emit, so a client expecting the usual format will find nothing. There is also an open issue about these headers being lost on streaming responses, which is most of an assistant’s traffic.

Identity: beyond the static key

Handing out keys by hand works with three teams and stops working with thirty. The two routes for connecting the gateway to corporate identity:

JWT. It is enabled with enable_jwt_auth and configured with the litellm_jwtauth block, which maps token fields to LiteLLM entities: the team comes from team_id_jwt_field, the user from user_id_jwt_field, the organisation from org_id_jwt_field. It supports dot notation for nested claims, automatic creation of users and teams with user_id_upsert and team_id_upsert, role-based access control with enforce_rbac, per-team model restriction with enforce_team_based_model_access, and several issuers at once. The issuer’s public key is cached with a TTL of 600 seconds by default.

general_settings:
 enable_jwt_auth: true
 litellm_jwtauth:
 team_id_jwt_field: "groups"
 user_id_jwt_field: "sub"
 user_email_jwt_field: "email"
 enforce_rbac: true
 enforce_team_based_model_access: true
 team_id_upsert: true

OIDC for the admin interface. With Keycloak you use the generic provider, and the variables are PROXY_BASE_URL, GENERIC_CLIENT_ID, GENERIC_CLIENT_SECRET, GENERIC_AUTHORIZATION_ENDPOINT, GENERIC_TOKEN_ENDPOINT, GENERIC_USERINFO_ENDPOINT, plus a set of attributes to map the identifier, the email, the name and the role, and GENERIC_ROLE_MAPPINGS_* to translate Keycloak groups into LiteLLM roles. Login is rate-limited and sessions have a TTL of their own.

For automatic provisioning there is SCIM in the enterprise version, with base /scim/v2, and deprovisioning a user blocks their keys and takes them out of the authentication cache. That part is not in the open tree, so it cannot be verified against the code.

This fits with the identity work already covered in hardening and secrets of the sovereign stack and in the article on MCP authentication with Keycloak, which uses the same issuer.

Audit: what gets recorded

The table is LiteLLM_AuditLog and its columns are what you would expect from a change log:

id, updated_at, changed_by, changed_by_api_key,
action, table_name, object_id, before_value, updated_values

It stores the previous value and the new one, and attributes the change to an actor and to the key it was made with.

Three clarifications the documentation does not capture well.

The actions are six, in the past tense: created, updated, deleted, blocked, unblocked and rotated. The documentation mentions three. That blocking, unblocking and rotation are actions in their own right is exactly what is needed to reconstruct a credential’s life cycle for an auditor.

The scope is wider than advertised. Besides teams, users, keys and models, changes to the proxy configuration and to the SSO configuration are audited. A change of identity issuer is recorded.

The default depends on the licence. The resolution order is litellm_settings.store_audit_logs, then the variable LITELLM_STORE_AUDIT_LOGS, and if neither is set, it stays enabled in enterprise and disabled in the open version. An OSS deployment that assumes there is an audit trail does not have one:

litellm_settings:
 store_audit_logs: true

Two more pieces for a serious chain of evidence. The actor attribution can be passed with the LiteLLM-Changed-By header, and its use is restricted by the key’s or the team’s configuration, so any caller cannot forge it. And the events can be shipped out with audit_log_callbacks and its S3 parameters, which is what allows depositing them in an immutable store with object lock.

That last part is what turns the record into evidence. The Postgres table is mutable by anyone with database access, and as of September 2026 it has no indexes, so querying it by date range over a long history will not be comfortable either.

What this demonstrates to an auditor, and what it does not

This is the part that decides whether the setup is good enough for a regulated customer. With everything above configured, the platform sustains without difficulty:

Access control via corporate identity, with onboarding and offboarding in the identity provider and not in the gateway, and with the role determining which models are reachable. Segregation between tenants, with independent counters per organisation, team and person. Traceability of administrative changes, with actor, time, previous value and new value, exportable to an immutable store. And demonstrable consumption limits, with the evidence of the rejection in the spend log.

What it does not cover, and has to be solved elsewhere:

The record of the interactions is not this. The audit table records configuration changes, not model calls. The calls are in the spend log and in the traces, and traces are best-effort, which is the discussion in the first article in the series.

The integrity of the record is not something Postgres provides. Without export to immutable storage, the evidence is only as strong as the database permissions.

The content of the prompts is a separate problem, with its own personal-data treatment and its own decision about whether it is stored, masked or not logged at all.

And a warning about the control that tends to be shown first: while apply_user_budget_to_team_keys is not enabled, the per-person cap is not being applied to team keys. Showing that field in the interface as proof of a control that is not executed is the kind of finding a competent auditor discovers. The complete control mapping is in ENS, ISO 42001 and the EU AI Act.

Checklist

apply_user_budget_to_team_keys: true if personal budgets have to be enforced.
LITELLM_SALT_KEY set on day one, different from the master key and never rotated lightly.
store_audit_logs: true explicitly, without trusting the default.
audit_log_callbacks towards an immutable store if an audit has to be sustained.
Redis mandatory if there is more than one replica, or the limits get multiplied by the number of pods.
max_parallel_requests per key, on top of the per-minute limits, to protect the fleet from a runaway agent.
allowed_routes on application keys, so they cannot reach the management endpoints.
soft_budget with an alert on top, understanding that it does not block.
Rotation with a verified grace_period, because an invalid format revokes on the spot.
JWT against Keycloak as soon as there are more than a handful of teams, with enforce_rbac and enforce_team_based_model_access.

Traps and things that are not what they look like

A user’s cap is not enforced. They are using a team key and apply_user_budget_to_team_keys is missing.

Clients retry in a loop against an exhausted budget. The code is 429 and the OpenAI libraries retry 429s automatically.

The soft budget has stopped nothing. It does not block, it only logs.

The per-minute limits are enforced at double or triple. There is no Redis, and each replica keeps its own count.

The client does not see the limit headers. The names are nested and proprietary, and in streaming there is an open issue where they get lost.

There is no audit log. It is an OSS deployment and the default there is disabled.

The models stop authenticating after rotating the master key. There was no fixed LITELLM_SALT_KEY, and the encrypted provider credentials can no longer be decrypted.

The rotation cut the service on the spot. The grace_period carried a format the system did not understand and it carried on without it.

Blocking a key does not fire the alert. It is raised as a generic exception, without the type that expiry and model access do carry.

Closing

The keys and budgets layer is the one that turns a shared URL into a platform with tenants. It is well solved in LiteLLM and has more depth than the documentation suggests, with per-model budgets inside a key, multiple budget windows, per-tag limits and rotation that preserves the history.

Out of the whole article, two things take the attention. The apply_user_budget_to_team_keys line, because it is the difference between having a control and believing you have one. And setting LITELLM_SALT_KEY, because its default turns a routine rotation of the master key into an outage that is hard to diagnose. Both are one line of configuration and both are discovered late.

Sources

LiteLLM, Virtual Keys (parámetros de creación, ciclo de vida, rotación): https://docs.litellm.ai/docs/proxy/virtual_keys.
LiteLLM, Budgets, Rate Limits (jerarquía, presupuestos por nivel, clientes finales): https://docs.litellm.ai/docs/proxy/users.
LiteLLM, JWT Token Auth (bloque litellm_jwtauth y todos sus campos): https://docs.litellm.ai/docs/proxy/token_auth.
LiteLLM, Audit Logs y administración múltiple (la cabecera LiteLLM-Changed-By): https://docs.litellm.ai/docs/proxy/multiple_admins.
LiteLLM, SCIM (aprovisionamiento automático, versión enterprise): https://docs.litellm.ai/docs/tutorials/scim_litellm.
LiteLLM, litellm/proxy/auth/auth_checks.py en la etiqueta v1.100.0 (la condición de apply_user_budget_to_team_keys y los mensajes de presupuesto agotado): https://github.com/BerriAI/litellm/blob/v1.100.0/litellm/proxy/auth/auth_checks.py.
LiteLLM, litellm/proxy/management_endpoints/key_management_endpoints.py en v1.100.0 (rutas, rotación sobre la misma fila, periodo de gracia): https://github.com/BerriAI/litellm/blob/v1.100.0/litellm/proxy/management_endpoints/key_management_endpoints.py.
LiteLLM, litellm/proxy/hooks/parallel_request_limiter_v3.py y litellm/proxy/hooks/__init__.py en v1.100.0 (el limitador v3 como valor por defecto, la ventana, los scripts Lua): https://github.com/BerriAI/litellm/blob/v1.100.0/litellm/proxy/hooks/parallel_request_limiter_v3.py.
LiteLLM, litellm/exceptions.py en v1.100.0 (BudgetExceededError con código 429): https://github.com/BerriAI/litellm/blob/v1.100.0/litellm/exceptions.py.
LiteLLM, litellm/proxy/common_utils/encrypt_decrypt_utils.py en v1.100.0 (LITELLM_SALT_KEY cayendo en la clave maestra, y el comentario sobre la derivación de claves): https://github.com/BerriAI/litellm/blob/v1.100.0/litellm/proxy/common_utils/encrypt_decrypt_utils.py.
LiteLLM, schema.prisma en v1.100.0 (LiteLLM_VerificationToken, LiteLLM_AuditLog, la tabla de claves deprecadas): https://github.com/BerriAI/litellm/blob/v1.100.0/schema.prisma.
LiteLLM, issue #27748 — cabeceras x-ratelimit-* perdidas en respuestas en streaming con el limitador v3: https://github.com/BerriAI/litellm/issues/27748.

Hardening and secrets in the sovereign LLM stack: defence in depth

Thu, 11 Jun 2026 11:00:00 +0000

Part of the operational series on squeezing a generic on-premise 4×H100 SXM 80GB LLM cluster. The sibling pieces: the document ingestion from PDF to indexed chunk that fills the vector database, the embeddings and rerankers service with TEI in production that feeds it, and, the most directly coupled to this post, the GitOps of the inference stack with Flux, because GitOps and secrets share a chicken-and-egg problem we solve here. Assembling all of this into a conversational assistant (LibreChat + LiteLLM + RAG) is covered by another post in the series, still in draft.

TL;DR

A sovereign LLM inference stack is, at minimum, six services: a gateway (LiteLLM or equivalent), an inference engine (vLLM), an embeddings/rerankers service (TEI), a vector database, a state database (conversations, users) and a front end (LibreChat). Six services are six attack surfaces, and the assistant “works” as soon as the gateway returns tokens, long before it is hardened. This post walks through defence in depth layer by layer:

Secrets: never in the clear in git. sealed-secrets (asymmetric encryption, controller in the cluster) vs SOPS/age (file encryption, simple, pure GitOps) vs External Secrets Operator + Vault (dynamic secrets, native rotation). GitOps’s chicken-and-egg problem.
Network: default-deny NetworkPolicy + explicit allow; L3/L4 with the standard NetworkPolicy, L7 and DNS-based egress with Cilium (eBPF); egress control so the data does not leave the perimeter; internal mTLS.
Pod security: runAsNonRoot, readOnlyRootFilesystem, dropped capabilities, seccomp RuntimeDefault, restricted Pod Security Standards, nothing privileged.
Supply chain: pin by digest, scan with Trivy, sign with cosign, admission control that rejects anything unsigned.
AuthN/Z: LiteLLM virtual keys, OIDC/LDAP in the front end, Kubernetes RBAC with least privilege.
Runtime: detection and, optionally, enforcement with Tetragon.
Data at rest: storage encryption, credentials for the vector database and the state database.

The thesis: hardening reduces the blast radius, it does not eliminate it. That is why you prioritise by impact, and the first job on a 4×H100 is the gateway↔vector store pair and egress-deny.

The analogy: the sovereign office

Picture an office holding sensitive documentation: the corpus that feeds the RAG, the users’ conversations, the engine’s credentials. It is not enough for the street door to lock. Real security is defence in depth: several layers, each assuming the previous one can fail.

The mapping is direct:

The building’s perimeter is egress control: making sure a leaked secret or a compromised process cannot exfiltrate the corpus to an external server. It is the most underrated layer and the first one I put in place in a sovereign deployment.
Access control at every interior door is the default-deny NetworkPolicy: the front end does not talk to the vector database directly because it has no reason to; only the strictly necessary pairs are open.
The fire partitions are pod isolation (restricted) and namespaces: if one service catches fire, the fire does not jump to the one next door.
The doorman who checks credentials is the admission control that verifies each image’s cosign signature before letting it into the cluster.
The cameras are Tetragon/Falco: they record what each process did and detect (or kill) anything anomalous.
The safe with a rotated key is the secrets: encrypted at rest, out of git, and rotated so a stolen key expires.

No layer is sufficient on its own. The building is secure because crossing them all is expensive.

Layer 1 — Secrets: GitOps’s chicken-and-egg problem

The stack is deployed by GitOps: the sibling piece on Flux reconciles the state declared in git against the cluster. That is excellent for manifests, but there is a foundational problem: the inference engine needs the Hugging Face token to download the model, the state database needs its password, the gateway needs its master key. Those secrets cannot go into git in the clear. Anyone with read access to the repo, and in an organisation with generous read that is a lot of people, plus every repo backup, plus every fork, would read them.

The chicken and the egg: GitOps wants all state to be in git, but secrets cannot be in git in the clear. The solution comes in three families:

Family A — sealed-secrets (asymmetric encryption, controller in the cluster)

Bitnami Sealed Secrets is a controller running in the cluster plus a client CLI, kubeseal. It uses asymmetric cryptography: there is a key pair. The public one is held by developers and is used to encrypt; the private one lives only in the cluster’s controller and is used to decrypt. The flow:

The developer takes a normal Secret and encrypts it with kubeseal, which obtains the controller’s public key. Result: a SealedSecret resource.
That SealedSecret is committed to git in the clear — it is encrypted, it is not readable.
The controller in the cluster detects it, decrypts it with its private key and creates the real Kubernetes Secret in the target namespace.

The key property: because the private key never leaves the cluster, neither the developer nor anyone with access to git can decrypt. And the encryption includes the namespace name: a SealedSecret sealed for inferencia cannot be moved to front and decrypted there — it behaves as if each namespace had its own key. The controller also manages rotation of the sealing keys, labelling them as active or compromised.

Advantage: it fits pure GitOps perfectly, the encrypted secret lives with the rest of the state. Limitation: the secret, once decrypted, ends up as a normal Kubernetes Secret — it sits in etcd, and etcd has to be encrypted separately (we will see that in layer 7).

Family B — SOPS + age (file encryption, simple)

SOPS encrypts the whole YAML/JSON file (or only its values) and leaves it in git encrypted, decrypting it only at deployment time. It supports cloud KMS (AWS/GCP/Azure), PGP and, the relevant one for on-premise sovereignty, age, a simple serverless offline encryption scheme. The GitOps operator (Flux brings native SOPS integration) decrypts on reconciliation using the age key stored in the cluster.

Advantage: simple, scriptable, with no server to maintain; the operational weight falls on safeguarding the age key. It is the usual recommendation for small teams or for getting started. Limitation: rotation is manual (re-encrypt everything with the new key) and there are no dynamic secrets.

Family C — External Secrets Operator + Vault (dynamic secrets, native rotation)

The External Secrets Operator (ESO) keeps no secrets in git at all. All that goes into git is an ExternalSecret: a reference saying “the password field comes from path secret/data/vectordb in such-and-such a SecretStore”. The operator reads from an external store, typically HashiCorp Vault, and synchronises the Kubernetes Secret. Vault keeps the secrets in its own encrypted backend and serves them over an authenticated API, so that they never reside in git and, with its dynamic engines, it can issue short-lived database credentials that expire on their own.

Advantage: native rotation, dynamic secrets, centralised auditing, a single point of governance. Limitation: you have to operate Vault (sealing/unsealing, high availability, access policy), which is real work.

How to choose, and rotation

Criterion	sealed-secrets	SOPS + age	ESO + Vault
Secret in git	encrypted	encrypted	reference only
Extra server	lightweight controller	none	Vault (heavy)
Rotation	automatic sealing keys	manual (re-encrypt)	native / dynamic
Dynamic (short-lived) secrets	no	no	yes
Fit with pure GitOps	excellent	excellent	good (references)
Operational curve	low	very low	high

For a sovereign 4×H100 getting started, SOPS/age or sealed-secrets cover 90% at minimal cost. When the system grows and requirements for frequent rotation and auditing appear, typical in ENS High Category scenarios, you migrate to ESO + Vault. The rotation rule: a secret that never rotates is a secret that, once leaked, is leaked forever. Rotation does not prevent the leak; it bounds its window of validity. We will come back to that when we talk about blast radius.

Layer 2 — Network: default-deny, egress and the arithmetic of the surface

The arithmetic of communication pairs

Without a network policy, in Kubernetes every pod can talk to every pod. That is the default posture, and it is the worst one for a sovereign system. With $N$ services, the number of possible ordered communication pairs (who-can-call-whom) is:

$$P_{\text{abierto}} = N \cdot (N-1) \approx N^2$$

With our $N = 8$ components (gateway, vLLM, TEI, vector database, state database, front end, plus the secrets controller and the observability one), that is $8 \cdot 7 = 56$ possible directed pairs. Fifty-six paths along which a compromised service could pivot laterally.

Now we apply a default-deny NetworkPolicy: nothing talks to anything except what is explicitly allowed. The real whitelist of an LLM stack is small. The strictly necessary pairs:

front end → gateway
gateway → vLLM
gateway → TEI
gateway → vector database
gateway → state database
front end → state database (sessions/users)

That is $E = 6$ edges. The communication surface falls from $56$ to $6$:

$$\frac{E}{P_{\text{abierto}}} = \frac{6}{56} \approx 0.107$$

Almost 89% of the possible paths are closed. The front end can no longer touch vLLM or TEI or the vector database directly; if somebody compromises the front end, they have no network route to the corpus. This is the difference between $\sim N^2$ and a whitelist $E \ll N^2$.

Standard L3/L4, L7 and egress with Cilium

Kubernetes’ native NetworkPolicy operates at L3/L4: it selects pods by label and allows/denies by port and protocol. That covers the bulk of the whitelist. But it has limits: it does not understand DNS or HTTP. This is where Cilium comes in, applying policies in the kernel via eBPF and extending them with CiliumNetworkPolicy:

Egress by FQDN/DNS: instead of pinning IPs (which change), allow egress only to huggingface.co so vLLM can download the model and block the rest. Critical for egress control.
L7: allow only certain HTTP methods/paths between the gateway and an internal service.
Enforcement modes: in the default mode, an endpoint with no policy selecting it has everything open; in always mode, everything is denied until a policy explicitly opens it. For a sovereign system, always + default-deny is the target posture.

Egress control is the sovereign piece par excellence. An internal service being unable to open connections to the internet except to a handful of explicit destinations means that, even if vLLM or the gateway is compromised, the corpus cannot leave the perimeter. The RAG is the asset of value; egress-deny is what stops it leaking out.

Internal mTLS

The NetworkPolicy says who can talk to whom, but it neither encrypts nor authenticates east-west traffic. For that, mTLS (mutual TLS: client and server authenticate each other). Cilium offers native mutual authentication; alternatives such as Linkerd or Istio give you a full service mesh. For a six-service stack, Istio’s full mesh is usually over-engineering; Cilium’s mutual authentication or Linkerd (lighter) is proportionate. The effect: an attacker on the cluster network cannot impersonate the gateway or eavesdrop on internal traffic in the clear.

Layer 3 — Pod security: restricted, and nothing privileged

The Pod Security Standards define three profiles: privileged (no restrictions), baseline (the reasonable minimum) and restricted (hardened). The target for the whole LLM stack is restricted, applied via Pod Security Admission with a namespace label in enforce mode. The restricted profile requires:

runAsNonRoot: true and a runAsUser other than 0. No container runs as root.
readOnlyRootFilesystem: true. The root filesystem is read-only; anything that needs to write goes to an emptyDir or an explicit volume. An attacker cannot leave persistent binaries in the container.
drop: ["ALL"] of Linux capabilities. No capabilities that are not needed.
seccomp RuntimeDefault, which applies the runtime’s profile and blocks dangerous syscalls.
allowPrivilegeEscalation: false, nothing privileged, no host namespaces.

The nuance with GPUs: pods using an H100 load NVIDIA’s device plugin, which historically tempted people to relax the securityContext. You do not need to run the inference container as privileged in order to use the GPU; device access is managed by the plugin, and the vLLM pod can and should run restricted. This is a fire partition: if vLLM is compromised, the attacker has a non-root process, with no capabilities, a read-only FS and trimmed syscalls — a terrible starting point for escalation.

Layer 4 — Image supply chain

The container image is third-party code running with access to your data. Three composed controls:

Pin by digest, not by tag. vllm/vllm-openai:latest is a moving target; @sha256:... is immutable. Pinning the digest guarantees that what was deployed is exactly what was audited.
Scanning with Trivy. Before promoting an image, Trivy enumerates its CVEs and composes the SBOM (component inventory). The pipeline fails if there are unmitigated critical vulnerabilities.
Signing with cosign and verification at admission. The Sigstore project (cosign for signing, Fulcio as a CA for ephemeral certificates via OIDC, Rekor as an immutable transparency log) allows the image to be signed. And Sigstore’s policy-controller, or Kyverno, is an admission controller that verifies the signature before admitting the pod: an image without a valid signature does not enter the cluster.

This is the doorman from the analogy: he checks each image’s credential (signature) at the door. A poisoned image uploaded to a registry, or a hijacked tag, stays outside because it carries no signature from the trusted issuer.

Layer 5 — AuthN/Z: virtual keys, OIDC and minimal RBAC

Three identity control points, from the outside in:

Front end (OIDC/LDAP). The human user authenticates against the corporate identity provider. The front end does not invent its own user system; it delegates to OIDC. This gives SSO, MFA and centralised revocation.
Gateway (LiteLLM virtual keys). The gateway issues virtual keys: each team, application or user has its own key with a budget, a rate limit and permitted models. The gateway’s master key, and the real API keys towards the engine, are never seen by the client; clients only handle their virtual key, revocable individually. If a virtual key leaks, that one and only that one is revoked.
Kubernetes RBAC with least privilege. Each service’s ServiceAccount has exactly the permissions it needs. The vLLM pod does not need to list Secret objects in other namespaces or create pods. Restrictive RBAC means a stolen service account token opens very little.

Layer 6 — Runtime: the cameras with Tetragon

The previous layers are preventive. What is missing is detection: what if something, despite everything, runs where it should not? Tetragon is observable security and runtime enforcement over eBPF, Kubernetes-aware. It hooks kernel events — process_exec, tcp_connect, security_file_open — with typical overhead below 1%, and it can move from observing (recording the event) to enforcement (killing the process or cutting the connection in the kernel, Sigkill).

The operational rule, which I set out in detail in the bubblewrap + Tetragon runbook: adopt first, block later. First you deploy in observation mode to build a baseline of the stack’s normal behaviour — which binaries vLLM executes, what the gateway connects to — without false positives. Only afterwards do you promote the clear rules to enforcement: kill any process that tries to read secret paths, or cut every tcp_connect to destinations outside the egress whitelist. Falco is the detection-only alternative over eBPF; Tetragon adds enforcement. These cameras also produce the audit evidence: what each service ran and which attempt was blocked.

Layer 7 — Data at rest

The last thing we protect is data standing still:

Storage encryption. The persistent volumes, where the vector database and the state database live, on top of disk encryption (LUKS/dm-crypt) or Ceph-level encryption. A disk stolen from the datacenter does not reveal the corpus.
etcd encryption. Remember that Kubernetes Secret objects, once decrypted by sealed-secrets or ESO, are normal objects in etcd. You have to enable etcd encryption at rest, or the secret sits in the clear in the control plane.
Database credentials. The vector database’s password and the state database’s are first-class secrets (layer 1), never embedded in the manifest or in environment variables in the clear in git.

Exposure table: service × port × external egress?

This table is the input for writing the NetworkPolicy resources. The egress column is the one that decides what leaves the perimeter.

Service	Internal port	Permitted callers	External egress?
front end	3080	(human ingress via OIDC)	No
gateway (LiteLLM)	4000	front end	No
vLLM	8000	gateway	Only `huggingface.co` for the initial download; zero in operation
TEI (embeddings/reranker)	8080	gateway	Only model download; zero in operation
vector database	6333	gateway	No
state database	5432	gateway, front end	No
secrets controller	—	(control plane)	No
observability	9090	internal scraping	No

The reading: no service needs external egress in normal operation. vLLM and TEI need it once to pull the model, and that permission can be temporary or restricted by FQDN to huggingface.co. Everything else is total egress-deny. If a service starts attempting outbound connections this table does not contemplate, Tetragon records it and, in enforcement, cuts it.

Blast radius: a leaked secret, with and without defence

The blast radius measures how much damage a compromise does. Let us model it for the realistic worst case: the state database’s credential leaks.

Without hardening (flat network, unrotated secret, no egress-deny, no detection):

The secret gives access to the state database from any pod (flat network → 56 open pairs).
The secret does not rotate → it is valid indefinitely; the exploitation window is $\infty$ until somebody notices.
Without egress-deny, the attacker dumps the whole database to an external server.
Without Tetragon, nobody finds out until the public incident.
Blast radius: the entire state database, exfiltrated, undetected, for an indefinite time.

With hardening (default-deny, ESO + Vault with dynamic credentials, egress-deny, Tetragon in enforcement):

The secret is only usable from the pod that has a network route to the state database (1-2 pairs, not 56).
With Vault’s dynamic credentials, the secret expires — say within a window $T$ of hours; past $T$, it is worthless.
Egress-deny prevents the dump to the internet: the attacker can read, but cannot take anything out.
Tetragon records the anomalous access and, in enforcement, kills the process attempting the outbound connection.

The qualitative reduction is enormous, but let us be quantitative about the window. If a static secret is valid forever and a rotated one with period $T$ is valid for at most $T$, and compromises arrive at rate $\lambda$, the expected number of live and exploitable secrets at any given instant goes from growing without bound to being capped at $\lambda \cdot T$. With rotation every 24 h ($T = 1$ day) against “never”, a given secret’s window falls from months to a day: a reduction of one to two orders of magnitude in temporal exposure. Combined with the reduction in network pairs ($56 \to \sim 2$, a factor of $\sim 28\times$) and egress-deny (from exfiltration possible to impossible by the direct route), the blast radius is drastically reduced.

But let us be honest: it does not reach zero. The attacker with the credential can read the state database during the window $T$ from the compromised pod. Hardening turned “indefinite, silent catastrophe” into “a bounded, detected incident with no exfiltration by the direct route”. That is exactly what defence in depth promises: not invulnerability, but that the cost of a full compromise is high and its radius small.

The ENS / NIS2 angle

These layers are not voluntary hygiene: they implement specific controls. The mapping is developed in detail in the technical controls ENS × ISO 42001 × EU AI Act post; here, the actionable summary:

Hardening layer	ENS measure (RD 311/2022)	NIS2 / framework link
Encrypted secrets + rotation	`op.exp.11` (cryptographic keys), `mp.info.3` (encryption)	Credential management; in High Cat., HSM
Default-deny NetworkPolicy + segmentation	`mp.com.1` (perimeter), `mp.com.4` (flow separation)	NIS2 art. 21: network security measures
Egress control	`mp.com.1` + `op.mon.1`	Exfiltration prevention
Internal mTLS	`mp.com.2-3` (confidentiality/integrity in transit)	Mandatory TLS
Restricted Pod Security	`op.exp.2` (hardened configuration)	Configuration hardening (CIS)
Trivy + cosign + admission	`op.exp.6` (malicious code), `op.ext.3` (supply chain)	NIS2 supply chain
OIDC + virtual keys + RBAC	`op.acc.1-2-5` (identification, access, authentication)	MFA in High Cat.
Tetragon runtime	`op.mon.1` (intrusion detection)	Monitoring and response
Encryption at rest + etcd	`mp.info.3` (encryption), `mp.si` (media)	Data at rest

The honest note for auditing: hardening reduces risk, it does not eliminate it, and maturity is demonstrated by prioritising by impact. A competent auditor does not want to see nine half-finished layers; they want to see that egress-deny on the critical asset (the corpus) and secrets management are solid before mTLS is perfect between low-sensitivity services. For the management and governance context, see also ISO/IEC 42001 as an AIMS and the EU AI Act mapping onto the architecture.

Applied to the generic 4×H100 cluster

In a real deployment on 4×H100 SXM 80GB, you do not harden the nine layers at once. The order, prioritised by impact:

Egress-deny on vLLM, TEI and the vector database, first. It is the barrier that stops the corpus leaving the perimeter, and it goes in as soon as the services start. Allow egress by FQDN to huggingface.co only during the model’s initial download; afterwards, zero. It is the layer with the highest return per hour invested.
Secrets for the inference engine and the databases, out of git. The Hugging Face token vLLM uses to download the model, the vector database’s and the state database’s passwords, the gateway’s master key: into sealed-secrets or, if there is already a rotation requirement, into ESO + Vault. Never in values.yaml in the clear.
Default-deny NetworkPolicy + the 6-edge whitelist. The gateway and the vector database are the most exposed services — the gateway because it receives all the traffic, the vector database because it holds the embedded RAG. Closing everything that is not on the whitelist cuts lateral pivoting from $\sim N^2$ to the 6 real edges.
restricted Pod Security in the inference namespace, including the vLLM pod with a GPU (it needs no privileges to use the H100).
cosign + admission so only signed images get in; Trivy in the GitOps pipeline of Flux.
Tetragon in observation, baseline, and then enforcement over the egress of the sensitive pods.
Encryption at rest for the databases’ volumes and for etcd.

The gateway and the vector database are the two I harden first inside the whitelist: the gateway for being the exposed face, the vector database for holding the asset that egress-deny protects. The rest is built on top, layer by layer, always assuming the previous one can fail.

What hardening does NOT solve

To close honestly, what these layers do not cover and what needs other pieces:

Prompt-level attacks (jailbreak, indirect injection via the RAG corpus): that is the job of guardrails and LLM Guard, not of NetworkPolicy.
Agents with legitimate permissions doing something harmful: the runtime isolation from the agent isolation post bounds what an agent can touch, but a granted permission is a usable permission.
The human factor: a well-managed secret shared over Slack is still leaked. Rotation bounds the window, it does not eliminate the mistake.
Zero-day vulnerabilities in the components themselves: Trivy detects what is known; the unknown gets through until the CVE is published.

Hardening is a multiplier on the cost of attacking, not an impassable wall. Its value lies in making an individual compromise bounded, detected and with no way out — and that, for a sovereign system holding sensitive data, is exactly the goal.

Ontologies and knowledge graphs in LLMOps: the Linnaean nomenclature that holds up the six pipeline stages

Wed, 03 Jun 2026 03:30:00 +0200

This post runs through the six stages of the LLMOps pipeline from a cross-cutting perspective: the common nomenclature that makes the stages share a vocabulary. It connects directly to RAG corpus curation (the corpus is curated against an ontology), embeddings (the ontology enriches the embedding with typed metadata), hybrid retrieval (the KG is a fourth channel alongside dense/sparse/multi-vector), evals (golden sets are stratified by ontological class), structured output (JSON Schemas derive from OWL/SHACL), and the three frameworks of ISO 42001, ENS and EU AI Act (each one is a control ontology).

TL;DR

The conversation about ontologies and LLMs has swung between two equally wrong positions over the last three years: either “LLMs already extract knowledge on their own, ontologies belong to the last century”, or “all of RAG has to go and we should build a knowledge graph on top”. The operational reality of mid-2026 is more sober: the ontology is not a replacement for RAG but its common nomenclature, without which the six stages of the LLMOps pipeline work with different vocabularies without knowing it. The corpus is curated without knowing which entity classes exist; the embeddings drill through documents without being enriched with typed metadata; the evals report a global accuracy that hides whole class gaps; the guardrail blocks on word lists instead of formal classification; incident response groups badly because each alert names “the affected asset” its own way; compliance cannot map its controls because ENS, ISO 42001 and the EU AI Act are three ontologies and the system has none. This post takes apart what an ontology is in practical terms (TBox and ABox, RDF and SPARQL, the four OWL 2 profiles: EL for enormous terminologies such as SNOMED, QL for OBDA, RL for rule-based reasoning, DL for the full description logic, plus SHACL for shape validation, SKOS for thesauri, JSON-LD as a viable serialisation), walks the six LLMOps stages showing where the ontology changes operations, reviews the GraphRAG field in 2026 with verifiable data (Microsoft GraphRAG v2 Oct 2025, LightRAG dual-level with incremental updates, HippoRAG 2 with Personalized PageRank, KAG on OpenSPG ontology-grounded), inventories the vertical ontologies actually deployed in production (FIBO, SNOMED CT, schema.org, IEC 81346, GS1, Wikidata, ENS Annex I-II of RD 311/2022, EU AI Act Annex III), settles the viable open source on-prem stack with its licensing caveats (Neo4j Community is GPLv3 with AGPL implications in some features, KuzuDB upstream archived Oct 2025, forks bighorn and ryugraph), describes the five LLM × ontology integration patterns and closes with seven operational traps. The rule of thumb: the knowledge graph is not the answer; shared formalised nomenclature is.

The analogy: Carl Linnaeus, 1735

In 1735 Carl von Linné published the first edition of Systema Naturae. Before Linnaeus, European naturalists had an operational problem: the same species could appear in five treatises under five different Latin names, each a polynomial description of the type “Felis cauda elongata cum maculis nigris in dorso et lateribus”, and two naturalists exchanging letters took months to realise they were arguing about the same animal. Biology was a field of lexicographic noise: impossible to compare observations, impossible to verify replication, impossible to build cumulative theory.

Linnaeus did not discover biology. What he discovered was that the field needed a common nomenclature with three properties:

Strict hierarchy. Kingdom → Phylum → Class → Order → Family → Genus → Species. Each level is a class with well-defined subclasses. A property of Felis (a carnivorous diet) is inherited automatically by Felis catus and Felis silvestris without being redeclared.
Unambiguous naming. Each species has a single binomial name (Genus + specific epithet) and a single type specimen anchored in a museum. “Felis silvestris” means exactly the same thing in Madrid, Stockholm and Calcutta.
Priority rules. If two botanists publish the same genus under different names, the first to register it validly wins. The naming convention is not debated in every paper: there is an explicit meta-level of governance.

After Linnaeus, comparative biology becomes possible. Mendel can talk about Pisum sativum and a Polish botanist knows exactly which plant to grow to replicate him. Darwin can compare Galápagos finches with finches from other islands with no confusion about what “the same kind of bird” means. The change is not one of instrumentation; the microscope had existed since Hooke (1665). The change is one of shared formal vocabulary.

An ontology in computing is exactly this:

Linnaeus (1735)	Ontology (2026)
Kingdom → … → Species hierarchy	Class hierarchy (`Person ⊑ Agent ⊑ Thing`), the TBox
Type specimen in a museum	Instance anchored with a unique IRI, the ABox
Binomial name	A unique IRI / URI per concept
Priority rules	Ontology axioms plus governance
“Felis silvestris” means the same in Madrid and Stockholm	`<http://example.org/ont/Felis_silvestris>` means the same in any system

When an LLMOps team today says “our corpus is curated, the embeddings are bge-m3 and the evals measure recall@5”, but the question “what proportion of queries about high-category ENS assets are well covered?” has no answer, because no formal class “high-category ENS asset” exists in the system, the problem is pre-Linnaean: the field has not yet given itself the nomenclature that makes each stage comparable.

The ontology runs through the six stages as shared vocabulary. Without it, each stage has its own definition of "customer", "sensitive document" or "incident".

What an ontology is in operational terms

The word “ontology” carries an unavoidable philosophical family resemblance (Aristotle, Kant’s categories, Quine) that confuses at first. In LLM infrastructure it does not matter: an ontology is a directed graph with types, formally described, over which you can reason, validate and query. What matters are six practical concepts.

TBox and ABox

The distinction used every day. The TBox (from terminology) is the schema: classes, subclass hierarchy, properties, axioms. The ABox (from assertions) is the instances.

# TBox — schema
:Person rdfs:subClassOf :Agent .
:Employee rdfs:subClassOf :Person .
:worksFor rdfs:domain :Employee ; rdfs:range :Organization .

# ABox — instances
:alice a :Employee .
:alice :worksFor :acme .

A reasoner checks that the ABox is consistent with the TBox: if you declare :alice :worksFor :acme but :alice is not an :Employee, the reasoner flags the inconsistency. That is the lever: automatic validation of knowledge, which no system based on dense embeddings alone can provide.

RDF and the unit of information

The atomic unit of the Semantic Web is the RDF triple (subject, predicate, object). Every piece of data is expressed as a collection of triples. This gives the paradigm’s most useful operational property: two graphs merge trivially by union. If your system indexes the medical corpus with SNOMED CT and the legal corpus with FIBO, both in RDF, merging them for a query that crosses both domains is literally g1 ∪ g2. In a property graph (Neo4j) this takes more surgery.

The four OWL 2 profiles

People new to the field assume OWL is one thing. It is four profiles with different trade-offs, all W3C Recommendations:

Profile	Expressiveness	Reasoning cost	Use cases
OWL 2 EL	restricted (subclass, intersection, properties)	polynomial in ontology size	enormous terminologies — SNOMED CT (350k+ concepts)
OWL 2 QL	subset that maps to SQL/UCQ	LOGSPACE in data	OBDA (ontology-based data access) over relational DBs
OWL 2 RL	subset implementable as rules (Datalog)	scalable, without full DL	production reasoning with rule engines
OWL 2 DL	full SROIQ (the “full ontology”)	decidable but NEXPTIME in the worst case	academic ontologies, deep validation

Operational rule: if your team is not going to read a description logics paper every month, do not use OWL 2 DL. Almost all the value is in EL/QL/RL. For large medical terminologies, EL. To reason over existing relational data, QL. For business rules, RL.

SHACL — the validation you actually operate

OWL does reasoning (“given these axioms, what can be deduced?”). SHACL does validation (“given this concrete graph, does it satisfy these shapes?”). In production, SHACL wins because its semantics are closer to the type checking a developer already understands:

:PersonShape a sh:NodeShape ;
 sh:targetClass :Person ;
 sh:property [
 sh:path :nombre ;
 sh:minCount 1 ;
 sh:datatype xsd:string ;
 ] ,
 [
 sh:path :nif ;
 sh:pattern "^[0-9]{8}[A-Z]$" ;
 ] .

Validating an incoming graph against this shape catches :alice :nombre 42 (wrong type), :alice :nif "12345678X9" (wrong format) or :alice a :Person with no name (min count violated). It is JSON Schema for graphs, conceptually. The SHACL 1.2 spec is a W3C draft from 2025; SHACL 1.0 has been in production since 2017.

SKOS — the lightweight thesaurus

Not all knowledge deserves OWL. For controlled vocabularies (thesauri, taxonomies, glossaries) there is SKOS:

:Mamifero a skos:Concept ;
 skos:prefLabel "Mamífero"@es , "Mammal"@en ;
 skos:broader :Animal ;
 skos:narrower :Felino , :Canido .

SKOS does not express formal axioms: skos:broader is not rdfs:subClassOf. It serves to classify content with no pretension of reasoning, which covers 80% of corporate cases. Start with SKOS: most enterprise “ontologies” are in fact thesauri that were promoted to OWL out of fashion and drag unnecessary complexity along.

JSON-LD and SPARQL — the practical surfaces

JSON-LD 1.1 (W3C Rec 2020) is the serialisation that actually gets used in real systems: ordinary JSON with an @context field mapping the keys to IRIs. The schema.org microformat on web pages is JSON-LD. For an LLMOps team, JSON-LD is the natural exchange format with tools and APIs.

SPARQL 1.1 (W3C Rec 2013; 1.2 in draft 2025) is SQL for graphs:

SELECT ?empleado ?empresa WHERE {
 ?empleado a :Employee ;
 :worksFor ?empresa ;
 :pais "España" .
 ?empresa :sector "fintech" .
}

Every modern triple store speaks it. The federation features let a single query touch several endpoints: SNOMED CT plus your own corporate ontology.

Why it matters for an LLM in production

The romantic promise of 2023-2024 was: “now that we have LLMs we do not need ontologies; the model understands natural language and extracts knowledge”. The operational reality of mid-2026 is more nuanced and rests on four observations anyone with a RAG in production has already made:

The LLM has semantic memory but no declared schema. If you ask “which entities of type Person appear in this document?”, it answers something reasonable. If you ask “which people appear and which of them are employees of the customer?”, the answer depends on how the model interprets “employee of the customer” in that context. Without an external schema saying “Employee is a subclass of Person and relates to Organization via worksFor”, coherence between two calls to the same LLM is not guaranteed.
Quality varies by domain without the system knowing why. Your RAG has a global accuracy of 78% but fails systematically on queries about derivative financial instruments. Since you have no formal classification of queries by category, the problem is invisible until a customer complains.
Compliance demands formal nomenclature. ENS classifies assets along five dimensions (Confidentiality, Integrity, Availability, Authenticity, Traceability) with three levels each. The EU AI Act lists eight high-risk areas in Annex III. Without a formal mapping between your assets and those categories, you cannot audit what you cannot name. The auditor asks “which corpus chunks touch specially protected personal data?” and your system does not have that column.
Interoperability between components demands types. Your retrieval returns “relevant chunks”. Your reranker reorders them. Your guardrail filters out the sensitive ones. If each component has its own definition of what a “sensitive chunk” is, the chain breaks at every interface. A shared ontology is the pipeline’s type contract.

The operational consequence: the ontology does not replace RAG. It types it. It makes it auditable, comparable and debuggable. The right question is not “do I need a knowledge graph?” but “at which pipeline stages do I gain if I introduce a shared formal nomenclature?”.

The six LLMOps stages × ontology

Let us walk the six pipeline stages asking what changes in each one when there is an ontology. This is the spine of the post: the lever is not “install Neo4j”, it is introducing types where there was plain text before.

Stage 1 — Data

Corpus curation becomes ontology-driven curation:

Each chunk is not just “text + embedding”, it also carries chunk:tipoDocumento, chunk:nivelClasificacion, chunk:categoriaENS, chunk:contienePII.
These types come from an explicit corporate ontology, not from ad-hoc strings written by whichever data engineer was on the morning shift.
Rule 4 of corpus curation, anti-contamination, benefits: chunks in the golden eval set carry dataset:goldenEval=true declared as a triple; any reindexing that filters on goldenEval=true becomes trivial.
The PII detector stops being a regular expression and becomes a classifier against the personal data categories thesaurus: identifier, contact, financial, health, biometric. The chunk:pii column is no longer boolean but a list of SKOS categories.

# Ingestion with ontological typing
chunk = {
 "@context": "https://ontology.fibercli.es/v1/context.jsonld",
 "@id": f"chunk:{uuid4()}",
 "@type": "Chunk",
 "tipoDocumento": "ContratoComercial",
 "nivelClasificacion": "ConfidencialMedio",
 "categoriaENS": ["Disponibilidad-M", "Confidencialidad-A"],
 "contienePII": ["IdentificadorFiscal", "Contacto"],
 "embedding": [...],
 "text": "...",
}

Under the JSON-LD context, all those keys resolve to IRIs and are queryable via SPARQL.

Stage 2 — Train / Adapt

Continuous fine-tuning and retrain gain two levers:

Datasets stratified by class. When production feedback turns into a training dataset, each example comes labelled with the ontological class of the incident that produced it. This lets you sample n examples per class instead of n examples globally, which corrects the model’s coverage gaps.
Ontology-guided synthetic generation. For classes with few examples in the real corpus, synthetic data is generated against the schema: “generate 50 questions about FIBO:DerivativeInstrument that a trader might ask”. The output goes through structured output validated against the schema’s SHACL shape before entering the dataset.

Stage 3 — Eval

The evals layer changes more than any other. Without an ontology, the eval reports a global accuracy that hides everything:

accuracy = 0.78

With an ontology, it reports a coverage matrix by class:

 accuracy n_queries covered_in_corpus
ContratoComercial 0.82 142 yes
EmpleadoENS-Alto 0.31 18 partial
DerivadoFinanciero 0.74 67 yes
SOAP_3.0_Endpoint 0.05 9 no

The EmpleadoENS-Alto row with accuracy 0.31 exposes a problem that is invisible without stratification. The SOAP_3.0_Endpoint row with accuracy 0.05 and covered_in_corpus=no shows that the class has no corpus at all: before touching the model you have to touch ingestion. A single metric hides; a per-class metric drives action.

This is the rule that LLM-as-judge and evals should always implement wherever an ontology exists: the golden eval set is labelled by class and every metric is reported stratified.

Stage 4 — Deploy

In the LLM inference router the ontology enables:

Semantic routing by class. Queries that, after a first classification, fall under FIBO:Securities are routed to the adapter fine-tuned on finance; queries under SNOMED:ClinicalFinding go to the medical adapter. Without an ontology, this routing rests on ad-hoc classifiers or fragile lexical heuristics.
Typed tool calling. The tools the agent can invoke declare their arguments against ontology classes. The cliente_id argument is not a string; it is a :ClienteCorporativo. Before running the tool, the arguments are validated with SHACL. This sharply cuts errors from badly populated arguments.
Feature flags with a class. The canary becomes “the new model receives 10% of queries in class X” instead of an undifferentiated 10%: it isolates the blast radius.

Stage 5 — Observe

This is where the absence of an ontology hurts fastest in operations. The incident response runbooks require:

A formal incident taxonomy. IncidenteSeguridad ⊑ Incidente, IncidenteIA ⊑ Incidente, FugaDatos ⊑ IncidenteSeguridad. Without this taxonomy, the five events from last month labelled “model issue”, “data drift”, “pii leak”, “prompt injection” and “hallucination” are neither groupable nor comparable. Keep + Kafka apply deduplication against that taxonomy.
Typed lineage in the KG. GPU observability plus tracing emits spans with attributes. If those attributes are typed against the ontology (span.input.classification = :ConfidencialMedio), finding every request that touched class ConfidencialAlto in the last hour is a trivial SPARQL query; without an ontology, it is a grep over unstructured logs.

Stage 6 — Govern

Where the ontology becomes unavoidable. Every regulatory framework is an ontology:

ENS RD 311/2022 Annex I: defines five dimensions (C, I, A, A, T) × three levels (Low, Medium, High). It is an asset classification scheme. Annex II lists 73 control measures with an organisational / operational / protection hierarchy. The ENS technical controls map each control to stack components, and that mapping is a relational ontology.
ISO 42001 Annex A: lists grouped controls (A.5 policies, A.6 internal organisation, A.7 resources for AI, A.8 assessment, A.9 operation). The AIMS over an on-premise LLM formalises them.
EU AI Act Annex III: eight high-risk areas. The technical file mappings are a translation from the legal ontology to the system’s technical ontology.

Without an ontology mapping your inventory of assets, datasets, models and endpoints to the classes of those three frameworks, compliance is manual, reactive and breaks with every change to the stack. With the ontology, a model change automatically triggers which controls are affected.

The GraphRAG field in 2026

GraphRAG is the generic name for a family of techniques that build a knowledge graph from a corpus and use it as an additional retrieval layer complementary to the dense / sparse / multi-vector we saw in embeddings. The motivation is that some queries (“what are the dominant themes in this corpus”, “which entities appear connected to customer X in the last six months”) are not answered well by cosine similarity between vectors.

Microsoft GraphRAG

microsoft/graphrag (July 2024, v1.0 Dec 2024, v2.x Oct 2025; any reference to v3 needs checking against GitHub releases before citing). The canonical pipeline:

Extraction. An LLM reads the corpus chunk by chunk and extracts entities and relations, so the TBox emerges from the data instead of being declared.
Graph construction. The extracted entities are disambiguated, merged and connected through the relations.
Community detection with the Leiden algorithm. The graph is partitioned into hierarchical communities.
Per-community summaries. For each community, the LLM generates a summary.
Local vs global search. Local: neighbourhood traversal for queries about specific entities. Global: map-reduce over community summaries for thematic queries.

The price: building the KG costs on the order of 5-20× more tokens than an embedding pass over the same corpus. For a corpus of 1 million chunks with bge-m3 embeddings (a day of compute on an RTX 4090), a pure GraphRAG typically requires 1-3 weeks of LLM-extractor compute (Qwen2.5-72B or similar). The LazyGraphRAG variant (mid-2025) defers summary generation to query time and cuts the construction cost by an order of magnitude.

LightRAG

HKUDS/LightRAG (HKU, arXiv:2410.05779, October 2024, EMNLP 2025). Practical improvements over canonical GraphRAG:

Dual-level retrieval. Each query generates both low-level keywords (specific entities) and high-level keywords (themes). The system searches by both and fuses the results. It captures factual and thematic questions in the same pipeline.
Incremental updates. Insertion of new chunks without rebuilding the whole graph. Canonical GraphRAG requires periodic rebuilds.
Reported cost: comparatively cheaper than GraphRAG for serving similar queries.

It is the operationally most reasonable GraphRAG when the corpus mutates.

HippoRAG 2

OSU-NLP-Group, arXiv:2502.14802 (Feb 2025; the original HippoRAG at NeurIPS'24). Inspired by the hippocampal indexing model of human memory:

It builds an open KG and also keeps the original chunks.
For each query it extracts entities and runs Personalized PageRank over the graph seeded by those entities: the PageRank “marks” the relevant nodes and, transitively, the associated chunks.
Reported +7% on associative memory tasks over SOTA embedders, with significantly lower indexing cost than GraphRAG, RAPTOR and LightRAG.

It is the most efficient GraphRAG for corpora where “which chunks are relevant to which entities” matters more than “what is the semantic structure of the corpus”.

KAG / OpenSPG

Ant Group + OpenKG, arXiv:2409.13731 (Sep 2024). The key difference from the others: KAG is ontology-grounded. It does not let the LLM invent the TBox; the TBox is declared by the domain (FIBO, SNOMED, corporate ontology) and the LLM only populates the ABox in accordance with that schema. Four pillars:

LLM-friendly representation — the schema is exposed in a format the LLM can consume as context.
Mutual index between the KG and chunks — each KG node links to the chunks it appears in.
Hybrid logical-formal reasoning — it combines the LLM with a declarative rule engine.
Semantic alignment — entity disambiguation against the ontological catalogue.

Reported +19.6% F1 on 2WikiMultiHopQA, +33.5% on HotpotQA over the RAG baseline. Deployed in Ant’s e-government and e-health Q&A in production.

KAG is the GraphRAG that works when the domain has a stable ontology (finance, health, government). Canonical GraphRAG wins when the corpus is exploratory and no prior TBox exists.

Others in the landscape

nano-GraphRAG: a lightweight Python port of GraphRAG; ideal for prototypes.
Think-on-Graph (ToG) / GraphReader: agents that plan hop traversals over the KG instead of single-shot retrieval. Better at multi-hop QA.
Neo4j LLM Graph Builder plus LangChain integration: the path of least resistance for companies already running Neo4j.

Vertical ontologies that really get used in production

Three ontologies cover 90% of vertical cases in mid-2026:

FIBO — Financial Industry Business Ontology

EDM Council + OMG, MIT license, OWL DL. The Q1/2026 production release contains 2,446 classes spread across Foundations, Business Entities, Securities, Derivatives, Loans and so on. Used in production for:

KYC entity resolution: disambiguating legal organisations (fibo-be-le-fbo:FormalBusinessOrganization).
Classification of financial instruments (fibo-sec-sec-bsk:Basket, fibo-der-drc-cds:CreditDefaultSwap).
Regulatory reporting: mapping fields against the canonical schema.

For a corporate RAG in finance, FIBO is the type schema any extraction has to satisfy. Without FIBO, two chunks that talk about a “swap” might mean an interest rate swap or a currency one.

SNOMED CT

IHTSDO/SNOMED International. Monthly releases (the May 2026 International Edition published on 15 May). Roughly 350,000+ active concepts in OWL 2 EL. Free licence in member countries (Spain is a member through the CSI / Ministry of Health), commercial outside. In production:

Assisted clinical coding: the LLM proposes SNOMED codes and the system validates them against the ontology.
Cross-lingual search in records: Diabetes mellitus type 2 and Diabetes mellitus tipo 2 resolve to the same concept (73211009).
HIPAA / GDPR health compliance: traceability of what type of clinical data each component handles.

schema.org

CC-BY-SA, ~800 types, native JSON-LD. The ontology of the web. Used in any RAG over public crawls to type Product, Article, Person, Organization from the microformats the corpus already carries embedded.

The others worth keeping on the radar

Ontology	Domain	Licence	When to use it
IEC 81346	industrial systems (designation =K1-Q1)	IEC proprietary	CMDB-as-graph, industrial plant
GS1	supply chain (GTIN, GLN, SSCC)	membership; free web vocab	EUDR traceability, retail
NIEM	US gov interoperability	CC0	gov-to-gov integration
Wikidata	universal KB (~115M items)	CC0	universal entity linking
ENS RD 311/2022 Annex I-II	ESP public sector security	BOE public	asset classification in any ENS deployment
EU AI Act Annex III	8 high-risk areas	EU regulation	EU compliance tagging

For a Spanish public sector customer with AI systems, the minimum ontology worth formalising is the union of ENS Annex I + EU AI Act Annex III + ISO 42001 Annex A. That mapping is generated once, kept as a versioned artefact in the AI governance repo and linked from the lineage of every deployed model.

Open source on-prem stack 2026

The implementation landscape splits into RDF triple stores, property graphs and auxiliary tooling.

RDF / SPARQL triple stores

Stack	Licence	Operational notes
Apache Jena Fuseki	Apache 2.0	The open reference. TDB2 storage. Quarterly releases. The reasonable default.
Eclipse RDF4J	EDL/BSD-like	Java framework plus server (Sesame-derived). Mature.
Virtuoso Open Source	GPLv2	High performance. The Community edition does not include clustering.
Ontotext GraphDB Free	proprietary EULA, free up to 2 concurrent queries	Strong OWL 2 RL reasoning. Operational cap on concurrency.
Stardog	proprietary	No genuine free production tier in 2026, only developer.
Blazegraph	discontinued	Wikidata is migrating to Qlever / others. Do not start a new project on it.

Property graphs (Cypher / Gremlin)

Stack	Licence	Operational notes
Neo4j Community Edition	GPLv3 (with a historical Commons Clause on some artefacts); Enterprise closed	Native vector index since 5.11. Cypher 25 adds the `SEARCH` clause. Cypher AI procedures (Dec 2025) integrate LLM calls and embedding generation into the query. AGPL implication: if you redistribute a SaaS exposing Neo4j Community functionality it may require source disclosure — check with legal.
Memgraph	BSL → Apache after 4 years	In-memory, Cypher. Faster than Neo4j for query-intensive workloads.
NebulaGraph	Apache 2.0	Distributed. For large sizes.
ArangoDB	Apache 2.0 (Community); features moved to Enterprise post-3.12	Multi-model (graph + document).
KuzuDB	MIT	Kùzu Inc. archived the upstream repo in Oct 2025. Community forks: `bighorn` (Kineviz), `ryugraph`. Treat upstream as unmaintained.

Hybrid vector + graph

Neo4j 5.x with native HNSW: the vector as a node property, search from inside Cypher. The most integrated option.
Memgraph + pgvector: two stacks, two operating points.
Qdrant with a graph payload: not a real graph, but it allows basic k-hop style filters over the payload.

Editors and tooling

Protégé (Stanford, BSD): the de facto ontology editor. A suite with the HermiT, Pellet and ELK reasoners.
TopBraid Composer: commercial; useful if it is already in the organisation.
Atomgraph: LGPL web editor.

Building the KG with an LLM

GLiNER / GLiREL (Apache 2.0): zero-shot NER and relation extraction. Far cheaper than an LLM-extractor (10-100× fewer tokens).
REBEL (MIT): joint entity + relation extraction based on BART. SOTA for years, today beaten by LLM-extractors but still reasonable as a baseline.
LLM-extractor with structured output: vLLM + XGrammar or Outlines enforcing a JSON Schema derived from SHACL. XGrammar has been the default backend in vLLM / SGLang / TensorRT-LLM since March 2026, with <40 µs/token of overhead.

SPARQL clients

rdflib (Python, BSD), the Apache Jena CLI, Comunica (MIT, JS, native SPARQL federation).

Five LLM × ontology integration patterns

Almost everything useful fits into five repeatable patterns.

1. Schema-guided extraction

The LLM emits JSON conforming to a schema derived from the ontology, validated in the decoder with structured output. The output is typed ABox ready to insert as triples:

schema = derive_json_schema_from_shacl("PersonShape.ttl")
# The LLM can only emit tokens that keep the output valid.
extracted = llm.generate(prompt=document, schema=schema)
graph.add_triples(jsonld_to_rdf(extracted))

Cost: practically zero overhead per token with XGrammar; effective elimination of “outputs that do not validate”.

2. Text-to-SPARQL with a semantic firewall

The LLM generates SPARQL; a semantic firewall validates every predicate and class against the TBox before running the query:

sparql_text = llm.generate(prompt=user_query, context=ontology_summary)
query = parse(sparql_text)
for predicate in query.predicates:
 if predicate not in ontology.declared_predicates:
 raise UnknownPredicate(predicate)
result = endpoint.execute(query)

It catches the classic pattern of the LLM inventing a plausible predicate that does not exist in the ontology, before touching the triple store.

3. Hybrid dense + sparse + KG retrieval with RRF

The reranker and hybrid retrieval is extended with a fourth channel: traversal in the KG seeded by the entities extracted from the query. The rankings of the four channels are fused with Reciprocal Rank Fusion:

\text{RRF}(d) = \sum_{c \in \{\text{dense}, \text{sparse}, \text{colbert}, \text{kg}\}} \frac{1}{k + \text{rank}_c(d)}

with k=60 typical. The KG channel covers exactly the queries that break the other three: queries with named entities that dense misreads or that appear rarely in the corpus.

4. Reranking by graph distance

Among the candidates from the first retrieval committee, chunks whose entities lie within k hops in the KG of the query entities are preferred. A practical implementation: add a graph_distance score and fuse it into the reranker:

def graph_distance_score(chunk, query_entities):
 chunk_entities = chunk["entities"]
 distances = [
 shortest_path_length(kg, qe, ce)
 for qe in query_entities for ce in chunk_entities
 ]
 return 1 / (1 + min(distances))

5. Typed tool calling + stratified evals

Tools declare their arguments as ontology classes. Before invocation, the arguments go through SHACL validation. This avoids the classic bug of the agent calling buscar_cliente(cliente_id="the customer who complained yesterday"), a free string where an IRI was expected.

Stratified evals by rdf:type or skos:Concept: each golden set query carries its ontological class as a label, the metrics are reported per class, and global accuracy is complemented by per-class coverage. It is the mechanism evals recommends and the ontology makes operational.

Implications for on-premise inference

The triple store or property graph does not eat GPU: it runs on CPU plus NVMe. What does compete for GPU is the LLM-extractor that builds and maintains the KG.

On the RTX 4090 (24 GB)

A reasonable setup for a PoC and small sites:

GPU 24 GB ┐
 ├─ TEI bge-m3 (dense + sparse + colbert) │ ~6 GB VRAM
 ├─ vLLM Qwen2.5-7B-Instruct AWQ Q4 (main LLM) │ ~8 GB VRAM
 └─ Occasional load: vLLM Qwen2.5-7B-Instruct for overnight extraction │ shares VRAM in another window
CPU/RAM ┐
 ├─ Apache Jena Fuseki (TBox + ABox of the corporate KG) │ ~2 GB RAM per M triples
 ├─ Qdrant (dense + sparse + colbert) │ ~3 GB RAM per M chunks
 └─ GLiNER + REBEL for fast batch extraction │ CPU-only

For corpora of up to a few million chunks, an RTX 4090 does the job by combining GLiNER/REBEL on CPU for bulk extraction (cheap but less accurate) and the LLM on GPU for critical cases.

On the 4×H100 80 GB cluster

H100 #1 (80 GB) ── vLLM Qwen3-72B-Instruct AWQ + Qwen2.5-7B speculative │ main LLM
H100 #2 (80 GB) ── vLLM gte-Qwen2-7B-instruct (embedding 32k ctx) │ large embedder
H100 #3 (80 GB) ── vLLM Qwen2.5-32B-Instruct (dedicated KG extractor) │ KG construction + maintenance
H100 #4 (80 GB) ── Hold-out for canary and offline evals │ see the canary post

Apache Jena Fuseki cluster (3 CPU nodes + NVMe RAID)
 ├─ Corporate ontology (TBox)
 ├─ ABox (hundreds of millions of triples)
 └─ FIBO / ENS / EU AI Act as named graphs

Qdrant cluster (3 CPU nodes + NVMe)
 ├─ Chunks indexed with triples in the payload
 └─ Lineage towards KG nodes

The H100 dedicated to the KG extractor is the real price of the GraphRAG approach. If the corpus is stable, that H100 can go to offline evals or speculative decoding. If the corpus mutates daily, it is busy keeping the graph up to date online.

The seven operational traps

Promoting SKOS to OWL DL out of academic ego. Most “corporate ontologies” are taxonomies that need no description logic reasoning. A SKOS with skos:broader/skos:narrower and skos:prefLabel per language covers 80% of cases. OWL DL only makes sense when there are consistency axioms the reasoner has to verify. Start with SKOS, move up to OWL EL/RL if you need to, avoid OWL DL unless the need is proven.
Building a KG over the whole corpus. Canonical GraphRAG applied to 100 million chunks costs as much as training a small model. The correct alternative is HippoRAG 2 / LightRAG / KAG depending on the case, or GraphRAG over the critical subset of the corpus only. The rule: if the construction cost exceeds the annual cost of serving the model, you have picked the wrong tool.
A TBox created by an LLM with no governance. Microsoft GraphRAG generates an emergent TBox from the data. For an exploratory corpus that works; for a regulated domain (finance, health, government) the TBox is not discovered, it is declared: FIBO, SNOMED, ENS. KAG is the right choice in those cases.
Forgetting KG maintenance when the corpus changes. New chunks introduce new entities. Without an entity reconciliation process (disambiguation, merging), the graph accumulates duplicates of the same entity under different IRIs and quality collapses quietly within six months. LightRAG has primitives for this; canonical GraphRAG requires periodic rebuilds.
A JSON Schema out of sync with the SHACL. If the ontology lives in RDF/SHACL and the structured outputs come from a hand-written JSON Schema, they drift apart. The right approach is to generate the JSON Schema from the SHACL with tools such as shacl-to-json-schema and regenerate it in CI every time the shape changes.
Neo4j Community licensed badly. GPLv3 means any modification you distribute has to be released under the same licence. If you are going to redistribute a product embedding Neo4j Community, check with legal or use an alternative with a more permissive licence (Memgraph BSL, Apache Jena for RDF, the Kùzu fork bighorn).
A compliance ontology not linked to the technical stack. Your ENS / ISO 42001 / EU AI Act mapping lives in a spreadsheet owned by the governance team. Your inventory of models, datasets and endpoints lives in another system. With no formal link between them, no stack change triggers the corresponding compliance review. The mapping goes into the graph, not into the spreadsheet.

Conclusion

An ontology is not an alternative to RAG; it is the nomenclature that makes its pieces comparable. Without it, the corpus is curated with ad-hoc categories, the embeddings drill through documents without being enriched, the evals measure the mean instead of the variance by class, the guardrail blocks on lists instead of types, incident response groups badly because each alert names things its own way, and compliance is a spreadsheet out of sync with the system. The six LLMOps stages are all better when they share a vocabulary, and sharing a vocabulary means formalising a small corporate ontology, aligned with the relevant vertical frameworks (FIBO, SNOMED, schema.org, ENS, EU AI Act), serialised in JSON-LD so the code consumes it without friction, validated with SHACL at every interface and queried with SPARQL when reasoning is needed. GraphRAG in its 2026 variants (Microsoft v2, LightRAG, HippoRAG 2, KAG) is a complementary lever, not the main course: the main course is the shared formal nomenclature. The rest, Neo4j vs Jena, OWL DL vs SKOS, GLiNER vs LLM-extractor, are technical decisions that resolve better once there is clarity about which nomenclature is needed. Linnaeus discovered this in 1735 and biology has not gone back; the LLM field is discovering it in 2026 and will not go back either.

References

W3C. RDF 1.1 Concepts and Abstract Syntax. https://www.w3.org/TR/rdf11-concepts/
W3C. OWL 2 Profiles (EL, QL, RL, DL). https://www.w3.org/TR/owl2-profiles/
W3C. SHACL — Shapes Constraint Language. https://www.w3.org/TR/shacl/
W3C. SKOS Reference. https://www.w3.org/TR/skos-reference/
W3C. JSON-LD 1.1. https://www.w3.org/TR/json-ld11/
W3C. SPARQL 1.1 Query Language. https://www.w3.org/TR/sparql11-query/
Edge et al. From Local to Global: A Graph RAG Approach to Query-Focused Summarization. Microsoft Research, 2024. https://arxiv.org/abs/2404.16130
Microsoft GraphRAG. https://github.com/microsoft/graphrag
Guo et al. LightRAG: Simple and Fast Retrieval-Augmented Generation. arXiv:2410.05779, 2024. https://arxiv.org/abs/2410.05779
Gutiérrez et al. HippoRAG: Neurobiologically Inspired Long-Term Memory for Large Language Models. NeurIPS 2024. https://arxiv.org/abs/2405.14831
Gutiérrez et al. From RAG to Memory: Non-Parametric Continual Learning for Large Language Models (HippoRAG 2). arXiv:2502.14802, 2025. https://arxiv.org/abs/2502.14802
Liang et al. KAG: Boosting LLMs in Professional Domains via Knowledge Augmented Generation. arXiv:2409.13731, 2024. https://arxiv.org/abs/2409.13731
OpenSPG / KAG. https://github.com/OpenSPG/openspg
EDM Council. Financial Industry Business Ontology (FIBO). https://spec.edmcouncil.org/fibo/
SNOMED International. https://www.snomed.org/
schema.org. https://schema.org/
Real Decreto 311/2022, de 3 de mayo, por el que se regula el Esquema Nacional de Seguridad. BOE-A-2022-7191. https://www.boe.es/eli/es/rd/2022/05/03/311
Reglamento (UE) 2024/1689 (EU AI Act). https://eur-lex.europa.eu/eli/reg/2024/1689
ISO/IEC 42001:2023 — Artificial Intelligence Management System. https://www.iso.org/standard/81230.html
Apache Jena. https://jena.apache.org/
Neo4j Cypher and AI procedures. https://neo4j.com/docs/
Protégé. https://protege.stanford.edu/
GLiNER. https://github.com/urchade/GLiNER
REBEL. https://github.com/Babelscape/rebel

Incident response runbooks for LLM inference: every alert to a concrete action with Kafka and Keep

Tue, 02 Jun 2026 04:30:00 +0200

This post closes the observability trilogy opened by GPU observability for LLM inference (which metrics) and Anatomy of the twelve DCGM and five vLLM metrics (which documented anomaly per metric). Here each anomaly gets its concrete action and is fitted into the incident management machinery that compliance demands.

TL;DR

The GPU observability alerts are useless without a codified procedure for each one; the operator who interprets them by hand every time is operating on intuition. The right combination has three indispensable pieces. (1) Runbook catalogue: for each of the six critical alerts (GpuHbmNearOom, GpuThermalOrPowerThrottle, GpuXidErrorDetected, GpuEccDoubleBit, VllmKvCachePoolNearFull, VllmTtftP95OutOfSlo), a severity, an immediate mitigation, the evidence to capture before remediating, a resolution action, a closure criterion and a postmortem trigger. (2) Reproducible pipeline: Prometheus + DCGM → Alertmanager → Kafka as event bus (topics gpu.alerts.enriched, incidents.lifecycle, audit.actions with WORM retention) → Keep as workflow engine (declarative YAML workflows versioned in git) → Kubernetes job / script / ChatOps executors. (3) Formal fit into incident management under the regulatory corpus: ISO/IEC 27035 phases identify → report → assess → respond → learn; ENS controls op.exp.7 (incident management), op.exp.8 (activity logging), op.exp.10 (notification to users); NIS2 art. 23 with an early warning at 24 h, a formal notification at 72 h and a final report at 1 month; EU AI Act art. 73 for a serious incident on a high-risk system, deadlines of 2 to 15 days depending on severity; ISO/IEC 42001 clause 10 (continual improvement of the AIMS). The action taxonomy is immediate mitigation (drain, throttle, scale-down: contains the damage in seconds) → diagnosis (evidence capture with nvidia-smi -q, dmesg, a vLLM /metrics snapshot, the related OTel trace; without this the postmortem is not defensible) → resolution (restart, reset, RMA, rollback) → postmortem (5-whys RCA, prevention plan, runbook update). Kafka contributes the immutable audit trail that ENS and the EU AI Act demand: every action executed by Keep or by a human is published as an event on audit.actions with timestamp, actor, decision and evidence, retained WORM for at least 6 months. Keep contributes workflows as code: this post includes three complete workflows (XID with drain plus Jira ticket, ECC DBE with immediate paging and node blocking in the scheduler, automatic canary rollback on TTFT P95 out of SLO). Four anti-patterns close the material: alerts without a runbook (most of them), a runbook without prior evidence capture (it perpetuates the incident because the root cause is lost), escalation by seniority rota instead of severity (a junior operator handling an ECC DBE), and the absence of a human gate for destructive actions (Keep running nvidia-smi --gpu-reset without confirmation). Applicable to a generic 4×H100 SXM cluster with Kafka and Keep already deployed.

You are here: OBSERVE → DEPLOY (incident response closes the loop)

The analogy: a nuclear reactor control room

In a nuclear plant control room, the operator on shift never decides what to do on seeing an alarm. The decision is pre-made and codified in a written procedure (SOP) covering every alarm on the panel: if X sounds, open book X, read steps 1-N, execute exactly, call the supervisor at step M, escalate to the plant director at step N+3. The reason is strict: critical alarms are rare but catastrophic if handled badly; an operator improvising in an emergency makes worse decisions than one applying a procedure reviewed by experts and validated by simulation.

The reactor does not expect the operator to be a genius. It expects them to know the procedures to the letter and the operations management system to hand them the right procedure at the right moment. If the procedures are not written, not versioned, or not integrated with the alarms that fire them, the control room is operating on intuition. The difference between the two operations, procedural versus intuitive, is the difference between a plant that runs 30 years without incidents and one that ends up on a blacklist.

Incident response on an LLM inference cluster works identically. The DCGM and vLLM alerts listed in the previous posts are the panel alarms. Each one needs its written SOP, versioned, integrated with the alert that fires it and reviewed after every incident. Without that codification, the operator on shift improvises in the middle of an ECC DBE failure at 4 in the morning; with it, they execute the nine steps of runbook 12 and the incident closes in 20 minutes.

The incident pipeline architecture

Prometheus + DCGM. Collects the metrics described in the two previous posts. PrometheusRules define the six critical alerts with for: <duration> to avoid noise.

Alertmanager. Receives raw alerts; deduplicates, groups by labels ({cluster, node, gpu, model}), routes. Instead of sending straight to PagerDuty or Slack, it sends to Kafka via a webhook receiver. That turns the alert into a bus event that multiple consumers process (Keep for action, the audit topic for compliance, dashboards for visualisation).

Kafka as event bus. Three canonical topics:

gpu.alerts.enriched — alerts with added context (tenant, model, version, namespace owner, effective severity). Retention: 7 days, replication factor 3.
incidents.lifecycle — incident cycle events: incident.opened, incident.acknowledged, action.proposed, action.executed, incident.escalated, incident.resolved, postmortem.attached. Retention: 90 days.
audit.actions — an immutable record of every action executed (by Keep automatically or by a human confirming). Retention: 6 months minimum with compaction off plus tiered storage, WORM storage. This is the topic ENS op.exp.8, EU AI Act art. 12 and NIS2 require you to keep.

Keep as workflow engine. Consumes from gpu.alerts.enriched, fires YAML workflows versioned in git, executes actions (HTTP calls, kubectl jobs, Slack messages, Jira tickets) and publishes the result to incidents.lifecycle plus audit.actions. Choosing Keep over Alertmanager alone (or over PagerDuty alone) is deliberate: Keep separates runbook declaration (readable, reviewable YAML) from notification delivery (PagerDuty). The runbook is versioned code; notifications are operational details.

Executors. What actually moves the cluster:

Kubernetes jobs: kubectl drain, kubectl cordon, kubectl rollout undo.
NVIDIA API: nvidia-smi --gpu-reset, dcgmi diag -r <level>.
ChatOps: human confirmations through Slack interactive messages before a destructive action runs.
External tooling: Jira ticket, PagerDuty notification, CMDB call.

The six critical alerts and their runbooks

For each alert: severity, immediate mitigation (seconds), evidence to capture before remediating, resolution action, closure criteria, postmortem trigger.

RB-01 · `GpuHbmNearOom` — HBM > 92 % sustained

Severity: WARNING. Risk of OOM on the next PagedAttention allocation.

Immediate mitigation. Reduce admission temporarily by lowering max_num_seqs on the affected engine via hot reload (if the engine supports it) or a staggered restart of replicas. Trigger an additional scale-out via KEDA if there are free GPU nodes. There is no need to drain the node.

Evidence to capture.

nvidia-smi --query-gpu=index,memory.used,memory.free,memory.total --format=csv
nvidia-smi -q -d ROW_REMAPPER | grep -i pending
curl http://vllm-pod:8000/metrics | grep -E "gpu_cache_usage|num_requests"
kubectl logs <pod> --tail=200 | grep -i "preempt\|swap"

Save the snapshot to audit.actions with a timestamp and an incident_id.

Resolution. If the cause is a traffic spike: let the autoscaler scale to a stable regime, monitor for 30 min. If the cause is a model regression (canary v2 consumes more KV cache than v1): roll the canary back (see RB-06). If it is a leak (the metric grows without traffic growing): restart the pod with a heap dump capture.

Closure. gpu_cache_usage_perc < 80 % sustained for 15 min AND num_requests_waiting == 0.

Postmortem. Not mandatory unless the incident lasted > 30 min or had SLO impact.

RB-02 · `GpuThermalOrPowerThrottle` — bit ≠ 0 and not Idle in CLOCK_THROTTLE_REASONS

Severity: WARNING (thermal) or CRITICAL (sustained HW Power Brake, PDU risk).

Immediate mitigation. Identify the bit (decode the bitmap). If it is 0x40 HW_THERMAL or 0x20 SW_THERMAL: drain the workload from the node to other replicas if the temperature does not drop within 2 min, and stop new pods landing on that node (kubectl cordon). If it is 0x80 HW_POWER_BRAKE: alert DC infrastructure immediately (likely an over-committed PDU, the Dell KB 000220508 / Lenovo HT514380 case) and lower the TDP of the rack’s GPUs via nvidia-smi -pl to a lower value to relieve load on the breaker.

Evidence.

nvidia-smi --query-gpu=index,temperature.gpu,temperature.memory,power.draw,clocks_throttle_reasons.active --format=csv
ipmitool sdr | grep -i "fan\|temp\|inlet"
# PDU data if they are instrumented (modbus / SNMP)

Resolution.

Thermal: review rack airflow, check the rear-door HX, T_inlet, DGX fans. An infra issue, not an engine one.
Power Brake: review the sizing of the PDU branch, the breaker, the 415 VAC distribution. Likely a redistribution of load to another branch or a temporary TDP cap.

Closure. CLOCK_THROTTLE_REASONS == 0x1 (Idle only) or 0x0 for 30 min under normal load.

Postmortem. Mandatory if it was a HW Power Brake: that implicates the DC electrical infrastructure.

RB-03 · `GpuXidErrorDetected` — `increase(DCGM_FI_DEV_XID_ERRORS[5m]) > 0`

Severity: CRITICAL.

Immediate mitigation. kubectl cordon the node (no more new pods). If the XID is 31/48/79/94/95 (hardware or cascade): drain the node’s existing pods. If the XID is 13/43 (possibly software): keep the pods but block new ones, capture the trace and the active workload.

Evidence.

# The specific XID from dmesg
dmesg | grep -i xid | tail -30
nvidia-smi -q -d ERROR
nvidia-smi -q -d PCIE
# State of the retired pages
nvidia-smi -q -d ROW_REMAPPER
# Workload that was running
kubectl get pods -o wide | grep <node>
kubectl logs <pod> --previous --tail=500

Resolution.

XID 13/43 (software exception / channel verif): if it recurs only with one specific model, it is a workload bug; raise an issue with the model team. If it is transient, restarting the pod is enough.
XID 31 (MMU fault): usually a cascade from a previous XID 48. Reset the GPU (nvidia-smi --gpu-reset -i <index>) or reboot the node if the reset does not resolve it.
XID 48 / 95 (DBE / uncontained ECC): see RB-04. The node goes into quarantine.
XID 79 (fallen off the bus): reboot the node. If it recurs after the reboot, open an RMA for the GPU. ByteDance reports 43 % co-occurrence with PCIe errors, so check the slot and the cable too.
XID 94 / 145 / 149: catalogued in NVIDIA’s Xid Catalog with a specific procedure.

Closure. Node smoke test passed (dcgmi diag -r 3), 24 h with no new XIDs, back into the pool.

Postmortem. Mandatory. Include the specific XID, the distribution of XIDs across the cluster, an updated MTBE.

RB-04 · `GpuEccDoubleBit` — `DCGM_FI_DEV_ECC_DBE_VOL_TOTAL > 0`

Severity: CRITICAL, data corruption in progress.

Immediate mitigation. Drain the node immediately without waiting for further evidence. Page (PagerDuty / OpsGenie) the primary ON-CALL. Mark the node unschedulable and failed. XID 48 has a 100 % probability of killing the running job according to the Story of Two GPUs dataset; any inference already in flight is compromised.

Evidence (in parallel with the mitigation).

nvidia-smi -q -d ECC
nvidia-smi -q -d ROW_REMAPPER # Pending: Yes expected
dmesg | grep -E "Xid.*48|DBE|double-bit" | tail -50
# Full capture of the GPU state
dcgmi diag -r 4 -i <gpu_index>

Resolution. Full GPU reset (nvidia-smi --gpu-reset) or a node reboot if the reset does not complete. The reset activates the row remap. After the reboot:

nvidia-smi -q -d ROW_REMAPPER # Pending: No expected
nvidia-smi -q -d ECC # volatile counters at 0

If RETIRED_DBE > 8 pages after the remap: schedule a GPU replacement in the next window, because silicon degradation is progressive. The published real case documents ~19 hours of downtime as typical.

Closure. Node back in the pool after 48 h with no new DBEs.

Postmortem. Mandatory. If the incident affected a request carrying personal or classified data, evaluate notification to the DPO under GDPR art. 33 (it is not necessarily a breach, but it has to be assessed).

RB-05 · `VllmKvCachePoolNearFull` — `gpu_cache_usage_perc > 95 %` sustained 3 min

Severity: WARNING (risk of preempt-on-OOM, not of a real OOM).

Immediate mitigation. Activate autoscaler scale-out by lowering the KEDA threshold temporarily (from 0.85 to 0.75) for 30 min. In recompute mode, preempts raise TTFT but do not break requests; acceptable in the short term. In swap mode latency goes through the roof, so it is better to cut new traffic (return 503 from the router) for 5 min.

Evidence.

curl http://vllm-pod:8000/metrics | grep -E "gpu_cache|num_requests|num_preemptions"
kubectl get hpa vllm-llama70b
kubectl logs <pod> --tail=200 | grep -i preempt

Resolution. If it recurs regularly: revisit capacity planning, possibly lowering max_num_seqs or raising the stable replica count. See Capacity planning.

Closure. Pool < 85 % sustained 30 min, no preempts in the last 15 min.

Postmortem. Not mandatory unless it recurs > 3 times / week.

RB-06 · `VllmTtftP95OutOfSlo` — TTFT P95 > 1.5 s for 5 min

Severity: CRITICAL (contractual SLO violation).

Immediate mitigation. Quick diagnosis of the regime (in order of likelihood):

If a v2 canary is active and the ratio ttft_p95(v2)/ttft_p95(v1) > 1.30: automatic rollback of the canary via Argo Rollouts (argo rollouts abort vllm-llama70b).
If num_requests_waiting > 5: scale out via KEDA.
If DRAM_ACTIVE > 90 % plus gpu_cache_usage_perc > 90 %: HBM bottleneck, reach for the quantisation lever or a context reduction.
If CLOCK_THROTTLE_REASONS != 0: see RB-02.

Evidence.

# Histogram snapshot
curl http://vllm-pod:8000/metrics | grep time_to_first_token
# Breakdown by version if a canary is running
# DCGM state at that moment
curl http://dcgm-exporter:9400/metrics | grep -E "PIPE_TENSOR|DRAM_ACTIVE|THROTTLE"
# Active traffic
kubectl top pods -n inference

Resolution. Depends on the diagnosis. Typical cases:

Canary regression → full rollback (see Canary).
Capacity saturation → scale replicas or accept a temporary 503 with Retry-After.
Prefill bound → enable or calibrate chunked prefill or disaggregated serving (see Disaggregated serving).

Closure. TTFT P95 inside SLO sustained 30 min.

Postmortem. Mandatory. Document the root cause and the lever applied; update the runbook.

Keep YAML workflows — three complete examples

Runbooks are only useful if they are codified in the workflow engine. Keep lets you declare them in YAML versioned in git.

Workflow 1 — `xid-detected.yaml`

workflow:
 id: xid-detected-drain
 name: "XID error detected — cordon node and capture evidence"
 description: "RB-03 implementation"
 triggers:
 - type: alert
 filters:
 - key: alertname
 value: GpuXidErrorDetected
 steps:
 - name: capture-evidence
 provider:
 type: bash
 with:
 command: |
 set -e
 NODE="{{ alert.labels.node }}"
 GPU="{{ alert.labels.gpu }}"
 INC_ID="{{ alert.fingerprint }}"
 mkdir -p /var/evidence/$INC_ID
 kubectl debug node/$NODE -it --image=nvcr.io/nvidia/cuda:12.4.0-base-ubuntu22.04 -- \
 bash -c "nvidia-smi -q -d ERROR,PCIE,ROW_REMAPPER > /host/var/evidence/$INC_ID/smi.txt"
 kubectl describe node $NODE > /var/evidence/$INC_ID/node.txt
 - name: cordon-node
 provider:
 type: kubernetes
 with:
 action: cordon
 name: "{{ alert.labels.node }}"
 if: "{{ alert.labels.severity == 'critical' }}"
 actions:
 - name: open-jira-ticket
 provider:
 type: jira
 config: "{{ providers.jira-prod }}"
 with:
 project: GPUOPS
 issuetype: Incident
 summary: "RB-03: XID {{ alert.annotations.xid_code }} on {{ alert.labels.node }}/{{ alert.labels.gpu }}"
 description: |
 Severity: {{ alert.labels.severity }}
 XID: {{ alert.annotations.xid_code }}
 Evidence: /var/evidence/{{ alert.fingerprint }}
 Runbook: https://runbooks.example.local/RB-03
 - name: notify-slack
 provider:
 type: slack
 config: "{{ providers.slack-gpu-incidents }}"
 with:
 message: |
 :warning: *RB-03 triggered*
 Node: `{{ alert.labels.node }}` GPU: `{{ alert.labels.gpu }}`
 XID: `{{ alert.annotations.xid_code }}`
 <{{ jira.url }}|Jira ticket>
 - name: emit-audit
 provider:
 type: kafka
 config: "{{ providers.kafka-audit }}"
 with:
 topic: audit.actions
 message:
 incident_id: "{{ alert.fingerprint }}"
 action: "cordon_node"
 actor: "keep-workflow"
 workflow_id: "xid-detected-drain"
 target: "{{ alert.labels.node }}"
 timestamp: "{{ now }}"

Workflow 2 — `ecc-dbe.yaml` — immediate paging

workflow:
 id: ecc-dbe-critical
 name: "ECC double-bit — page on-call and quarantine node"
 triggers:
 - type: alert
 filters:
 - key: alertname
 value: GpuEccDoubleBit
 steps:
 - name: cordon-immediately
 provider:
 type: kubernetes
 with:
 action: cordon
 name: "{{ alert.labels.node }}"
 - name: drain-workload
 provider:
 type: kubernetes
 with:
 action: drain
 name: "{{ alert.labels.node }}"
 options:
 ignore-daemonsets: true
 delete-emptydir-data: true
 grace-period: 120
 - name: page-oncall
 provider:
 type: pagerduty
 config: "{{ providers.pagerduty-critical }}"
 with:
 service_key: "{{ env.PD_SERVICE_KEY }}"
 severity: critical
 summary: "RB-04 ECC DBE on {{ alert.labels.node }}/{{ alert.labels.gpu }} — node drained"
 - name: emit-lifecycle
 provider:
 type: kafka
 config: "{{ providers.kafka-incidents }}"
 with:
 topic: incidents.lifecycle
 message:
 incident_id: "{{ alert.fingerprint }}"
 event: incident.opened
 severity: critical
 runbook: RB-04
 requires_postmortem: true
 - name: notify-dpo
 provider:
 type: email
 with:
 to: dpo@example.local
 subject: "ECC DBE on a production GPU — assessment required"
 body: |
 RB-04 ECC DBE incident detected on {{ alert.labels.node }}.
 Affected model: {{ alert.labels.model }}.
 Please assess whether personal/classified data was processed
 during the error window and whether GDPR art. 33 notification is needed.

Workflow 3 — `canary-rollback.yaml` — TTFT P95 out of SLO

workflow:
 id: canary-rollback-ttft
 name: "Rollback canary when TTFT P95 ratio v2/v1 > 1.30"
 triggers:
 - type: alert
 filters:
 - key: alertname
 value: VllmTtftP95OutOfSlo
 - key: canary_active
 value: "true"
 steps:
 - name: check-ratio
 provider:
 type: prometheus
 config: "{{ providers.prom-prod }}"
 with:
 query: |
 histogram_quantile(0.95, sum by(le)(rate(vllm:time_to_first_token_seconds_bucket{version="v2"}[5m])))
 /
 histogram_quantile(0.95, sum by(le)(rate(vllm:time_to_first_token_seconds_bucket{version="v1"}[5m])))
 condition: result > 1.30
 actions:
 - name: argo-rollback
 provider:
 type: kubernetes
 with:
 action: exec
 command:
 - kubectl
 - argo
 - rollouts
 - abort
 - "{{ alert.labels.rollout }}"
 - -n
 - "{{ alert.labels.namespace }}"
 - name: notify-and-audit
 provider:
 type: kafka
 config: "{{ providers.kafka-audit }}"
 with:
 topic: audit.actions
 message:
 incident_id: "{{ alert.fingerprint }}"
 action: canary_rollback
 ratio: "{{ steps.check-ratio.result }}"
 actor: keep-workflow
 timestamp: "{{ now }}"

Each workflow lives in repos/keep-workflows/ versioned in git, reviewed by pull request, validated by CI (keep workflow validate). The written runbook lives as docs/runbooks/RB-XX.md linked from the workflow YAML; the two always evolve together.

The canonical Kafka event schema

For the topics to be consumable by compliance, postmortem tooling and dashboards without each consumer having to guess the shape, the schema is fixed with Avro / Protobuf.

{
 "name": "IncidentLifecycleEvent",
 "type": "record",
 "fields": [
 { "name": "incident_id", "type": "string" },
 { "name": "event", "type": { "type": "enum", "symbols": [
 "incident.opened", "incident.acknowledged", "action.proposed",
 "action.executed", "action.failed", "incident.escalated",
 "incident.resolved", "postmortem.attached"
 ]}},
 { "name": "timestamp", "type": "string", "logicalType": "timestamp-millis" },
 { "name": "actor", "type": "string" },
 { "name": "severity", "type": { "type": "enum", "symbols": ["low","warning","critical"] } },
 { "name": "runbook", "type": ["null","string"], "default": null },
 { "name": "alert_name", "type": "string" },
 { "name": "labels", "type": { "type": "map", "values": "string" } },
 { "name": "annotations", "type": { "type": "map", "values": "string" } },
 { "name": "evidence_uri", "type": ["null","string"], "default": null },
 { "name": "requires_postmortem", "type": "boolean", "default": false }
 ]
}

For audit.actions (WORM), a separate and stricter schema with non-modifiable fields:

{
 "name": "AuditAction",
 "type": "record",
 "fields": [
 { "name": "incident_id", "type": "string" },
 { "name": "action", "type": "string" },
 { "name": "actor", "type": "string" },
 { "name": "actor_type", "type": { "type": "enum", "symbols": ["human","workflow","scheduler"] } },
 { "name": "workflow_id", "type": ["null","string"], "default": null },
 { "name": "target", "type": "string" },
 { "name": "command", "type": ["null","string"], "default": null },
 { "name": "result", "type": { "type": "enum", "symbols": ["success","failure","partial"] } },
 { "name": "timestamp", "type": "string", "logicalType": "timestamp-millis" },
 { "name": "evidence_uri", "type": ["null","string"], "default": null },
 { "name": "approver", "type": ["null","string"], "default": null }
 ]
}

The topic is configured with cleanup.policy=delete, retention.ms=15552000000 (6 months) and min.insync.replicas=2 with acks=all to guarantee durability. For longer retention without the Kafka cost, use tiered storage to Ceph RGW or an S3-compatible backend: new log in the hot tier, old log in the cold tier, transparently to the consumer.

Formal fit into incident management

Runbooks are not an isolated SRE practice. They fit into four regulatory frameworks that production LLM platforms touch daily.

ISO/IEC 27035 — information security incident management

It defines the formal cycle in five phases: plan & prepare → detect & report → assess & decide → respond → lessons learned. Each phase has outputs that must be documented. Translated to the stack:

Plan & prepare: runbooks RB-01 to RB-06 plus the Keep workflows are part of the Information Security Incident Management Plan. Versioned in git, reviewed annually.
Detect & report: the Prometheus alerts entering Kafka are the materialisation.
Assess & decide: the severity in gpu.alerts.enriched plus the Keep workflow logic.
Respond: execution of the workflow’s steps plus actions.
Lessons learned: a mandatory postmortem for the runbooks that flag it; the output documented in the postmortem repo plus the runbook update.

ENS (Esquema Nacional de Seguridad) — op.exp controls

op.exp.7 Incident management: the runbook catalogue plus the Keep / Kafka pipeline materialise the “organised and procedural response”.
op.exp.8 Activity logging: the audit.actions topic with WORM retention of 6 months (minimum for level ALTO).
op.exp.9 Incident management logging: the incidents.lifecycle topic with the full cycle of each incident.
op.exp.10 Protection of activity logs: WORM plus encryption at rest plus access control (compliance consumers read-only).

NIS2 — notification to the competent authority

For essential and important entities, art. 23 sets three deadlines from the detection of significant impact:

24 hours: an early warning to the national CSIRT (INCIBE-CERT in Spain).
72 hours: a formal notification with an initial assessment.
1 month: a final report with root cause, impact and corrective measures.

The data for those reports comes straight out of incidents.lifecycle plus audit.actions with a consumer that generates the dossier in the required format. Without the auditable pipeline, the NIS2 deadlines are unreachable.

EU AI Act — art. 73 (serious incident reporting)

Applicable to high-risk systems. Deadlines:

2 days: for incidents causing death or irreversible harm to people or critical infrastructure.
10 days: for incidents producing serious disruption of critical infrastructure.
15 days: for all other “serious incidents”.

The definition of “serious incident” includes systematic model failures, a fundamental rights breach, material or environmental harm. Runbooks must flag which alerts can lead to a serious incident (typically anything affecting the model’s output in a high-risk context) and fire a specific legal assessment sub-workflow.

ISO/IEC 42001 — AIMS clause 10 continual improvement

The mandatory post-incident postmortem feeds clause 10. Updating the runbook after every incident that reveals a new pattern is the “corrective action with verification of effectiveness” the standard demands. See ISO 42001 AIMS.

Four anti-patterns

Anti-pattern 1 — alerts without a runbook. The alert fires, the junior operator on call looks at the dashboard, searches Confluence, finds nothing up to date, calls the senior on Slack, waits 20 minutes. In that time the incident has grown. Rule: no alert goes to production without a published runbook and an approved Keep workflow. CI validates that every PrometheusRule with severity ≥ warning has its corresponding keep workflow.

Anti-pattern 2 — a runbook without prior evidence capture. The workflow runs nvidia-smi --gpu-reset as soon as the XID arrives, losing the state that would have diagnosed the root cause. The next identical XID forces the diagnosis to be redone from scratch. Rule: steps before actions; all evidence is captured first, destructive actions come after.

Anti-pattern 3 — escalation by seniority rota instead of severity. The junior operator on call handles an ECC DBE because “it is their turn”. They lack the context to understand row remap, retired pages or the data corruption risk. Rule: page by severity, not by rota: RB-04 and RB-03 page the senior primary ON-CALL with automatic escalation to infra/hardware if there is no acknowledgement within 10 min.

Anti-pattern 4 — no human gate for destructive actions. The workflow runs kubectl drain automatically on any alert marked CRITICAL. On the first false alarm (a transient that resolved itself in 30 s), Keep drained a production node during peak hour. Rule: destructive actions (drain, reset, RMA, full rollback) require human confirmation via a Slack interactive message, with a configurable timeout. A justified exception: ECC DBE confirmed by > 1 measurement, where the corruption risk outweighs the false alarm risk.

Applied to typical on-premise hardware

For a generic cluster of 4 nodes × 4×H100 SXM 80 GB with Kafka and Keep already deployed:

Kafka: a 3-broker cluster on non-GPU nodes of the K8s cluster; topics gpu.alerts.enriched, incidents.lifecycle, audit.actions configured with replication factor 3, min.insync.replicas 2. Audit with tiered storage to Ceph RGW for retention > 6 months without a brutal cost.
Keep: 2 operator replicas plus 1 worker replica in a keep namespace; connected to Prometheus (read provider), Kafka (read plus write provider), Slack, PagerDuty, Jira, Kubernetes (provider with a dedicated SA holding get/list/patch nodes and create jobs permissions).
Workflows: ~25-40 YAML files in the infra/keep-workflows/ repo, synchronised with the cluster via Flux or Argo CD. Validated by CI (keep workflow validate) on every PR.
Event volume: for 16 GPUs in normal operation with debounced alerts, ~50-200 events/day on gpu.alerts.enriched. In a typical incident, peaks of 500-2,000 events/day.
Compliance consumers: a python consumer in the compliance namespace that generates NIS2 / ENS / EU AI Act reports weekly, reading audit.actions and incidents.lifecycle.

What we have not covered (upcoming posts)

Postmortem playbooks — the mechanics of RCA with 5-whys, Ishikawa adapted to LLMs, integration with MLflow tracking for re-training if the postmortem produces an enriched dataset.
Chaos engineering for LLMs — controlled injection of XID errors, simulated ECC, artificial HBM latency to validate runbooks before the real incident.
Multi-cluster incident coordination — how to coordinate Keep across geographic clusters when an incident affects multiple regions.
CMDB and procurement integration — the RMA → ticket → ServiceNow → hardware replacement cycle automated via workflow.
LLM forensics — extracting the full OTel trace of a request affected by an incident, with redacted PII, kept in an evidence vault.

References

ISO/IEC 27035-1:2023 — Information security incident management — Principles and process.
ISO/IEC 27035-2:2023 — Information security incident management — Guidelines to plan and prepare for incident response.
ENS — Real Decreto 311/2022, Anexo II controles op.exp.7 a op.exp.10.
Directiva NIS2 (UE 2022/2555) — art. 23 (notificación de incidentes significativos).
Reglamento EU AI Act (UE 2024/1689) — art. 73 (reporting of serious incidents).
ISO/IEC 42001:2023 — AI management system — cláusula 10 (mejora continua).
Keep project — keephq.dev y github.com/keephq/keep (documentación de workflows YAML, providers).
Apache Kafka — Tiered Storage y cleanup.policy (docs.confluent.io / kafka.apache.org).
Confluent — Schema Registry y best practices para eventos lifecycle.
NVIDIA — Xid Errors Documentation y procedimientos de remediación.
Google SRE Book — Effective Troubleshooting y Postmortem Culture.
Atlassian — Incident Management Handbook (referencia para severity matrices).

Technical controls: the ENS × ISO 42001 × EU AI Act cross-mapping over the on-premise LLM architecture

Mon, 01 Jun 2026 06:30:00 +0200

Third post in the blog’s AI governance trilogy. The first, ISO/IEC 42001, broke down the certifiable management system. The second, EU AI Act, broke down the directly applicable legal regulation. This one covers the third framework that appears when the client is a Spanish public administration or an essential-services entity: the ENS (Esquema Nacional de Seguridad, Spain’s national security framework, Royal Decree 311/2022). The editorial challenge: triple compliance is not the arithmetic sum of three jobs; it is one single set of technical evidence labelled for three lenses. This post takes apart how that evidence is built, measure by ENS measure.

TL;DR

Royal Decree 311/2022 updated the Spanish Esquema Nacional de Seguridad (ENS), aligning it with NIS2 and with the modern cyber-threat landscape. It applies mandatorily to the entire Spanish public sector (central, regional and local administration, universities, autonomous bodies) and to suppliers that provide IT services to them. The framework defines 74 security measures organised into three blocks (organisational framework org, operational framework op, protection measures mp), three application categories (Basic / Medium / High) according to the assessment of five dimensions (Confidentiality, Integrity, Traceability, Authenticity, Availability), and an Annex II with the measure × category matrix that dictates what is required at each level. This post maps the technical measures relevant to LLM systems (those of the op block: planning, access control, operation, external services, continuity, monitoring; and those of the mp block: communications, applications, information, services) against Annex A of ISO/IEC 42001 and the operational articles of the EU AI Act (Arts. 9 to 15, 17, 72 and 73), and shows that the overlap is massive: a single technical artefact from the blog’s OSS stack, the OTel spans of tracing, the datasets versioned with DVC, the LLM Guard scanners, the guardrail decisions, the incidents of the retrain loop, simultaneously satisfies ENS measures, 42001 controls and AI Act articles, provided it is labelled with the correct codes from the moment it is captured. The editorial thesis: the difference between a system that passes all three audits and one that suffers three separate certifications is not budget, it is disciplined labelling and a common vocabulary. The post builds the master table of triple compliance, walks through the case of the multi-tenant chatbot for a High-category public administration as a live checklist, and closes with the five traps of triple compliance.

The analogy: the triple inspection of a critical building

A critical building, say the control centre of a regional electricity grid, a reference hospital, or a 112 emergency response centre, goes through three different inspections of the same physical elements:

The regional inspection reviews the planning permit, local fire regulations and accessibility under regional legislation.
The European inspection reviews CE marking of equipment and conformity with EU directives on energy efficiency.
The ISO quality inspection reviews processes and maintenance under a management standard.

All three inspectors look at the same fire detector hanging from the ceiling. The regional one wants to see the installation certificate with the installer company’s number; the European one wants to see the CE mark stamped on the casing; the ISO one wants to see the monthly maintenance record with signatures. There is only one detector. The evidence each inspector needs is different. If the building management team kept one folder per inspector, the installation certificate, the photo of the CE mark and the maintenance sheet would live in three places, and on audit day inconsistencies between the three folders would surface. The professional way to operate: one single file per asset, with tags pointing at the three sets of legislation.

The on-premise LLM system is that critical building. The OTel spans from tracing are the fire detector: a single technical piece that satisfies ENS measure op.exp.8 (activity logging), 42001 control A.8.2 (information to interested parties), and EU AI Act article 12 (record-keeping) provided the spans carry the correct metadata: traceparent propagated, gen_ai.* semantic conventions, WORM retention, PII redacted by LLM Guard Vault. Without consistent labelling from capture onwards, audit day produces three folders that do not add up.

The analogy matters because it bounds an architectural decision: labelling evidence is not a compliance topic, it is a technical design topic. It is decided when the OTel Collector is set up, when the Vault schema is designed, when the format of retrain incidents is agreed. Postpone it, and the debt compounds.

ENS in 15 seconds

Regulatory framework: Royal Decree 311/2022, of 3 May, in force since 5 May 2022. It replaces RD 3/2010. It implements the update of the Esquema with NIS2, the NCS (Estrategia Nacional de Ciberseguridad, Spain’s national cybersecurity strategy) and the post-2020 reality.
Mandatory scope: the Spanish public sector (central, regional and local administration, universities, autonomous bodies), public-sector entities with their own legal personality, and private suppliers that provide IT services to them (a very important clause in consultancy: if your client is the Junta de Andalucía, the Comunidad de Madrid or Bilbao City Council, you fall under ENS by contractual extension).
Operational applicability in 2026: any AI project financed with NextGenerationEU European funds, plus any project with public data, plus any integration with electronic administrative systems.
Categorisation: three categories, Basic / Medium / High, according to the assessment of the five dimensions (C, I, T, A, D). The category dictates which measures are required and at what depth.
Certification: for Medium and High categories, a formal audit by an accredited body. For Basic category, self-assessment. Certification cycle is biennial.
Authority: the Centro Criptológico Nacional (CCN-CERT, Spain’s national cryptologic centre), part of the CNI intelligence agency. It maintains the ens.ccn.cni.es portal with the STIC guides (800 series).
Total number of measures: 74, organised into three blocks, plus Annex II with the measure × category matrix that defines what applies at each level.

The five security dimensions and their AI mapping

To classify the system as Basic / Medium / High, the ENS requires each dimension to be rated on a scale (not applicable / low / medium / high). The final category is the highest of the five. For LLM systems, the typical rating:

Dimension	Meaning	Typical LLM rating	Reason
C Confidentiality	Information protected from disclosure	Medium-High	PII in prompts, secrets in context, intellectual property in the RAG corpus
I Integrity	Information protected from modification	Medium-High	An altered RAG corpus produces false answers; a manipulated model produces directed bias
T Traceability	Actions attributable to users	High	Audit: who asked what, when, what were they answered, which dataset trained the model?
A Authenticity	Identity of users and origin of information	Medium	Robust authentication plus identification of chunks by source
D Availability	Service available when needed	Medium	Typical SLA, known recovery time

Typical result: Medium category for internal LLM systems with no sensitive data, High if they handle PII or regulated sectoral data (health, tax, judicial). The category triggers different controls.

The three blocks of measures

Organisational framework (org), 4 measures that always apply, transversal:

org.1 Security policy
org.2 Security regulations
org.3 Security procedures
org.4 Authorisation process

Operational framework (op), 31 measures in 6 subgroups, these are how it is operated:

op.pl Planning (5)
op.acc Access control (6)
op.exp Operation (10)
op.ext External services (4)
op.cont Service continuity (4)
op.mon System monitoring (2)

Protection measures (mp), 39 measures in 7 subgroups, these are what is protected:

mp.if Facility protection (7)
mp.per Personnel management (4)
mp.eq Equipment protection (4)
mp.com Communications protection (4)
mp.si Information media protection (5)
mp.sw Application protection (2)
mp.info Information protection (6)
mp.s Service protection (4)

Of those 74, roughly 25 matter operationally for LLM systems. The rest are either transversal (policies, personnel management, physical facilities) or specific to other layers (telephony, physical media in the literal sense). The rest of this post drops down to the 25 relevant ones.

Technical mapping: key ENS measures × 42001 controls × EU AI Act articles

What follows, by ENS subgroup, are the measures relevant to LLM with their cross-mapping. The Technical evidence from the blog column points to the operational artefact that materialises the measure.

Operational framework — planning (`op.pl`)

ENS measure	Requirement	42001 control	AI Act article	Technical evidence
`op.pl.1` Risk analysis	Formal periodic analysis, MAGERIT or OCTAVE methodology	A.5.4 (alignment with AI risk treatment)	Art. 9 Risk management	Risk document linked to the LLMOps pipeline + evals metrics
`op.pl.2` Security architecture	Architecture documentation, layer segregation	A.4.2 documented info	Art. 15 (technical robustness)	Seven stack layers + seven deployment phases
`op.pl.3` Acquisition	Acquisition criteria that include security	A.10.3 suppliers	Art. 53 (GPAI obligations)	OSS vs hyperscalers lock-in analysis + copyright analysis
`op.pl.4` Sizing	Capacity to support the expected load	A.4.5 system resources	Art. 15 (consistent performance)	Five maturity levels + GPU capacity study
`op.pl.5` Certified components	Preference for certified components	A.10.5 third parties	Art. 53 + Art. 15	OSS inventory with licence analysis + supply chain audit (cosign + SLSA)

Operational framework — access control (`op.acc`)

ENS measure	Requirement	42001 control	AI Act article	Technical evidence
`op.acc.1` Identification	Unique identification of users and processes	A.3.2 roles	Art. 14 (human oversight)	Keycloak / OIDC + JWT with unique `sub` + `user_id_hashed` in OTel spans
`op.acc.2` Access requirements	Need to know, authorisation	A.9.4 intended use	Art. 14 + Art. 26 (deployer)	Per-tenant allowlist in the AI Gateway + RBAC over adapters
`op.acc.3` Segregation of duties	No incompatible accumulation	A.3.2 + A.3.3	Art. 17 (QMS)	Separate roles: AI lead / data steward / SRE / DPO
`op.acc.5` Authentication	Proportionate mechanism, MFA at High	A.4.4 tooling	Art. 14	Keycloak + WebAuthn + mandatory MFA for High category
`op.acc.6` Local access	Protection against physical access	mp.if + A.4.5	Art. 15 (cybersec)	Cluster in a datacenter with physical control (strictly outside the blog’s scope)
`op.acc.7` Remote access	VPN, encryption, endpoint control	A.4.5 + mp.com	Art. 15	WireGuard / Defguard + mTLS for administrative access to the cluster

Operational framework — operation (`op.exp`)

This is the densest subgroup and the one that overlaps most with the LLM architecture.

ENS measure	Requirement	42001 control	AI Act article	Technical evidence
`op.exp.1` Asset inventory	CMDB with all system components	A.4 resources	Art. 49 (EU DB registration)	Inventory of models, adapters and datasets in a CMDB + Helm tags + OpenLineage lineage
`op.exp.2` Security configuration	Documented hardened configuration	mp.eq + A.4	Art. 15	vLLM, KServe and Cilium configurations documented in GitOps + CIS Benchmarks for K8s
`op.exp.3` Configuration management	Traceable and authorised changes	A.6.2 + A.4.2	Art. 9 + Art. 15	GitOps with Argo CD / Flux + mandatory PR review + immutable tags
`op.exp.5` Change management	Changes planned, authorised, recorded	A.6.2.6 + clause 8	Art. 9 (lifecycle) + Art. 72 (post-market)	CI/CD pipeline from the LLMOps post + change advisory board
`op.exp.6` Protection against malicious code	Antivirus, EDR, malware control	mp.eq	Art. 15 (cybersec)	Image scanning (Trivy / Grype) + container runtime security (Falco / Tetragon)
`op.exp.7` Incident management	Detection → response → recovery procedure	A.3.3 + clause 10	Art. 73 (serious incident reporting)	Incident-driven retrain + CCN-CERT channel + notification template
`op.exp.8` Activity logging	Auditable logs, minimum 2-year retention at High category	A.8.2	Art. 12 + Art. 19	OTel GenAI tracing + Tempo / Jaeger + Loki
`op.exp.9` Incident management records	Incident log with root cause and corrective action	clause 10	Art. 73	Ticketing system + structured retrain incident events
`op.exp.10` Record protection	Immutable logs, cryptographic integrity, guaranteed retention	A.8.2 + A.4.2	Art. 12	WORM storage (Ceph + immutable bucket) + log signing (sigstore) + 24-36 month retention
`op.exp.11` Cryptographic keys	Key lifecycle management, HSM at High category	mp.info.4	Art. 15	HashiCorp Vault / SOPS + HSM (Yubico, AWS KMS on-prem) for High category

Operational framework — external services (`op.ext`)

Critical when the system integrates GPAI (Llama, Mistral) hosted elsewhere, or when the deployer is a third party.

ENS measure	Requirement	42001 control	AI Act article	Technical evidence
`op.ext.1` Contracting external services	Contract with security clauses, SLA, right to audit	A.10.3 suppliers	Art. 25 + Art. 53	Contract with ENS clauses + annual audit review + Cloud Act analysis
`op.ext.2` Alternative means	Plan B if the supplier goes down	A.4.5 + clause 6	Art. 15 (resilience)	Multi-cluster with failover + qualified alternative GPAI (Llama→Mistral→Qwen)
`op.ext.3` Supply chain protection	Assessment of suppliers and sub-suppliers	A.10 + clause 6	Art. 53 + NIS2 supply chain	SBOM + cosign + SLSA + continuous vulnerability scanning
`op.ext.4` System interconnection	Interconnection agreements, secure gateways	mp.com + A.4.5	Art. 15	API Gateway with mTLS + JWT signing + rate limiting + WAF

Operational framework — continuity (`op.cont`)

ENS measure	Requirement	42001 control	AI Act article	Technical evidence
`op.cont.1` Impact analysis	BIA per system	A.5.5 (impacts on individuals)	Art. 9 (risk management)	Documented BIA with RPO / RTO per system
`op.cont.2` Continuity plan	Documented DRP, RTO/RPO	clause 6 + A.4	Art. 15 (resilience)	DRP + Velero K8s backups + DVC datasets in a secondary bucket
`op.cont.3` Periodic testing	Drills at a defined frequency (annual at High category)	clause 9 (evaluation)	Art. 15	Annual game-day with a simulated disaster + recovery stopwatches
`op.cont.4` Alternative means	Capacity to continue with degraded means	clause 6 + A.4.5	Art. 15	Secondary cluster in a different datacenter + reserved GPU pool + replicated datasets

Operational framework — monitoring (`op.mon`)

ENS measure	Requirement	42001 control	AI Act article	Technical evidence
`op.mon.1` Intrusion detection	IDS/IPS over network and applications	A.9.2 use	Art. 15 (cybersec)	Guardrails as a semantic WAF + LLM Guard PromptInjection + Tetragon eBPF runtime
`op.mon.2` Metrics system	Measurable operational metrics, auditable dashboard	clause 9 (performance evaluation)	Art. 72 (post-market monitoring)	Prometheus + VictoriaMetrics + Grafana + Langfuse dashboards
`op.mon.3` Surveillance (High category)	24×7 monitoring with alerting	clause 9 + clause 10	Art. 72 + Art. 73	SOC with SIEM alerts (Wazuh, OpenSearch, Vector + custom) + on-call rotation

Protection measures — communications (`mp.com`)

ENS measure	Requirement	42001 control	AI Act article	Technical evidence
`mp.com.1` Secure perimeter	Firewall, segmentation, DMZ	A.4.5	Art. 15	Cilium NetworkPolicy + Calico + ingress controllers with WAF (mod_security)
`mp.com.2` Confidentiality protection	Encryption in transit (TLS 1.2+ mandatory, 1.3 recommended)	A.4.5	Art. 15	TLS 1.3 mandatory + cert-manager + Let’s Encrypt or an internal CA
`mp.com.3` Integrity and authenticity protection	Encryption + origin authentication	A.4.5 + A.4.4	Art. 15	Intra-cluster mTLS + JWT signing at the gateway + checksums on artifacts
`mp.com.4` Flow separation	Segmentation of mgmt vs production vs external traffic	A.4.5	Art. 15	Cilium policies + network namespaces + east-west / north-south segregation

Protection measures — applications (`mp.sw`)

ENS measure	Requirement	42001 control	AI Act article	Technical evidence
`mp.sw.1` Application development	Secure SDLC, code review, SAST/SCA	A.6.2.3 responsible design	Art. 9 + Art. 15	Forgejo CI with SAST (Semgrep, CodeQL) + SCA (Trivy, Grype) + mandatory PR review
`mp.sw.2` Acceptance and go-live	Acceptance tests, eval gates before production	A.6.2.5 V&V	Art. 9 + Art. 15	Eval gates from the evals post + canary deploy + pre-go-live metrics

Protection measures — information (`mp.info`)

ENS measure	Requirement	42001 control	AI Act article	Technical evidence
`mp.info.1` Personal data	GDPR compliance + technical and organisational measures	A.5.5 + A.7.6	Art. 10 + Art. 26	LLM Guard Vault + Presidio + minimisation in RAG corpus curation
`mp.info.2` Information classification	Labelling by level (public / internal / confidential / restricted)	A.7.2 data	Art. 10	Schema contracts from data versioning with a `classification` field
`mp.info.3` Encryption	At-rest minimum at Medium category, High category with HSM	A.4.5 + mp.eq	Art. 15	LUKS / dm-crypt on disks + encryption in the Ceph bucket + keys in Vault
`mp.info.4` Electronic signature	Documents signed with a valid certificate (Medium category and above)	A.8.2	Art. 12	Log signing with sigstore + signing of published models with cosign
`mp.info.5` Timestamps	Qualified timestamp for temporal integrity (High category)	A.8.2	Art. 12	Timestamping with a qualified TSA + RFC 3161 on critical events
`mp.info.6` Document cleaning	Removal of unauthorised metadata, anonymisation	A.7.6 + A.5.5	Art. 10	LLM Guard Anonymize (input) + Sensitive (output) + Vault with TTL

Protection measures — services (`mp.s`)

ENS measure	Requirement	42001 control	AI Act article	Technical evidence
`mp.s.1` Email	Anti-spam, anti-malware, optional encryption	A.4.5	—	Outside the direct LLM scope
`mp.s.2` Protection of web services and applications	WAF, hardening, vulnerability management	A.9.2 + mp.com	Art. 15 (cybersec)	AI Gateway (LiteLLM / Envoy AI / Kong AI) with policies + ModSecurity + Cloudflare-like
`mp.s.3` Protection against denial of service	Rate limiting, anti-DDoS, capacity planning	A.4.5 + A.9.2	Art. 15	Rate limiting at the gateway + token quotas + circuit breakers
`mp.s.4` Protection against external threats (High category)	Advanced monitoring, threat intel	A.9.2 + clause 9	Art. 15 + Art. 72	Guardrails, 4 lines + advanced LLM Guard scanners + threat intel feed (CCN-CERT MISP)

Master table of triple compliance — the 25 relevant controls consolidated

The key reading of the table: one row per technical capability. The organisation does not build three solutions for “activity log” (ENS) + “information to interested parties” (42001) + “record-keeping” (AI Act). It builds one single piece of OTel tracing with the correct metadata and presents it labelled for whichever inspector is asking.

The labelling typically materialises in three mechanisms:

Tags in the CI/CD pipelines: every artefact produced carries tags ens:op.exp.8, iso42001:A.8.2, aia:art.12 in its Helm / Argo CD metadata.
Semantic OTel attributes: gen_ai.compliance.ens = "op.exp.8", gen_ai.compliance.iso42001 = "A.8.2" as custom attributes on the relevant spans (not standard yet, but useful internally).
A mapping table in the wiki: a living document of ENS measure → 42001 control → AI Act article → technical runbook + owner + last verification. This is the artefact the auditor consults.

Applied case: multi-tenant chatbot for public administration

A variant of the multi-tenant chatbot from the forensic post, where the client is now a Spanish regional government offering citizen assistance on administrative procedures. The three lenses:

ENS: applies mandatorily, being public sector plus a service to citizens. Category High (citizens’ PII plus a critical service).
ISO 42001: the regional government requires certification from the supplier as a contractual condition.
EU AI Act: if the chatbot informs about procedures but decides nothing on the citizen’s behalf, it is limited risk (Art. 50 transparency). If it automates decisions (admission to a programme, refusal of a benefit), it is high risk.

We assume high risk for the most demanding walkthrough.

The chatbot’s 25 key technical capabilities consolidated

Technical capability	ENS	42001	AI Act	Status
Robust citizen authentication	`op.acc.5` (MFA High category)	A.4.4	Art. 14	Cl@ve + digital certificate + WebAuthn
Unique tenant + user identification	`op.acc.1`	A.3.2	Art. 14 + 26	JWT with `tenant_id` + `user_id_hashed`
Per-tenant allowlist	`op.acc.2`	A.9.4	Art. 14	LiteLLM Proxy with policies + Envoy filter
Encryption in transit, mTLS	`mp.com.2-3`	A.4.5	Art. 15	TLS 1.3 + cert-manager + intra-mesh mTLS
Encryption at rest + HSM keys	`mp.info.3` + `op.exp.11`	A.4.5	Art. 15	LUKS + Vault + Yubikey or nCipher HSM
PII anonymisation input/output	`mp.info.1 + .6`	A.7.6	Art. 10	LLM Guard Vault + Presidio + Llama Guard 4
Traceable logging + WORM	`op.exp.8 + .10`	A.8.2	Arts. 12 + 19	OTel + Tempo + Loki + Ceph WORM 36 months
Log signing + timestamps	`mp.info.4 + .5`	A.8.2	Art. 12	sigstore + qualified TSA (FNMT)
Runtime threat detection	`op.mon.1 + mp.s.4`	A.9.2	Art. 15	Guardrails, 4 lines + Tetragon + Falco
Operational metrics dashboard	`op.mon.2`	clause 9	Art. 72	Prometheus + Grafana + Langfuse
24×7 SOC surveillance	`op.mon.3` (High category)	clause 9	Art. 72	SOC with SIEM + on-call rotation
Incident management with notification	`op.exp.7 + .9`	clause 10	Art. 73	Incident-driven retrain + CCN-CERT channel
CI/CD pipeline with eval gates	`mp.sw.1 + .2`	A.6.2.3-5	Arts. 9 + 15	Forgejo CI + Semgrep + Trivy + DeepEval gates
Backups + DRP	`op.cont.1-4`	clause 6 + A.4	Art. 15	Velero + DVC datasets in a secondary bucket + annual game-day
Systematic risk analysis	`op.pl.1`	A.5 + cl.6	Art. 9	MAGERIT + FRIA + ISO/IEC 23894 impact assessment
Documented secure architecture	`op.pl.2`	A.4.2	Art. 15	Seven layers + seven phases
Supplier management	`op.ext.1 + .3`	A.10.3	Art. 53	Contracts with ENS clauses + SBOM + Cloud Act analysis per GPAI
Certified components	`op.pl.5`	A.10.5	Art. 53	Inventory with licence + supply chain audit
Configuration hardening	`op.exp.2 + .3`	A.4 + A.6	Art. 15	CIS Benchmarks for K8s + GitOps + immutable tags
Protection against malicious code	`op.exp.6`	mp.eq	Art. 15	Image scanning + runtime security
Asset inventory	`op.exp.1`	A.4	Art. 49	CMDB + Helm tags + OpenLineage
Network segmentation	`mp.com.4`	A.4.5	Art. 15	Cilium NetworkPolicy + namespaces
Rate limiting + anti-DoS	`mp.s.3`	A.4 + A.9	Art. 15	LiteLLM rate limit + token quotas
Information classification	`mp.info.2`	A.7.2	Art. 10	Schema contracts with a `classification` field
Transparency towards the user	—	A.9.4	Art. 50	UI banner + disclaimer in responses

Result: the 25 technical capabilities are common to all three frameworks. Only two require evidence for a single framework in isolation: mp.info.4-5 (qualified signature and timestamp, ENS-specific, not required so literally by 42001 or the AI Act) and Art. 50 (transparency banner, AI Act-specific). The rest are the same technical piece with three labels. A well-organised team certifies all three in series with only marginal extra work between the second and the third.

The five traps of triple compliance

Trap 1 — Measuring the same thing three times. Inexperienced teams create three separate dashboards (one for ENS, another for 42001, another for the AI Act) with the same metrics duplicated. The result: three sources of truth that diverge, three audit teams with different figures, three corrections to resolve one and the same deviation. The rule: one metric, three labels.

Trap 2 — Losing the control that covers only one framework. mp.info.4 (electronic signature) is ENS-specific and gets forgotten while the team is focused on 42001 + AI Act. On ENS audit day, the gap surfaces. Solution: the master table keeps every control visible, orphans included.

Trap 3 — Bias towards the most recent framework. The team spends 80% of the effort on the AI Act because it is the newest, and forgets the rigour of the ENS, which has been in force for 14 years. The ENS measures are technically more prescriptive than the AI Act (which is legally stricter but leaves implementation freedom). Moving up a level to ENS High category introduces specific requirements (HSM, qualified timestamps, 24×7 surveillance) that the AI Act does not spell out. The ENS deserves respect for its technical detail, not for its legal stature.

Trap 4 — Mixing ENS Medium and High categories. The Annex II matrix of RD 311/2022 dictates which measures are required and at what depth per category. Moving from Medium to High changes 15-20 controls, which is not marginal. The category is decided at the start of the project and documented; changing it halfway forces a complete re-audit.

Trap 5 — Audit fatigue inside the technical team. Three audits a year (biennial ENS + annual 42001 surveillance + ad-hoc AI Act by the authority) exhausts the team if they are not planned and if evidence is not reused. The professional approach: one single quarterly internal audit cycle with rotating scope, producing evidence consumable by all three external auditors. The difference between 30 days a year and 90 days a year lost to audits is the discipline of single evidence plus disciplined labelling.

What we have not covered (upcoming posts)

The CCN-CERT STIC series applicable to AI systems: STIC 800-159 (web service operation), STIC 800-105 (cryptography), STIC 800-150 (cloud environments). Each adds technical detail on how to materialise the ENS measures.
The GDPR as a fourth lens: privacy and personal data protection. It overlaps with mp.info.1 and with A.7.6 of 42001 plus Art. 10 of the AI Act. Material for an analogous pass over LOPDGDD + GDPR + AEPD against the three frameworks seen here.
Concrete templates of technical evidence with minimum fields: a log entry with every attribute required by the three lenses, an incident report with every field demanded by the three frameworks, a unified ENS / AI Act / 42001 declaration of conformity.
The NextGenerationEU funds case: specific compliance requirements for AI projects financed with European funds, where the AI Act + ENS are contractually mandatory.
42001 + ENS High category combined with DORA (Digital Operational Resilience Act, Reg. 2022/2554) for Spanish financial entities deploying AI.

References

RD 311/2022 — por el que se regula el Esquema Nacional de Seguridad. https://www.boe.es/buscar/act.php?id=BOE-A-2022-7191.
CCN-CERT — Portal ENS: https://ens.ccn.cni.es/. Guías STIC Series 800.
CCN-STIC 803 — Valoración de los sistemas y de la información. Metodología para asignar categoría ENS.
CCN-STIC 804 — Esquema Nacional de Seguridad. Guía de implantación.
CCN-STIC 824 — Informe del estado de seguridad. Plantilla para auditoría ENS.
MAGERIT v3 — Metodología de Análisis y Gestión de Riesgos del Ministerio de Asuntos Económicos. Insumo de op.pl.1.
ISO/IEC 42001:2023 — Sistema de gestión IA. Norma certificable que solapa con ENS.
Regulation (EU) 2024/1689 (EU AI Act) — texto consolidado.
NIS2 (Dir. 2022/2555) — directiva de ciberseguridad que el ENS implementa parcialmente en su versión 2022.

ISO/IEC 42001: the operations manual for the AI system — how the AIMS fits over the on-premise LLM platform described in this blog

Mon, 01 Jun 2026 06:00:00 +0200

This post closes an asymmetry the blog had been accumulating: we have described in detail the technical platform (seven stack layers, seven deployment phases, five maturity levels), the operational pipeline (six LLMOps stages), the data pieces (corpus curation, versioning), the eval / safety pieces (evals, guardrails, LLM Guard) and the observe pieces (OTel GenAI tracing). What had not appeared is the governance layer a regulated client asks for on top of all that. ISO/IEC 42001 is that layer.

TL;DR

ISO/IEC 42001:2023 is the first certifiable international standard that defines how an AI system is managed. It is not a technical standard (it does not say “use this inference engine” or “this safety threshold”): it is a management standard, a cousin of ISO 27001 and ISO 9001. From both it inherits the Annex SL structure, seven mandatory clauses running through context, leadership, planning, support, operation, performance evaluation and improvement, and it adds an Annex A with 38 AI-specific controls in 9 sections: policies, internal organisation, resources, impact assessment, lifecycle, data, information to interested parties, use, third parties. The thesis of this post is that the technical architecture described in this blog directly covers between 60% and 80% of the A controls with no extra work. The LLMOps pipeline materialises A.6, versioning and curation materialise A.7, guardrails and evals materialise A.9, OTel tracing materialises A.8. The rest is governance discipline that does not appear in the code (a written AI policy, impact assessments per system, a stakeholder register, role decisions between provider/producer/customer, mandatory documentation), and that is precisely what separates a real certification from performative compliance. The post maps the correspondence control by control, cross-references it with the EU AI Act (seven articles directly aligned with 42001: 9, 10, 11, 12, 13, 14, 17), with NIS2 (asset register, incident notification, supply chain) and with ENS (Esquema Nacional de Seguridad, Spain’s national security framework, RD 311/2022, Basic/Medium/High categories), lists the seven mandatory minimum documents an auditor asks for, presents the blog’s multi-tenant chatbot as a live 42001 checklist, and closes with the five usual traps (confusing 42001 with EU AI Act compliance, over-documenting without measuring, ignoring A.5 until the audit, assuming 27001 covers the AI part, thinking certification is a one-off project rather than a living system).

The analogy: the aircraft operations manual

A modern aircraft, an A350, a Boeing 787, a drone certified for urban delivery, does not fly because it has good engines. It flies because the organisation that operates it has an Operations Manual approved by the aviation authority (EASA in Europe, the FAA in the US, AESA in Spain as a delegated body). The manual does not contain the engine blueprints, which the manufacturer certifies; it contains the procedures: who is captain on each flight, which checklist is run before each take-off, which periodic inspections happen at 100, 500 and 2,000 flight hours, which external suppliers are authorised to touch which components, what is documented after each incident, what to do when a new alert appears on the panel. The authority does not sit in on every flight: it reads the manual, randomly audits the traceability of past flights against the manual, and if everything adds up, it keeps the certification in place.

An AI system in production, the multi-tenant chatbot from the forensic post, a copilot for lawyers, a credit scoring system, is exactly the same. It flies because the model is good, the LLMOps pipeline is well built, the guardrails catch the bad cases. But it certifies because the organisation operating it has an AIMS (AI Management System) described in an auditable manual. ISO/IEC 42001 is that manual: its mandatory table of contents (Annex SL, seven clauses) and its catalogue of AI-specific controls (Annex A, 38 controls). The auditor does not sit next to the MLOps engineer: they read the AI policy, review the impact assessments of the most recently deployed systems, check that incident retrain is documented, verify third-party contracts, audit a sample of Langfuse traces cross-checked against dataset_hash and prompt_id. And if everything adds up, they certify.

The analogy matters because it frames the right question: 42001 does not certify the model or the code. It certifies the way of operating the complete system. A team can have the best OSS stack in the world and fail the audit because it has no written AI policy and no documented decision about which role (provider vs producer vs customer) it occupies towards its clients. And the reverse: a team with a modest model but with operations-manual discipline can certify without acrobatics.

ISO/IEC 42001 in 15 seconds

Publication: December 2023, ISO/IEC JTC 1/SC 42 (the ISO/IEC subcommittee for AI).
Status in 2026: an active standard, certifiable by accredited bodies (BSI, AENOR, TÜV, Bureau Veritas, A-LIGN, Schellman). Not yet formally recognised as a harmonised standard under the EU AI Act, but it provides the management base to lean on.
Compatibility: it shares the Annex SL structure with ISO 9001 (quality), 27001 (information security), 27701 (privacy), 22301 (continuity), 20000-1 (IT services). Organisations with integrated management systems (IMS) add it with 20-40% of the effort it would take to implement from scratch.
Applicability: any organisation that develops, provides, deploys or uses AI systems. It is not limited to developers: a company that consumes a hosted LLM and integrates it into its own product is within scope.
Certification: a 3-year cycle with an initial audit (Stage 1: documentation review + Stage 2: on-site audit) and annual surveillance audits. Typical cost: 15,000-60,000 € for the initial one depending on size; 6,000-20,000 € per annual surveillance.

What 42001 does not do:

It does not say which models to use or which thresholds to apply.
It does not certify the individual model (that is done by specific evaluations such as a NIST AI RMF profile or EU AI Act technical documentation).
It does not replace the EU AI Act or the GDPR: it is complementary. Implementing it well makes legal compliance easier but does not guarantee it.
It is not a technical standard for explainability or robustness (those are ISO/IEC 25059, 24029, 23894 and others in the SC 42 family).

Distinction from neighbouring frameworks

Framework	Nature	Scope	Certifiable	Overlap with 42001
ISO/IEC 42001:2023	Management standard	AIMS for any AI system	Yes	—
EU AI Act (Reg. 2024/1689)	Binding legal regulation	AI systems in the EU, risk-categorised	No (it is law)	Arts 9, 10, 11, 12, 13, 14, 17
NIS2 (Dir. 2022/2555)	Cybersecurity directive	Essential/important entities	Via the national scheme	Asset register, incident, supply chain
ENS (RD 311/2022)	Spanish security regulation	Public sector and its suppliers	Yes (B/M/A categories)	Traceability, incident management
ISO/IEC 27001	Management standard	Information security	Yes	Annex SL structure + Annex A overlap
ISO/IEC 27701	Management standard	Privacy (extends 27001)	Yes	PII in training data
NIST AI RMF 1.0	Voluntary framework	AI risk management	No	Conceptually aligned, not identical
ISO/IEC 23894	Technical standard	AI risk management	No	Input to A.5 (impact assessment)
ISO/IEC 5259	Family	Data quality for AI	No	Input to A.7 (data)

Three distinctions that matter operationally and are a recurring source of confusion with clients:

ISO 42001 ≠ EU AI Act compliance. Holding the 42001 certification makes it easier to demonstrate articles 9-17 of the European Regulation, but the Regulation requires things 42001 does not cover directly (CE marking of high-risk systems, registration in the European database, declaration of conformity, specific post-market monitoring). Implementing 42001 first and then filling the AI Act gaps is the standard route.
ISO 27001 is not enough. 27001 covers confidentiality, integrity and availability of information. The AI side is missing: bias, opacity, model drift, training corpus quality, human evaluation, impact on affected persons. 42001 is a complement, not a substitute. Organisations that already have 27001 in place have an advantage because they share half the documentation.
NIS2 ≠ AI safety. NIS2 requires registering critical assets, notifying incidents within 24 h, and managing the digital supply chain. AI systems can be within NIS2 scope if they form part of the critical asset (an LLM serving customer support in a financial entity is), but NIS2 does not audit model quality. 42001 does.

The seven clauses (Annex SL): the mandatory table of contents

The seven clauses, from clause 4 to clause 10, are common to all modern management standards (Annex SL, also called the “High Level Structure”). That means an organisation with ISO 9001 or 27001 already in place recognises the structure. Clauses 1-3 are introductory (scope, normative references, terms).

Clause 4 — Context of the organisation

Identify the external context (applicable regulation, customer expectations, social risks) and the internal context (strategy, culture, capabilities). Identify the interested parties and their expectations: customers, regulators, affected persons, employees, suppliers. Define the scope of the AIMS: which AI systems are in and which are out.

The usual gap: organisations that say “all our AI systems are in scope” without having enumerated them. The auditor asks for the list. Without a list, there is no scope.

Clause 5 — Leadership

Top management must approve and publish an AI policy, assign roles and responsibilities (typically AI lead, AI risk owner, data officer), and demonstrate commitment through resources, communication and oversight. The policy is an auditable document and must be made available to staff and interested parties.

The usual gap: a generic AI policy copied off the internet, with no measurables and no concrete objectives. The auditor asks how compliance with it is measured. Without metrics, the policy is theatre.

Clause 6 — Planning

Identify risks and opportunities of the AIMS (not of the individual model). Define measurable AI objectives, with deadlines and owners. Plan changes to the AIMS.

The usual gap: confusing AIMS risks (what happens if we do not document correctly?) with model risks (what happens if the model is biased?). The first belongs here; the second goes to A.5.

Clause 7 — Support

Resources: human, technical, financial, infrastructure. Competence of personnel (documented training). Awareness of the policy among personnel. Internal and external communication. Documented information (the backbone of the management system: policy, procedures, records, evidence).

The usual gap: documentation scattered across Confluence/Notion/Drive with no version control and no recorded approvals. The auditor asks about the last change: who approved it? when? on what grounds?

Clause 8 — Operation

The most operational clause. It requires:

Operational planning and control: how the AI system’s lifecycle is managed day to day. → Covered in the blog by the six-stage LLMOps pipeline.
Impact assessment (linked to A.5).
AI system lifecycle management (linked to A.6).
Data for AI systems (linked to A.7).

This is the clause that materialises in controls A.5, A.6 and A.7. On its own it adds no new requirements: it links to Annex A.

Clause 9 — Performance evaluation

Monitoring, measurement, analysis, evaluation. Internal audits (planned, with criteria, scope, frequency, recorded results). Management review (typically quarterly or half-yearly, with a mandatory agenda: inputs, evidence, decisions, actions).

The usual gap: there is OTel tracing + Langfuse + Grafana and plenty of data, but there is no formal management review agenda with documented minutes. The auditor asks for the minutes. Without minutes, there is no review.

Clause 10 — Improvement

Nonconformity and corrective action: when something fails, it is recorded, root cause is analysed, a correction is agreed, effectiveness is verified. Continual improvement: the system evolves deliberately.

The usual gap: Jira tickets with technical post-mortems but no formal “ISO nonconformity” record closed out with an effectiveness check. They are two distinct artefacts, even if they can be integrated.

The 38 Annex A controls: the AI-specific catalogue

Unlike Annex SL (which is common), Annex A is 42001’s AI-specific signature. The 38 controls are organised into 9 sections (A.2 to A.10; A.1 is the introduction) covering the AI-specific risks: opacity, bias, drift, corpus quality, impact on affected persons, third-party dependency. Each control has an objective (what it aims to achieve) and implementation guidance in Annex B.

Section	Focus	# controls
A.2	AI-related policies	2
A.3	Internal organisation	3
A.4	Resources for AI systems	6
A.5	Impact assessment	5
A.6	AI system lifecycle	4
A.7	Data for AI systems	5
A.8	Information for interested parties	4
A.9	Use of AI systems	3
A.10	Third parties and customer relationships	4
Total	—	38

What follows is the section-by-section mapping of the controls onto material we have already covered in the blog. The editorial intent is to show which gaps remain once the technical architecture is in place, so that the road to certification does not start from zero.

Cross-mapping: 38 controls ↔ blog posts

A.2 — AI policies (2 controls): PARTIAL

A.2.2 AI policy: the organisation must have a documented AI policy, approved by management, reviewed periodically, communicated and available. It covers principles, scope and commitments.
A.2.3 Alignment with other policies: the AI policy is not an orphan, it aligns with existing security, privacy, quality and ethics policies.

Gap: this is not a code matter. The AI policy is a document that the organisation’s management approves and signs. The blog teaches a neutral, technical editorial stance (no hype, sovereignty, OSS by default under ENS/NIS2), but that is not any specific organisation’s AI policy. Each client has to draft and sign their own.

Minimum template: 1-2 pages with: principles (transparency, human oversight, fairness, accountability, sustainability), scope (which systems), measurable commitments (annual review, impact assessment before deployment, team training), governance (who approves what).

A.3 — Internal organisation (3 controls): GAP

A.3.2 AI roles and responsibilities: roles defined, non-overlapping, communicated. Typically: AI lead, AI risk owner, data steward, AI ethics officer (which may be a single person in small organisations).
A.3.3 Reporting of AI incidents/concerns: a channel for anyone (internal or external) to report a problem with an AI system, with documented follow-up.
A.3.4 Identification of stakeholders: a maintained list of stakeholders (customers, affected persons, regulators, partners) and their expectations.

Gap: also not technical. An organisational decision. The usual way to cover it is to appoint an AI lead (which may be the CIO, the CTO or a new role depending on size), reuse the security reporting channel (typically already in place because of 27001) by extending it to AI, and maintain a live stakeholder register.

A.4 — Resources (6 controls): COVERED

A.4.2 Documented information: documentation of the AIMS.
A.4.3 Data resources: identification and management of the data available for training, evaluation and operation.
A.4.4 Tooling resources: development, validation and monitoring tools.
A.4.5 System resources: hardware, infrastructure, compute.
A.4.6 Human resources: competent personnel.
A.4.7 Financial resources: budget.

Covered by the blog in the three architectural posts:

Anatomy of the stack: seven layers: A.4.5 system resources, A.4.4 tooling.
Seven deployment phases: A.4.5 + A.4.7 (budget implicitly).
Five maturity levels: A.4.5 + A.4.6 (team maturity).
OSS tooling catalogue: A.4.4 tooling.
Data versioning with DVC and lakeFS: A.4.3 data resources.

A.5 — Impact assessment (5 controls): PARTIAL

A.5.2 AI impact assessment process: a documented impact assessment procedure.
A.5.3 Documentation of AI impact assessments: records of the assessments carried out.
A.5.4 Alignment with AI risk treatment: the impact assessment’s decisions feed risk treatment.
A.5.5 Impacts on individuals: specific dimensions covering affected persons (rights, discrimination, privacy).
A.5.6 Societal impacts: dimensions covering society (information, social rights).

Partial: the method exists in the ISO/IEC SC 42 family. ISO/IEC 23894:2023 is the technical standard for AI risk management and NIST AI RMF 1.0 is the freely usable American equivalent. But the organisation has to write its procedure and run it per system before deployment. It is not code, it is discipline.

Minimum template for the impact assessment (3-5 pages per system):

Description of the system (what it does, who it serves, underlying model and stack).
Stakeholders identified.
Potential impacts (intended and unintended) on people, groups and society.
Fairness and robustness metrics applied, with thresholds and results.
Mitigations applied (guardrails, evals, human oversight, rate limiting).
Accepted residual risks, with signed justification.
Review cadence (typically annual, or on substantial change).

A.6 — AI system lifecycle (4 controls): COVERED

A.6.2.2 Objectives for responsible development of AI: responsible development objectives defined per system.
A.6.2.3 Processes for responsible AI design and development: design and development procedures.
A.6.2.4 AI system requirements and specifications: formal specification of the system.
A.6.2.5 Verification and validation: V&V before and during operation.
A.6.2.6 Deployment: deployment procedures.
A.6.2.7 Operation and monitoring: continuous operation and monitoring.
A.6.2.8 Documentation: lifecycle documentation.

Covered by the blog:

The six-stage LLMOps pipeline: the complete master map of the lifecycle.
Anatomy of an LLM request: the forensic version of how it runs in production.
Continuous fine-tuning in production: the A.6.2.3 + A.6.2.5 + A.6.2.6 + A.6.2.7 discipline in real operation.
Evals: the layer after tracing: A.6.2.5 verification and validation.
Retrain: A.6.2.7 operation + continuous iteration.
Modern alignment: DPO, KTO, ORPO, SimPO: A.6.2.3 responsible design.
MLOps landscape 2026: the tooling landscape.

A.7 — Data for AI systems (5 controls): COVERED

A.7.2 Data for development and enhancement of AI: data management policy and procedures for development and improvement.
A.7.3 Acquisition of data: acquisition procedures (origin, authorisation, quality).
A.7.4 Quality of data for AI systems: measurable quality criteria.
A.7.5 Data provenance: data lineage.
A.7.6 Data preparation: preparation procedures (chunking, anonymisation, labelling).

Covered by the blog:

RAG corpus curation: the active librarian: A.7.4 + A.7.5 + A.7.6 in detail (five layers: schema, dedup, PII, anti-contamination, lineage).
Data versioning: DVC and lakeFS: A.7.2 + A.7.5 (the four data artefacts versioned with lineage).
Reranker and hybrid retrieval: A.7.6 preparation + filtering.
LLM Guard: A.7.6 runtime anonymisation with Vault.

A.8 — Information for interested parties (4 controls): COVERED

A.8.2 System documentation and information for users: technical documentation available.
A.8.3 External reporting: the capacity to report to authorities where applicable.
A.8.4 Communication of incidents to users: notification to users when there is an incident.
A.8.5 Information for interested parties: information for other stakeholders.

Covered by the blog:

LLM tracing with OpenTelemetry GenAI: A.8.2 per-request traceability, A.8.3 the capacity to extract forensic reporting.
Prompt versioning with Langfuse and MLflow: A.8.2 documented versioning.
Guardrails and safety in LLMs: A.8.4, gen_ai.guardrail.* spans as the basis for incident notification.
LLM Guard: A.8.4 incident events for retrain.

A.9 — Use of AI systems (3 controls): COVERED

A.9.2 Processes for responsible use of AI: responsible use procedures.
A.9.3 Objectives for responsible use of AI: objectives.
A.9.4 Intended use of AI systems: documentation of the intended use.

Covered by the blog:

Guardrails and safety in LLMs: A.9.2 + A.9.3 (the four lines of defence).
LLM Guard: A.9.2 operational detail.
Evals: the layer after tracing: A.9.3 measurement of objectives.
Retrain: A.9.2 closed loop.

A.10 — Third parties and customer relationships (4 controls): COVERED

A.10.2 Allocation of responsibilities: distribution of responsibilities between AI roles.
A.10.3 Suppliers: procedures for AI suppliers.
A.10.4 Customers: procedures towards customers.
A.10.5 Third parties: procedures for third parties.

Covered by the blog:

The parallel catalogue: OSS vs hyperscalers: A.10.3 supplier assessment with lock-in and contractual sovereignty analysis.
The OSS catalogue for LLMOps: A.10.5 third-party inventory (OSS components with licences and governance).
Anatomy of an LLM request: A.10.2 + A.10.4 in the multi-tenant case.

The roles defined by the standard

ISO/IEC 22989:2022 (AI vocabulary, complementary to 42001) defines six roles. Each organisation has to decide which ones it occupies and document it:

Role	Definition	Main responsibility	Example
AI provider	Organisation that provides the AI system to others	Makes the system available	OpenAI provides GPT-5 via API
AI producer	Organisation that develops the AI system	Design, development, validation	Meta produces Llama 4
AI customer	Organisation that acquires the AI system	Selection, integration, oversight	A consultancy integrating an LLM into its own product
AI partner	Organisation collaborating with another AI role	Shared	A GPU hardware manufacturer
AI subject	Person or group affected by the system	Recipient of the impact	The chatbot’s end user
Relevant authority	Regulator with jurisdiction	External oversight	AEPD, CNMC, EU AI Act authorities

An organisation can occupy several roles at once, which changes the applicable controls. A common pattern in consultancy is: producer + customer + provider towards the end client. The A.10 responsibilities are modulated by the roles.

Example role mapping for the multi-tenant chatbot from the forensic post:

Base model manufacturer (Llama 4): AI producer of the base model.
OSS stack operator (the consultancy): AI producer of the LoRA adapter + AI provider of the chatbot to its clients + AI customer of Meta’s base model.
End client (the insurer): AI customer of the chatbot + AI provider of the customer support service.
The policyholder: AI subject.
AEPD + EU AI Act authority: relevant authority.

Each box in the table generates different obligations. The consultancy, being producer of the adapter, must document A.6 (lifecycle) and A.7 (data) for the adapter. Being provider of the chatbot, it must document A.10.4 (customers). Being customer of the base model, it must document A.10.3 (suppliers) and validate that Meta does its part.

Impact levels and proportionality

42001 does not demand the same rigour of every system. Clause 6.1.2 and control A.5 introduce impact as a modulator. The standard does not define strict categories (unlike the EU AI Act, which does define “prohibited / high risk / limited risk / minimal”), but it recommends using levels according to severity and probability.

Industry practice in 2026 aligns the 42001 levels with the EU AI Act categories:

42001 level	EU AI Act	Examples	Control depth
High	High risk (Annex III)	Credit scoring, HR, health, critical infrastructure	Exhaustive impact assessment, mandatory human oversight, continuous monitoring, adversarial evals, detailed logging, half-yearly management review
Medium	Limited risk	Customer service chatbots that do not automate decisions, productivity assistants	Standard impact assessment, complete guardrails, annual review
Low	Minimal risk	Spam filters, non-personalised content recommendations	Lightweight impact assessment, basic controls

This proportionality is operationally key: implementing 42001 at maximum rigour for a low-risk system is waste; relaxing it on a high-risk one is non-compliance.

The seven minimum AIMS documents

An auditor at Stage 1 (documentation review) asks for between seven and ten documents. The seven essentials:

AI policy (clause 5.2 + A.2.2). 1-2 pages. Approved by management, dated, versioned.
AIMS scope (clause 4.3). List of AI systems in scope, inclusion criteria.
Stakeholder register (clause 4.2 + A.3.4). A maintained list with expectations.
AIMS risk register (clause 6.1). Risks of the management system, not of each model.
Impact assessment procedure (A.5.2) + records of assessments carried out (A.5.3). The procedure plus one or more assessments done.
AI lifecycle procedure (A.6.2), which can literally read “see the six-stage LLMOps pipeline” with references to technical runbooks.
Data management procedure (A.7.2), covering acquisition, quality, provenance, preparation, anonymisation.

Common additional documents:

Responsible use policy (A.9.2) with permitted and non-permitted use types.
AI third-party management procedure (A.10.3, A.10.5) with assessment criteria for AI suppliers.
Internal audit plan + management review agenda (clauses 9.2 + 9.3).

For an organisation with a mature OSS stack, documents 6 and 7 are references to technical artefacts that already exist (pipeline runbooks, DVC configurations, the PII policy in LLM Guard). The real documentary effort sits in documents 1, 2, 3, 4 and 5.

Applied case: the blog’s multi-tenant chatbot → 42001 checklist

We take the system described in the forensic post, a multi-tenant customer support chatbot for insurers on an on-premise OSS stack, and walk it as a 42001 auditor would.

Clause 4 — Context. The AIMS scope includes the chatbot and excludes the internal HR system (a different AI). Stakeholders identified: client insurers, affected policyholders, the AEPD, the EU AI Act authority (once it enters into force on 2 Aug 2026), the supplier Meta (base model), the hardware supplier NVIDIA. → Documented.

Clause 5 — Leadership. AI policy signed by the CEO, in force. Roles assigned: AI lead (CTO), AI risk owner (CISO), data steward (Head of Data), quarterly AI ethics committee. → Documented.

Clause 6 — Planning. AIMS risk register: incomplete documentation, team churn, dependency on a single GPU supplier, EU AI Act regulatory change. AIMS objectives for 2026: 42001 certification before Q4, EU AI Act high-risk compliance before 2 Aug. → Documented.

Clause 7 — Support. Resources: a 4×H100 SXM cluster + the seven stack layers. Competence: 2 MLE + 2 SRE + 1 part-time AI ethics, all with documented training. Communication: AI policy on the intranet + handbook. → Documented.

Clause 8 — Operation. Operating procedures = the six-stage LLMOps pipeline. Impact assessment run before deployment + annual review + review on substantial change (defined as: base model change, major adapter change, expansion to a new tenant). → Documented.

Clause 9 — Evaluation. Monitoring: Langfuse + Tempo + VictoriaMetrics + Grafana. Mandatory dashboard metrics: F1 per guardrail category over real traffic, statistical drift, RAG faithfulness, refusal rate. Quarterly internal audit with written criteria. Half-yearly management review with signed minutes. → Documented.

Clause 10 — Improvement. Incident-driven retrain tickets mapped as nonconformities when severity ≥ HIGH. Documented root cause analysis. Effectiveness verified at the next eval gate. → Documented.

Annex A — By section:

A.2 (Policies): AI policy + responsible use policy. → Documented.
A.3 (Organisation): roles assigned, reporting channel, stakeholder register. → Documented.
A.4 (Resources): seven deployment phases + OSS catalogue + training plan + annual budget. → Documented.
A.5 (Impact): procedure + per-system assessments + fairness metrics applied. → Documented.
A.6 (Lifecycle): LLMOps pipeline + continuous fine-tuning + retrain. → Documented.
A.7 (Data): data versioning + RAG corpus curation + LLM Guard Vault + Presidio. → Documented.
A.8 (Information to parties): OTel tracing + Langfuse + gen_ai.guardrail.* spans + notification to tenants within SLA. → Documented.
A.9 (Use): guardrails + evals + responsible use policy. → Documented.
A.10 (Third parties): OSS vs hyperscalers with lock-in analysis + Meta contract for the base model + contracts with tenants. → Documented.

Result of the walkthrough: certifiable. The typical gaps (A.2.2 written policy, A.3 roles, A.5 impact assessment procedure) are covered as formal documents. The operational clauses (8, 9, 10) lean on the blog’s technical architecture. The distance between “having the architecture” and “having certification” is measured in documentary discipline, not in code.

Cross-mapping with the EU AI Act, NIS2 and ENS

EU AI Act (Reg. 2024/1689) — seven directly aligned articles

EU AI Act article	Topic	Aligned 42001 control	Applies to
Art. 9	Risk management system	A.5 + clause 6	High-risk systems
Art. 10	Data and data governance	A.7 (all)	High-risk systems
Art. 11	Technical documentation	A.6 + A.4.2	High-risk systems
Art. 12	Record-keeping (logs)	A.8.2 + OTel tracing	High-risk systems
Art. 13	Transparency to deployers	A.8.5 + A.10.4	High-risk systems
Art. 14	Human oversight	A.9.2 + documented oversight	High-risk systems
Art. 17	Quality management system	Clauses 4-10	High-risk providers

The main obligations for high-risk systems enter into application on 2 August 2026. Implementing 42001 now builds the management base that deadline demands.

What is missing for EU AI Act compliance that 42001 does not cover:

CE conformity of high-risk systems (declaration of conformity, marking, registration in the EU database).
The specific post-market monitoring required by Art. 72.
Serious incident reporting to authorities within legal deadlines (not only to users).
Transparency obligations towards users for limited-risk systems (Art. 50): chatbots, deepfakes, generated content.
The Art. 5 prohibitions (social scoring, manipulation, real-time biometrics with exceptions).

NIS2 (Dir. 2022/2555) — three pillars with overlap

Asset register (Art. 21.2.f): AI systems within NIS2 scope must be in the asset inventory. → Overlaps with A.4 + clause 4.3 (scope).
Incident notification (Art. 23): significant incidents are notified within 24 h (initial alert) + 72 h (detailed report). → Overlaps with A.3.3 (reporting) + clause 10 (improvement).
Supply chain security (Art. 21.2.d): security assessment of the digital supply chain. → Overlaps with A.10.3 (suppliers).

For essential NIS2 entities that also use AI systems, 42001 covers the AI-specific part that NIS2 requires by inference but does not spell out.

ENS (RD 311/2022)

The Spanish Esquema Nacional de Seguridad already expressly addresses AI in its Annex II (ENS controls). The Basic/Medium/High categories align with the 42001 impact levels. The ENS controls on traceability (op.exp.8), activity logging (op.exp.10) and incident management (op.exp.7) are covered by the same technical artefacts as A.8 and A.5 of 42001. An organisation certified at ENS High category with AI systems is a reasonable effort away from adding 42001.

The five usual certification traps

Trap 1 — Confusing 42001 with EU AI Act compliance. Passing the 42001 audit does not imply conformity with the European Regulation. They are distinct universes with a 60-70% overlap. The trap surfaces when the client asks for CE marking of the high-risk system and the organisation produces only the 42001 certificate.

Trap 2 — Over-documenting. Two-hundred-page manuals with procedures copied from templates, with no measurables and no evidence of application. The auditor asks for the last execution of the procedure; with no records, the procedures are ornament. The practical rule: prefer short documents referencing live technical artefacts to long self-contained ones.

Trap 3 — Under-measuring. Defining AIMS objectives with no operational metrics. “Improve model quality” is a null objective; “F1 per guardrail category ≥ 0.85 over real traffic, measured weekly, reviewed quarterly in the management review” is an auditable objective. The blog has insisted on this in every post on evals, guardrails and retrain.

Trap 4 — Ignoring A.5 until audit day. The impact assessment is the most underrated control and the first one the auditor asks for. Without per-system assessments carried out before deployment, there is no way to demonstrate A.5. The trap surfaces when there is no longer time to produce credible retrospective assessments.

Trap 5 — Assuming 27001 covers the AI part. Organisations that already have 27001 sometimes think “we have half of it done”. That is true for Annex SL (structure) and for A.5/A.6/A.7 of 27001 (not of 42001) as far as infosec goes. It is false for A.5 of 42001 (impact assessment), A.7 of 42001 (AI-specific data quality), A.9 (responsible use) and A.10.4 (AI customers). You have to add, not assume.

What we have not covered (upcoming posts)

Concrete templates of the seven mandatory documents, with drafting examples and metrics. Material for a post along the lines of “The AIMS manual in 7 documents” with a reference frame.
Detailed article-by-article mapping to the EU AI Act with the checklist of technical evidence derivable from the blog’s OSS stack. Especially Arts 11 (technical documentation), 14 (human oversight) and 72 (post-market monitoring).
The combined ENS High category + 42001 case: which ENS controls are covered by which AIMS artefacts, avoiding duplication.
NIST AI RMF 1.0 vs 42001 comparison: many international clients ask for both. How the same artefacts are recycled to satisfy the two frameworks.
42001 for LLM agents and MCP: the new dimensions that emerge when the AI system is agentic (excessive agency, tool use, graduated autonomy). The guardrails post introduced line 3 (tool GR); 42001 has open gaps in this terrain and SC 42 is working on addenda.

References

ISO/IEC 42001:2023 — Information technology — Artificial intelligence — Management system. ISO. https://www.iso.org/standard/81230.html.
ISO/IEC 22989:2022 — Information technology — Artificial intelligence — Artificial intelligence concepts and terminology. Define los roles AI provider/producer/customer/partner/subject.
ISO/IEC 23894:2023 — Information technology — Artificial intelligence — Guidance on risk management. Insumo de A.5.
ISO/IEC 38507:2022 — Governance implications of the use of AI by organizations. Complemento de gobierno.
ISO/IEC 5259 — Data quality for analytics and machine learning (familia). Insumo de A.7.
EU AI Act (Regulation 2024/1689) — texto consolidado en EUR-Lex. Entrada en vigor de obligaciones de alto riesgo: 2 ago 2026.
NIS2 (Directive 2022/2555) — texto consolidado en EUR-Lex.
ENS — Real Decreto 311/2022 — Esquema Nacional de Seguridad, BOE-A-2022-7191.
NIST AI RMF 1.0 (2023) — https://www.nist.gov/itl/ai-risk-management-framework.
EUR-Lex EU AI Act consolidated text — https://eur-lex.europa.eu/eli/reg/2024/1689.
A-LIGN / BSI / Schellman — blogs sobre experiencia de auditoría 42001 con casos reales 2024-2025.

EU AI Act: the technical dossier, article by article, over the blog's on-premise LLM architecture

Mon, 01 Jun 2026 05:30:00 +0200

Sister post to the mapping onto ISO/IEC 42001. That one broke down the AI management system, the certifiable standard. This one breaks down the binding legal regulation that applies without any certification: the EU AI Act is direct law in all 27 Member States, with no transposition and with explicit penalties of up to 35 million euros or 7% of worldwide turnover. The main obligations for high-risk systems enter into force on 2 August 2026; each article applies from its own date, not from the date the organisation gets certified.

TL;DR

Regulation (EU) 2024/1689 (the EU AI Act, “Reglamento Europeo de Inteligencia Artificial”), published in the Official Journal on 12 July 2024, sets obligations by risk tier (prohibited, high, limited, minimal) and by role (provider, deployer, importer, distributor, authorised representative). The obligations for high-risk systems (Annex III: biometrics, critical infrastructure, education, employment, essential public and private services, law enforcement, migration, justice, democratic processes) enter into force on 2 August 2026 and are the category that applies to most LLM projects in a medium-to-large enterprise. This post maps, article by article, the obligations relevant to a high-risk LLM system deployed on-premise: each article states its requirement, identifies which blog post already describes the technical piece that materialises it, and closes with an auditable checklist that a provider hands to a national supervisory authority. The Annex IV technical dossier is reconstructed by pointing its nine mandatory sections at the corresponding technical runbooks. Also covered: the Art. 6 classification and how to decide whether a system falls in as high risk, the Art. 5 prohibitions (what is excluded by construction), the GPAI obligations of Art. 53 that affect anyone building on base models (Llama, Mistral, DeepSeek, Qwen) rather than their own, the full timetable of application dates (5 Aug 2024 entry into force, 2 Feb 2025 prohibitions, 2 Aug 2025 GPAI, 2 Aug 2026 high risk Annex III, 2 Aug 2027 high risk Annex I and systemic GPAI), the Art. 99 penalty table (up to 35 M€ or 7% of worldwide turnover for Art. 5 violations, 15 M€ or 3% for high risk, 7.5 M€ or 1% for incorrect information) and the five frequent compliance traps. The editorial thesis: the technical architecture described in this blog directly covers between 70% and 85% of the Regulation’s technical requirements; the rest is documentary and procedural discipline (FRIA, CE marking, signed declaration of conformity, EU database registration, incident reporting within legal deadlines) built on top of technical artefacts that already exist but running on its own circuit.

The analogy: the type-approval dossier for a new vehicle

A vehicle manufacturer cannot sell a new car in the EU without passing WVTA (Whole Vehicle Type Approval). The process is public and standardised: the manufacturer prepares a technical dossier with dozens of chapters (brakes, emissions, active and passive safety, lighting, noise, weight, dimensions, recyclable materials, driver assistance devices), submits it to a type-approval authority or a notified technical service, which audits the file and, if everything adds up, issues the type approval. The manufacturer then stamps the E mark (E1 Germany, E9 Spain, and so on) and the CE/UNECE plate on every vehicle of that type produced in series. Each vehicle also carries a service book with mandatory inspections, and serious accidents or systemic defects are reported to the competent ministry, which can order recalls.

The EU AI Act adapts exactly this industrial model to high-risk AI software. The provider prepares the Annex IV dossier (nine mandatory sections) with the full technical documentation of the system, runs a conformity assessment (self-assessment for most Annex III cases, notified body for the more sensitive Annex I ones), signs the EU declaration of conformity, registers the system in the European database, and applies the CE marking to the system when it is placed on the market. From there on it must keep a live post-market monitoring system and report serious incidents to the market surveillance authorities of each Member State within legal deadlines ranging from 2 to 15 days depending on severity. Failing to comply, penalties reach 35 million euros or 7% of worldwide turnover depending on which article was breached.

The analogy matters because it bounds expectations: this is not a one-off compliance job, nor a badge you buy. It is an industrial type-approval process, with cadences, evidence, signatures and criminal liability. And most of the technical evidence the dossier asks for already exists in any serious system described in this blog: data lineage, OTel tracing, continuous evals, guardrails, incident-driven retrain, a responsible-use policy. What is missing is assembling it in the correct legal format.

How it fits with ISO 42001, NIS2 and ENS

Before dropping into the articles, a reminder of the editorial position from the post on ISO 42001:

Piece	Nature	Who operates it	Coverage
EU AI Act	Direct EU law	Provider + deployer + national surveillance authorities	AI systems on the EU market, segmented by risk
ISO/IEC 42001	Certifiable management standard	Organisation + certification body	AIMS, organisational governance
NIS2	Transposed cyber directive	Essential/important entities	Asset register, incident notification, supply chain
ENS (Esquema Nacional de Seguridad, Spain’s national security framework, RD 311/2022)	Spanish security regulation	Public sector + its suppliers	Categories B/M/A, certifiable

Implementing 42001 makes it easier to demonstrate articles 9-17 of the EU AI Act, but it is not equivalent to legal compliance. The table of legal obligations and the chain of criminal liability come from the Regulation, not from the standard. An organisation certified against 42001 that deploys a high-risk system without CE marking, without registration in the EU database, without a signed declaration of conformity and without a documented FRIA breaches the Regulation even with the certificate on the wall.

The four risk categories and the Art. 6 classification

The Regulation classifies systems into four risk tiers. The choice of category belongs to the provider and must be documented in the dossier, with technical and legal justification.

Category	Article	Examples	Consequence
Prohibited	Art. 5	Social scoring, manipulation, real-time biometrics with exceptions, indiscriminate facial scraping	Cannot operate in the EU under any circumstances
High risk	Art. 6 + Annex I + Annex III	Credit scoring, HR, education, critical infrastructure, non-real-time biometrics, justice, migration, health	Complies with Arts. 9-17, Annex IV dossier, CE marking, EU DB registration
Limited risk	Art. 50	Chatbots with humans as users, deepfakes, synthetic content	Transparency obligations towards the user
Minimal risk	Everything else	Spam filters, video game NPCs, content suggestions	No specific obligations; a voluntary code of conduct is recommended

The Art. 6 test for deciding whether a system is high risk:

Is it in Annex I? (products regulated by the listed harmonisation legislation: machinery, lifts, toys, medical devices, and so on). If the AI system is a safety component of an Annex I product, it is high risk.
Is it in Annex III? (eight areas: biometrics, critical infrastructure, education, employment, essential public/private services, law enforcement, migration/asylum, justice/democratic processes). If the system falls in any of those areas it is high risk, except if the Art. 6.3 exception is invoked (systems performing a narrow procedural task, improving the result of a previous human activity, detecting decision patterns without influencing the final decision, preparatory tasks).

The Art. 6.3 exception requires formal documentation justifying why it does not apply. In other words, even falling outside is not free: you have to demonstrate why.

For the typical LLM systems covered in this blog:

Customer support chatbot for banking, insurance or healthcare: probably high risk if it automates contractual decisions about the customer, limited risk if it only informs.
Internal HR assistant (CV screening): high risk (Annex III, employment area).
Medical assistant (diagnostic support): high risk (Annex III, healthcare services area).
Fraud detection system: high risk (Annex III, financial services area if it affects access to credit).
Code copilot for developers: minimal risk (does not affect third parties’ fundamental rights).
Internal LLM as a service with no productive use: minimal risk.

The category decision is not an opinion: it is documented and justified in the dossier.

Timetable of application

The obligations arrive in stages. The dates are inflexible:

Date	Applies
1 Aug 2024	The Regulation enters into force
2 Feb 2025	Art. 5 prohibitions + Art. 4 AI literacy obligations
2 Aug 2025	GPAI obligations (Art. 53) + governance + general penalties + designated national authorities
2 Aug 2026	Main high-risk obligations for Annex III + Art. 50 transparency to users
2 Aug 2027	High risk under Annex I (components of regulated products) + GPAI with systemic risk

2 August 2026 is the date that matters to most enterprise LLM projects. We are in June 2026: less than two months to go.

Article-by-article mapping

The sections below follow the structure of the Regulation. For each article the requirement is stated, the blog’s technical artefact that covers it is identified, and it closes with an auditable checklist.

Art. 5 — Prohibited practices (in force since 2 Feb 2025)

What it requires. It prohibits placing on the market, putting into service or using AI systems that:

Manipulate behaviour through subliminal or deceptive techniques that distort decision-making.
Exploit vulnerabilities related to age, disability or socio-economic situation.
Implement social scoring by public authorities.
Perform individual predictive policing based on profiling.
Perform indiscriminate facial scraping to build facial recognition databases.
Infer emotions in workplaces or education, except for medical or safety reasons.
Perform biometric categorisation inferring sensitive attributes (race, political opinion, sexual orientation, and so on).
Real-time remote biometric identification in public spaces by law enforcement, with strict exceptions (terrorism, kidnapping, missing persons) subject to prior judicial authorisation.

The blog’s stack. No piece of the blog facilitates these practices; the OSS catalogue described is oriented towards legitimate tasks. But the provider must explicitly document why the system does not fall under these prohibitions. It cannot be assumed.

Checklist.

Prohibition analysis documented per system, with a written statement of non-applicability.
If the system uses facial biometrics or emotion analysis: specific legal analysis with a formal opinion.
Annual legal review, or on any change of functionality.

Art. 6 — Classification of high-risk systems

What it requires. Determine whether the system is high risk by being in Annex I (safety component of a regulated product) or Annex III (8 areas). If it is in Annex III, assess the Art. 6.3 exception where applicable.

The blog’s stack. The forensic post and the six-stage pipeline describe systems that are typically high risk (multi-tenant chatbot affecting service decisions in a regulated sector).

Checklist.

Art. 6 analysis signed by the organisation’s legal officer.
If Art. 6.3 is invoked: formal documentation of the exception.
Re-assessment if the functionality changes (for example, the assistant moves from informing to deciding).

Art. 9 — Risk management system

What it requires. An iterative system, planned and executed across the whole lifecycle. Identify foreseeable risks, estimate risks under normal use and foreseeable misuse, evaluate emerging risks in post-market monitoring, adopt mitigation measures, communicate residual risks. Effectiveness testing is done under realistic conditions.

The blog’s stack.

The six-stage LLMOps pipeline, the iterative lifecycle.
Evals: the layer after tracing, testing under realistic conditions with golden sets.
Guardrails and safety in LLMs, operational mitigation measures.
Retrain: closing the loop, management of emerging risks via incident-driven retrain.

Checklist.

Risk management document per system, with identification, mitigation, and accepted residual risks signed off.
Periodic review procedure (at least annual, or on substantial change).
Link to the documented improvement loop.

Art. 10 — Data and data governance

What it requires. Training, validation and testing datasets that are relevant, representative, as free of errors and as complete as possible, taking into account the characteristics of the intended purpose. Document:

Data collection and selection.
Processing and annotation.
Biases identified as likely to affect fundamental rights or cause discrimination; measures to prevent them.
Identification of data gaps and how they are addressed.

The blog’s stack.

Data versioning with DVC and lakeFS, the four data artefacts plus end-to-end lineage.
RAG corpus curation: the active librarian, five layers: schema, dedup, PII, anti-contamination, lineage.
LLM Guard: Vault and Anonymize, runtime anonymisation with restitution.

Checklist.

Data governance document per dataset (training / RAG corpus / golden eval / enriched retrain).
Bias analysis by protected category with metrics (parity ratio, equalized odds, calibration).
PII / anonymisation / pseudonymisation procedure with measured F1.
Justification of representativeness for the intended context.
Verifiable chunk→trace lineage.

Art. 11 + Annex IV — Technical documentation

What it requires. A technical dossier with the nine Annex IV sections, drawn up before the system is placed on the market, maintained during operation, and available to authorities for ten years after the last operation. The nine sections:

General description of the system: name, version, purpose, integrator, intended hardware, instructions for use.
Detailed description of design and development: architecture, base models, training methods, design decisions with justification.
Information on monitoring, functioning and control: capabilities, limitations, expected accuracy, behaviour under normal use and foreseeable misuse.
Information on data: datasets used, sources, preparation methods, biases addressed.
Description of the monitoring system and metrics: traces, logs, dashboards.
Description of the QMS and the Art. 17 procedures.
FRIA where applicable (Fundamental Rights Impact Assessment, Art. 27).
Automatically generated logs that the system stores (Art. 12).
EU declaration of conformity under Art. 47, included.

The blog’s stack. It serves as a direct input for each section:

Annex IV section	Technical input from the blog
1. General description	Anatomy of the stack: 7 layers + seven deployment phases
2. Design and development	Six-stage LLMOps pipeline + continuous fine-tuning + modern alignment
3. Capabilities and limitations	Evals + LLM-as-judge
4. Data	Data versioning + RAG corpus curation
5. Monitoring	LLM tracing with OTel GenAI + prompt versioning
6. QMS	Procedures derived from ISO 42001
7. FRIA	Gap, see Art. 27 below
8. Logs	OTel tracing + retention and policies
9. Declaration of conformity	Documentary gap, see Art. 47 below

Checklist.

Annex IV dossier complete, versioned, dated, signed.
10-year retained access guaranteed (immutable / WORM storage).
Update procedure on substantial change.

Art. 12 + Art. 19 — Record-keeping (logs)

What it requires. A high-risk system must be technically capable of generating automatic logs during its operation. Those logs must allow:

Tracing how the system behaved over time.
Facilitating post-market monitoring (Art. 72).
Enabling investigation of serious incidents (Art. 73).
Supporting audits.

The provider must retain the logs for at least six months (or longer if national laws or the QMS require it). For remote biometric identification systems there are additional specific requirements.

The blog’s stack.

LLM tracing with OpenTelemetry GenAI, the canonical substrate. Every request emits a span with trace_id, gen_ai.* attributes, costs, latencies and guardrail decisions.
Prompt versioning: prompt_id + version travel as attributes.
Guardrails and safety in LLMs: gen_ai.guardrail.* attributes record every decision.
LLM Guard: spans per scanner with risk_score and action.
Data versioning: dataset_hash and model_version propagated.

Checklist.

OTel + backend (Tempo, Jaeger) running in production.
Minimum 6-month retention (24-36 months suggested for financial regulation).
WORM / immutable storage.
PII in logs redacted (via LLM Guard Vault or equivalent). Logs are not exempt from the GDPR.
Forensic query procedure with audited permissions.

Art. 13 — Transparency to deployers

What it requires. The provider gives the deployer instructions for use that are clear, complete and accessible, in comprehensible language, covering:

The provider’s identity.
Characteristics, capabilities, limitations (accuracy by category, technical specifications).
Foreseen changes to the system and its metrics.
Human oversight measures (Art. 14).
Expected computational resources and hardware.
When it applies, the expected lifetime of the system and of its maintenance.

The blog’s stack.

The OSS catalogue for LLMOps, which components and with what function.
OSS vs hyperscalers, lock-in analysis and documented dependencies.
Anatomy of an LLM request, capabilities and limitations at forensic level.

Checklist.

User manual in non-technical language for the deployer, plus a detailed technical manual.
Accuracy metrics by category with thresholds.
Change procedure with prior notification.

Art. 14 — Human oversight

What it requires. The system is designed to allow effective human oversight throughout the period of use, with interfaces and procedures that make it possible to:

Understand capabilities and limitations.
Detect malfunctions (automation bias awareness).
Decide not to use the system’s output, to override it, to reverse it.
For remote biometric identification: human verification before acting, by at least two people.

The blog’s stack.

Guardrails and safety, line 3 (Tool GR) with human-in-the-loop for destructive actions.
Evals, metrics on a human-accessible dashboard.
OTel tracing, Langfuse with auditable human sessions.

Checklist.

Oversight interface documented with use cases.
Override / abort capability with no technical restrictions.
Documented training for oversight personnel.
Metrics of the effectiveness of the oversight (override rate, false-negative rate of the oversight itself).

Art. 15 — Accuracy, robustness and cybersecurity

What it requires. High-risk systems are designed and developed to reach an appropriate level of accuracy, robustness and cybersecurity, and to perform consistently throughout their lifecycle. The relevant accuracy metrics are declared in the instructions for use. Resilience against:

Errors, faults and inconsistencies within the environment of use.
Feedback bias during operation (feedback loops).
Attacks that try to exploit the system’s vulnerabilities (data poisoning, model poisoning, model evasion, confidentiality attacks).
Technical and organisational measures to detect, respond to and resolve vulnerabilities.

The blog’s stack.

Quantisation fundamentals, accuracy vs efficiency with reported metrics.
Continuous batching + KV cache, operational robustness.
Guardrails: line 1 input + line 2 retrieval, defence against prompt injection and data poisoning via RAG.
LLM Guard: PromptGuard 2 + injection scanners, direct adversarial mitigation.
Evals: jailbreak resistance + adversarial, robustness metrics evaluated in CI.

Checklist.

Declared accuracy metrics: F1 by category, accuracy, calibration, RAG faithfulness, hallucination rate.
Robustness plan against adversarial inputs (Garak suite / Promptfoo redteam / PyRIT run periodically).
Cybersecurity plan: vulnerability management, patching of the stack (vLLM, its deps, CUDA), secrets rotation.
Analysis of potential feedback loops with drift monitoring.

Art. 17 — Quality management system (QMS)

What it requires. The provider has a written, systematic and proportionate QMS covering (without being limited to):

Regulatory compliance strategy.
Design, verification and quality control of the system.
Testing and validation procedures.
Data management.
The risk management system (Art. 9).
Post-market monitoring (Art. 72).
Incident reporting (Art. 73).
Communication with authorities, deployers and other stakeholders.
Records: documentation, log maintenance.
Resource management.
Accountability: management responsibilities.

The blog’s stack. The QMS is not code, but it leans on code.

ISO/IEC 42001 implemented (previous post) covers practically the whole content of Art. 17.
Six-stage LLMOps pipeline as the reference operating procedure.

Checklist.

QMS manual written, dated, signed, versioned.
Annual internal audit plan with criteria and records.
Management review agenda with signed minutes.
If 42001 is implemented: documented QMS-42001 mapping.

Art. 26 — Deployer obligations

What it requires. Whoever deploys the system (uses it under their own authority, not necessarily the developer) has obligations of their own:

Use the system in accordance with the instructions (Art. 13).
Assign competent, trained human oversight (Art. 14).
Ensure the input data under their control is appropriate.
Monitor operation and notify the provider on detecting problems or serious incidents.
Keep the logs under their control for at least 6 months.
Inform the affected persons when the system is used on them to make decisions (and, in an employment context, also consult their representatives).
For some Annex III cases: complete a FRIA (Art. 27).

The blog’s stack. In the case of the multi-tenant chatbot, the deployer is the client insurer. It must:

Accept the provider’s instructions (the consultancy’s) and sign the terms.
Configure human oversight on its side.
Notify the provider when it detects drift or a serious complaint.
Keep its own logs in addition to the provider’s.

Checklist (for the deployer).

Contract with the provider covering SLAs, responsibilities, exit plan.
Training programme for oversight personnel.
Incident notification procedure towards the provider.
Policy for informing affected persons (in the employment context, notification to representatives).
FRIA where applicable.

Art. 27 — Fundamental Rights Impact Assessment (FRIA)

What it requires. Applicable to deployers that are public bodies or private entities providing public services, or that use systems to assess credit score or life insurance. Before first use, the deployer carries out a FRIA documenting:

A description of the intended use.
Period and frequency of use.
Categories of affected persons.
Specific risks of harm identified.
Human oversight measures.
Mitigation measures should the risks materialise.

The FRIA is notified to the market surveillance authority. Substantial changes force an update.

The blog’s stack. The FRIA is a governance document, not a technical artefact. The blog does not cover it directly. But the technical input is:

The impact analyses from the ISO 42001 post, section A.5 are the natural starting point.
The metrics from the evals post on fairness by category and groundedness feed the risk section of the FRIA.

Checklist.

FRIA procedure documented, aligned with the AIIA in ISO 42005 (published as a complement).
FRIA carried out per system before first use.
Notification to the market surveillance authority.
Periodic review, plus on substantial change.

Art. 47 — EU declaration of conformity

What it requires. The provider draws up a written declaration of conformity per high-risk system, stating:

Identification of the system and the provider.
A statement that it complies with Arts. 8-15 + Art. 17.
Reference to the harmonised standards and common specifications applied.
Where applicable, the notified body and the certificate.
Place and date, signature and name of the authorised signatory.

It must be available to authorities for ten years. It is kept up to date.

The blog’s stack. A pure legal document. Template in Annex V.

Checklist.

Declaration of conformity signed by an authorised person before market placement.
Languages: at least the official EU language of the market where the system is placed.
Re-signing procedure on substantial change.

Art. 48 — CE marking

What it requires. A high-risk system carries the CE marking visibly, legibly and indelibly. For digital systems with no physical part, the marking is included in the documentation or the interface. If a notified body was involved, its number follows.

The blog’s stack. CE marking on a software system typically materialises in:

The product information or “About” page.
The official product documentation delivered to the deployer.
Metadata of the exposed API (custom HTTP header, OpenAPI info).

Checklist.

CE marking visible in the product interface or official documentation.
Notified body number attached where applicable.
Update procedure on substantial change.

Art. 49 — Registration in the European database

What it requires. Before placing on the market or putting into service a high-risk Annex III system (except area 2, critical infrastructure), the provider registers it in the EU database of high-risk AI systems managed by the Commission. Deployers that are public authorities also register their use. Most registration data is public (transparency towards the public).

The blog’s stack. A pure administrative procedure. No technical part beyond having the dossier ready.

Checklist.

Registration completed before first productive use.
Update on substantial change.
Portal access maintained (credentials, contact).

Art. 50 — Transparency to end users

What it requires. Applies to limited risk systems (and, complementarily, to some high-risk ones too):

Chatbots and AI assistants: the person interacting must know they are talking to an AI, unless it is obvious from the context.
Generated synthetic content (text, audio, image, video): marked as AI-generated in the output, in a machine-readable format.
Deepfakes: explicitly declare that the content is artificially generated or manipulated.
Emotion detectors or biometric categorisation: inform the affected persons.

The blog’s stack. Technical materialisation:

A UI banner in the chatbot saying “You are talking to an AI assistant”.
A disclaimer on every exportable response (PDF, email): “Generated by AI”.
Watermarking of the output (perplexity-based, model-fingerprint), optional but useful for deepfakes.
For generated audio, image or video, standard C2PA metadata.

Checklist.

Mandatory UI banner.
Disclaimer on exportable outputs.
If it generates visual content: C2PA marking or equivalent.
Procedure for use of the system on a person without their knowledge (for example, automated CV screening).

Art. 53 — Obligations of GPAI providers (in force since 2 Aug 2025)

What it requires. Providers of GPAI (general-purpose models trained with vast compute, typically foundational: Llama 4, Mistral, DeepSeek, Qwen, Gemma) must:

Maintain technical documentation of the model, accessible to the AI Office and national authorities.
Make information available to downstream providers that will integrate it.
Comply with EU copyright (Art. 4 of Directive 2019/790): an opt-out mechanism for rightsholders.
Publish a summary of the training content (Annex XI, copyright summary).

If the model has systemic risk (10^25 FLOPs threshold, or designated by the Commission), additional obligations apply (Art. 55): model evaluation, adversarial testing, incident reporting, cybersecurity.

The blog’s stack. For an organisation that uses GPAI models (Llama 4, Mistral) and does not train them from scratch:

It is not a GPAI provider; it is a downstream provider integrating GPAI into its system.
It must hold the GPAI technical documentation (Llama paper, Mistral docs) and reference it in its own Annex IV documentation.
Analysis of the specific GPAI licence (Llama Community License, Apache 2.0, and so on).
The post on modern alignment and continuous fine-tuning describe how a LoRA adapter on top of the GPAI does not turn the downstream party into a GPAI provider, as long as it does not train a new model from scratch.

Checklist (downstream provider).

Inventory of GPAI models used, with version, source, licence, referenced documentation.
Mapping of responsibilities between the upstream GPAI provider and us as downstream.

Art. 72 — Post-market monitoring

What it requires. A documented post-market monitoring system proportionate to the risk, collecting data on performance throughout the lifecycle, including interaction with other AI systems. It allows the provider to:

Assess continuous compliance with Arts. 8-15.
Adopt the necessary corrective measures.
Detect trends in real use (drift, abuse).

The monitoring plan is part of Annex IV and is maintained throughout the system’s life. The Commission publishes a template in 2026.

The blog’s stack.

OTel tracing + Langfuse, the base.
Continuous evals, operational metrics as online gates.
LLM-as-judge, judges over production sampling to detect degradation.
Incident-driven retrain, the closed improvement loop.

Checklist.

Post-market monitoring plan documented per system.
Operational metrics defined with thresholds and periodic review.
Corrective action procedure on alert.
Integration with Art. 73 (when an alert equals a serious incident).

Art. 73 — Serious incident reporting

What it requires. The definition of a serious incident (Art. 3(49)):

Death or serious harm to health.
Serious disruption of critical infrastructure.
Infringement of legal obligations intended to protect fundamental rights.
Serious damage to property or the environment.

The provider reports to the market surveillance authority of the Member State where the incident occurred. Deadlines:

Type of incident	Maximum deadline from becoming aware
General	15 days
Death	10 days
Critical infra affected, or widespread infringement	2 days

The first report may be preliminary; the complete one follows later. Internal investigation is mandatory, as is cooperation with the authorities. Corrective action is proportionate.

The blog’s stack. The technical flow:

OTel tracing provides the traceability for forensic investigation.
Guardrails and safety emits the canonical incident_event (category, severity, trace_id).
Incident-driven retrain materialises the corrective action.

Checklist.

Incident reporting procedure documented with deadlines and templates.
Designated person (typically DPO + AI Risk Owner) with responsibility and training.
Annual dry-run of the procedure (drill).
Technical integration between the guardrails / tracing layer and the notification channel.

The assembled Annex IV dossier: SVG of the complete file

The diagram shows the blog’s editorial asymmetry: seven of the nine Annex IV sections are covered directly by the technical stack. Only the FRIA (section 7) and the signed declaration of conformity (section 9, not shown in the SVG because it is a one-page document) are documentary gaps needing express administrative work. The main compliance effort is assembling and signing, not building from scratch.

Applied case: the multi-tenant chatbot assessed against the AI Act

We take the system from the forensic post, a multi-tenant customer support chatbot for insurers, and walk through it as the provider of the system.

Art. 6 classification: the chatbot helps customers understand products, check status and open tickets. It does not automate contractual decisions (it does not approve claims, it does not calculate premiums). Does it fall into Annex III area 8 (essential private services)? That depends on the use. If the insurer uses it only for informational support, it is limited risk (Art. 50 applies). If it uses it to assess claim declarations, it is high risk. Documenting the analysis is mandatory.

We assume high risk for the complete walkthrough:

Art. 5 prohibitions: written statement of non-applicability. ✓
Art. 9 risk management: per-system document with identified risks (hallucination, dialect bias, PII leakage, jailbreak), applied mitigations (RAG over a curated corpus, guardrails with 4 lines, LLM Guard Vault, continuous evals) and signed accepted residuals. ✓ (input: pipeline + guardrails + evals).
Art. 10 data governance: governance of the four datasets (training adapter, insurer RAG corpus, golden eval, enriched retrain) with biases analysed, PII anonymised, lineage in place. ✓ (input: data-versioning + rag-corpus-curation + LLM Guard).
Art. 11 + Annex IV: dossier with 9 sections drafted, signed, accessible for 10 years in a WORM bucket. ✓ (7 sections from the blog, 2 new).
Art. 12 + Art. 19 logs: OTel + Tempo + Langfuse with 24-month retention, PII redacted by Vault. ✓
Art. 13 transparency to deployers: user manual for the insurer plus a technical manual. ✓ (input: OSS catalogue + request anatomy).
Art. 14 human oversight: Langfuse + Grafana dashboard, human escalation protocol for critical cases, training for the insurer’s staff. ✓
Art. 15 accuracy, robustness, cybersecurity: F1 by category declared, Promptfoo redteam adversarial suite run monthly, stack cybersecurity plan (vLLM patching, secrets rotation). ✓
Art. 17 QMS: ISO 42001 implemented and certified. ✓
Art. 26 deployer: the contract with the insurer includes the deployer’s obligations. ✓
Art. 27 FRIA: the insurer carries out a FRIA before first use (it is a private essential-service entity). ✓ (deployer’s responsibility, the provider assists).
Art. 47 declaration of conformity: signed by the consultancy’s CTO before market placement. ✓
Art. 48 CE marking: visible in the chatbot interface and in the official documentation. ✓
Art. 49 EU DB registration: completed before first productive use. ✓
Art. 50 transparency to users: UI banner “You are talking to an AI assistant”, disclaimer on exportable responses. ✓
Art. 53 GPAI: Llama 4 documentation (the base model) referenced, plus EU copyright analysis and responsibility mapping. ✓
Art. 72 post-market monitoring: documented plan, OTel + continuous evals + retrain already running. ✓
Art. 73 incident reporting: procedure, designated owner, annual dry-run. ✓

Result: certifiable and deployable on the EU market on 2 August 2026. The key gaps (FRIA, CE marking, EU DB registration, declaration of conformity) are documentary work over technical artefacts that already exist, not new technical projects.

Penalties (Art. 99)

The penalty table is proportional to worldwide turnover or to an absolute cap, whichever is higher:

Violation	Penalty cap
Art. 5 (prohibited practices)	Up to 35 M€ or 7% of annual worldwide turnover
Other obligations (Arts. 8-22, 26-50, 72-73, and so on)	Up to 15 M€ or 3% of annual worldwide turnover
Incorrect or misleading information to authorities	Up to 7.5 M€ or 1% of annual worldwide turnover

For SMEs and startups the caps are the lower of the two figures (not the higher). The proportionality mitigation exists but requires formal demonstration.

In addition, national authorities can order:

Immediate suspension of the system on the market.
A mandatory recall.
Mandatory public communication of the penalty.

The five frequent compliance traps

Trap 1 — Assuming the GPAI model used already covers the obligations. The downstream provider remains responsible for the integrated system: neither Meta nor Mistral nor DeepSeek takes on the obligations of whoever builds on their models. The trap surfaces when the authority asks for the dossier and the team points at the Llama model card as if that were enough.

Trap 2 — Confusing ISO 42001 with EU AI Act conformity. Holding a 42001 certificate does not imply conformity: certification is not a FRIA, not CE marking, not EU database registration, not a signed declaration of conformity. Standardisation is progressing, but until ISO 42001 is published as a harmonised standard (it was not at the end of 2025), there is no presumption of conformity. The table of legal obligations runs on its own circuit.

Trap 3 — Forgetting incident reporting within the legal deadline. Fifteen days sounds long until an incident lands in the middle of the summer holidays. Two days for critical infrastructure is not negotiable. Without a documented procedure and an annual drill, the deadline is missed in silence. A penalty for misleading information (1% of worldwide turnover) follows if the incomplete reporting is discovered.

Trap 4 — Underestimating the deployer. The AI Act assigns obligations to both the provider and the deployer. A company that uses a hosted LLM integrated into its service (without developing it) is still a deployer with obligations of its own (Art. 26): human oversight, FRIA where applicable, notification to affected persons. The trap surfaces when the deployer assumes that “responsibility lies with the model provider”. It does not, not entirely.

Trap 5 — Leaving the FRIA until last. The FRIA (Art. 27) requires a fundamental rights impact analysis with qualitative dimensions (discrimination, privacy, social rights). It is not an afternoon’s document. It is carried out before first use, not after a problem is detected. Public deployers and private essential-service providers who leave it for “whenever they ask” take 4-8 weeks to produce a credible one, time they typically do not have when the inspection arrives.

What we have not covered (upcoming posts)

Concrete templates for each document: EU declaration of conformity (Annex V), full Annex IV dossier section by section, FRIA, post-market monitoring plan, initial serious incident report. Material for a post along the lines of “The EU AI Act compliance folder in 12 templates”.
Voluntary codes of practice published by the Commission under Art. 56, useful for limited-risk systems that want to demonstrate good behaviour without a legal obligation.
Comparative analysis of notified bodies for systems requiring third-party conformity assessment (mainly Annex I).
How compliance changes for LLM agents, systems with graduated autonomy, tool calling and the capacity to act. SC 42 and the AI Office are working on specific guidance.
The complete map of national authorities designated under Art. 70, plus the sectoral authorities that retain jurisdiction (AEPD for privacy, CNMV for financial services, Banco de España for banking, AESA for aviation).

References

Regulation (EU) 2024/1689 (EU AI Act) — Texto consolidado en EUR-Lex: https://eur-lex.europa.eu/eli/reg/2024/1689. Diario Oficial L 1689/12.7.2024.
EU AI Act Explorer (AI Act Service Desk, Comisión Europea): https://ai-act-service-desk.ec.europa.eu/en/ai-act-explorer.
AI Act Text portal (artificialintelligenceact.eu): artículos individuales con anotaciones.
Anexo IV — Technical documentation: estructura de los nueve apartados obligatorios.
Anexo V — EU declaration of conformity: plantilla obligatoria.
Anexo III — High-risk AI systems: las ocho áreas que clasifican un sistema como alto riesgo.
Anexo XI — Copyright training summary template: para GPAI providers.
NIST AI RMF 1.0 (2023) — https://www.nist.gov/itl/ai-risk-management-framework.
ISO/IEC 42001:2023 — sistema de gestión, complemento facilitador.
ISO/IEC 42005 — Impact assessment AI (publicada 2025 como guía técnica para FRIA).
Draft Commission guidance on serious incident reporting (2025) — borrador en consulta para Art. 73.

Ens on lo0 — Tech Blog

deepagents on a cluster of your own: the SDK is free, the server is not, and what you have to build in between

TL;DR

You are here: the harness arrives after the model

The analogy: the scaffolding and the crane

What deepagents actually is

What is no longer there

Where state lives

The backends

What grows in the database

The store, which does have cleanup

The isolation that does not exist

The model, and the trap you need to know about

The tools, and the MCP that is not where it seems

The subagents

Code execution

Observability, and the package it goes through

The server: here is where the free part ends

What you have to build

How it fits with activity logging

Checklist

Traps and things that are not what they look like

Closing

See also

Sources

Making the model prefer our tools: the priority that exists in no layer, the two primitives that do, and the `_meta` that crosses the gateway

TL;DR

You are here: the question that arrives after the third server

The analogy: the counter with two trays

What the specification says: nothing

The priority that exists and is no use

The only blessed filtering is by credential

Discovery does not discover tools

What there is in proposals

The layer that decides: the client

Claude Code

The other clients

The API layer

The test: the _meta crosses the gateway

The setup

The result

The three routes where it is lost

The library trap

What we have not tested

What LiteLLM can and cannot do

The cheap lever: the description, not the name

What does not work

The ladder, updated

The risk that has to be declared

Checklist

Traps and things that are not what they look like

Closing

See also

Sources

Completing Keycloak for MCP: the protected resource no SDK hands you ready-made, and the enterprise extension that skips the whole flow

TL;DR

You are here: the resource side

The analogy: the visa and the border checkpoint

Part 1. The split of obligations

What is new in the revision and affects the setup

Part 2. What the SDKs give, and what they do not

Protected resource metadata

Audience validation

The authentication challenge

Scopes, which are not per tool

Which revision each one announces

Part 3. Building the protected resource

Part 4. The hop from the gateway to the MCP server

What the gateway does today

Part 5. The enterprise extension, which changes the picture

And here comes the problem

What is already in the gateway, undocumented

Part 6. Per-tool authorisation

Part 7. What still has no standard

Part 8. Who covers what

Reference configuration

Checklist

Traps and things that are not what they look like

Closing

See also

The `priority` that exists and is no use

The test: the `_meta` crosses the gateway

The `litellm_jwtauth` fields that decide security