Resources
Architecture
Data plane on the wire, control plane off it, and one shared restriction store connecting them.
Reading the diagram
Left — adoption
Agents call tools through the shim or proxy. Operators pin definitions. Platform runs the control plane and provisions SigNoz.
Centre — evidence
SigNoz is where MCP traffic, spans, the integrity verdict, and the enforcement record all become visible.
Right — machinery
Upstream MCP servers, the detector families and judge, and the control plane that contains.
Component map
src/kams/
transport/ stdio and streamable-HTTP adapters
protocol/ JSON-RPC parsing and MCP trace propagation
shim/ shared interception pipeline
detect/ integrity, injection, egress, cost, behaviour
policy/ declarative policy and sliding-window limits
telemetry/ OTel setup and semantic constants
daemon/ webhook, shared state, async enrichment
provisioning/ versioned SigNoz dashboard and alert
demo/ deterministic, alert-only, and Bedrock scenarios
tests/ detector, policy, telemetry-contract, and golden-wire tests
Transport adapters own I/O. The interceptor owns correlation, detection, policy, and telemetry. Detectors are pure — no I/O, no clock, no network — which is what lets the whole brain be exercised without Docker, SigNoz, or a live MCP server.
The two planes
| Data plane | Control plane | |
|---|---|---|
| Processes | One shim per connection, or one long-lived proxy | One kamsd |
| On the request path | Yes | No |
| Decides | Evidence in a single connection | Fleet-wide, time-windowed conditions |
| Writes | kams.lock, shared state, OTLP | Shared state, OTLP |
| If it dies | MCP traffic stops | MCP traffic is unaffected |
The daemon being off the request path is the reason a missing daemon or an unavailable SigNoz degrades observability and alert-driven policy without breaking otherwise healthy MCP traffic.
Failure behaviour
| Failure | Behaviour |
|---|---|
| SigNoz or OTLP unavailable | Export retries and buffers, then drops. MCP continues |
| Webhook daemon unavailable | No new alert-origin restriction; reflex policy remains |
| Detector or policy exception | Logged, treated fail-open |
| Shared-state file unreadable | Treated as empty |
| Upstream dies | Protocol error or EOF reaches the client; pending span closes as error |
| No incoming trace context | Valid root MCP span, propagation flag false |
| LLM enrichment unavailable | Deterministic finding and action unchanged |
Known boundaries
- Calls already pipelined before a restriction is installed cannot be recalled.
- The demo webhook assumes a trusted network and has no signature validation.
- Provider usage is turn-level, so measured cost is defensibly attributed but not tokenised independently per result.
- Alert evaluation is intentionally slower than the reflex path.
