Runtime Configuration Snapshots
Purpose
This functional area composes live runtime behavior from administrative configuration.
It is responsible for loading, caching, and invalidating the full execution configuration needed for each tenant and client application, so the Runtime can behave as a stable and pre-composed execution layer.
Main Capabilities
- build tenant and client-specific snapshots
- combine mappings, toolsets, policies, and downstream settings
- cache snapshots in a two-layer model
- invalidate snapshots on configuration changes
- track a version stamp for database-based invalidation
- deduplicate concurrent snapshot builds for the same key
Snapshot Content
Runtime snapshots combine:
- published mappings
- MCP toolsets
- client application assignments
- client application prompt metadata
- target systems
- authentication profiles
- credential workflow definitions
- tool access policies
Snapshot Scope
Snapshots are scoped per tenant and per client application.
This means:
- different client applications within the same tenant can see different toolset visibility
- different client applications within the same tenant can resolve different effective MCP system prompts
- toolsets are filtered to those assigned to the requesting client application
- each combination has its own cache entry and invalidation lifecycle
Two-Layer Cache
The snapshot provider uses a two-layer cache to minimize latency and support distributed deployments.
L1 — In-Process Memory Cache
The first layer is an in-process memory cache that holds the fully materialized snapshot object.
Characteristics:
- zero serialization cost on a cache hit
- no TTL by default — entries persist until explicitly invalidated
- optimized for fast local access within each runtime instance
L2 — Distributed Cache
The second layer is a distributed cache that holds a serializable snapshot payload.
Characteristics:
- shared across process restarts
- supports distributed cache-backed snapshot reuse across deployments
- entries expire after a configurable absolute expiration period (default 24 hours)
Resolution Order
The snapshot provider follows this sequence on each request:
- L1 hit → return immediately (zero allocation beyond the return value)
- L1 miss + L2 hit → deserialize, rebuild the L1 entry, return
- L1 miss + L2 miss → load from database, populate L2, populate L1, return
Concurrent requests for the same key are deduplicated so only one database load happens at a time even under concurrent load.
Cache Invalidation
Two invalidation modes are supported, configurable through Runtime:Cache:InvalidationMode.
Bus Mode (Default)
In Bus mode, invalidation is event-driven through the message bus.
When administrative configuration changes in the Portal, an invalidation message is published. The Runtime consumes this message and evicts the affected tenant's L1 and L2 entries.
This mode is well suited to distributed deployments.
Client application changes are snapshot-affecting events. This includes changes to client metadata that influence effective MCP prompt composition, such as the client application's optional system prompt.
Database Mode
In Database mode, the snapshot provider computes a version stamp from live database state on every L1 and L2 read.
If the stored version stamp does not match the current state, the snapshot is evicted and rebuilt from the database.
The version stamp is derived from counts and last-updated timestamps across:
- mappings
- client applications
- toolsets
- tool endpoint authentication bindings
- tool access policies
- target systems
- authentication profiles
- credential workflow definitions
This mode provides an alternative invalidation strategy for deployments that prefer database-driven freshness checks.
Because the version stamp includes client application update timestamps, editing a client application's system prompt forces affected tenant/client snapshots to be rebuilt even when bus invalidation is not being used.
Cache Configuration
Cache behavior is controlled through the Runtime:Cache configuration section.
Configurable options include:
Enabled— enables or disables snapshot cachingInvalidationMode—BusorDatabaseSnapshotAbsoluteExpirationHours— how long L2 entries are kept before unconditional expiry (default 24 hours)CredentialAbsoluteExpirationMinutes— how long resolved credential sets are kept in the distributed cache (default 5 minutes)
Functional Value
This area gives the Runtime a predictable execution model and keeps configuration-driven behavior consistent across requests, tenants, and deployment scenarios.