Skip to main content
Glama
actuator-mcp-authz

actuator-mcp-authz

by nagarjunr

actuator-mcp-authz

Physical-actuation extension of mcp-local-authz's control-plane-optional MCP authorization architecture, plus a new non-learned physical safety-envelope middleware. Implementation of a non-learned safety envelope for industrial relay and digital I/O control.

Code Ocean: Extending Offline MCP Authorization to Physical Actuation: A Non-Learned Safety Envelope for Industrial Relay and Digital I/O Control

What this is

The prior project (mcp-local-authz) established locally-rooted PKI, a signed declarative policy, protocol-native middleware enforcement, and a hash-chained audit log for MCP tool-servers exposing information tools (Eclipse Ditto, MQTT). That architecture answers "is this agent permitted to call this tool" -- it says nothing about whether an authorized command is physically safe to execute.

This project retrofits that authorization stack, unmodified, onto a new MCP tool-server wrapping a real industrial actuator: an Advantech ADAM-6060 (6-channel relay output, 6-channel digital input) over Modbus TCP. Underneath the unchanged authorization middleware, it adds a second FastMCP middleware implementing five non-learned physical safety rules: rate-limiting/duty-cycle enforcement, interlock/state-consistency enforcement, limit-switch/digital-input confirmation, local emergency-stop precedence, and degraded-network fail-safe reversion.

Related MCP server: otgate

Status

Implementation complete, verified end-to-end on real hardware (NVIDIA Jetson Orin Nano driving a real ADAM-6060, a real DC motor, a real 12V bulb, and a real pushbutton digital input). All 18 individual pass/fail checks (13 scenarios, 14 sub-checks, plus 4 corner cases found in a post-hoc coverage review) passed against the real, live rig -- see results/evaluation_results.md for the full evidence log.

  • ca/, policy_engine/ -- reused unmodified from mcp-local-authz (locally-rooted Ed25519 CA, signed policy engine, hash-chained audit log, FastMCP authorization middleware)

  • mcp_server/adam6060.py -- thin Modbus TCP wrapper around the ADAM-6060 (read digital inputs, read/write relays), the "vendor" device driver

  • mcp_server/adam_server.py -- the MCP tool-server itself; imports neither policy_engine nor safety_envelope, confirming the zero-source-change retrofit property

  • mcp_server/safety_envelope.py -- the new non-learned physical safety-envelope middleware (this project's actual novel contribution)

  • mcp_server/retrofit.py -- composes both middleware layers onto the vendor server via the host framework's own public extension point

  • mcp_server/setup_ca_and_policy.py -- one-time commissioning script: generates a fresh root CA, issues agent certs, signs the policy document

  • mcp_server/evaluation_harness.py -- the 13-scenario / 14-check evaluation battery, run for real against live hardware

  • hardware/assembly_guide.tex (+ compiled .pdf) -- full physical bring-up guide, corrected against the actual unit's terminal labels (including the Iso.GND digital-input-ground gotcha discovered during bring-up)

  • results/ -- full evaluation evidence: evaluation_results.md (narrative + table), evaluation_results.json / .jsonl (structured/raw logs), evidence_snapshot/ (sanitized runtime artifacts: signed policy, root CA certificate only, issued agent certificates, hash-chained audit logs -- no private keys are committed; regenerate a fresh CA and certs locally via mcp_server/setup_ca_and_policy.py to reproduce)

Running the evaluation yourself

Requires a real ADAM-6060 (or compatible Modbus TCP relay/DI module) reachable on the network; this is a hardware-in-the-loop evaluation, not a mocked test suite.

uv sync
uv run python -m mcp_server.setup_ca_and_policy   # one-time: generate CA, certs, signed policy
uv run python -m mcp_server.evaluation_harness    # runs all 13 scenarios against live hardware

Edit ADAM_HOST in mcp_server/evaluation_harness.py to point at your own module's IP. Scenario 11b (the positive DI0-confirmation case) requires a human to physically press the wired pushbutton during an announced 8-second window -- see the project's Evaluation notes for why this is reported as a single human-attended trial rather than a fully automated result.

License

MIT.

Known limitations

This is a research prototype. These gaps are known and listed here so nobody has to find them the hard way:

  • Agent identity is a bearer credential. The middleware checks that an agent's certificate chains to the local root CA, but it does not require proof that the caller holds the matching private key. Anyone who obtains the certificate blob sent in the request metadata can present it. Short certificate lifetimes limit the window. Per-call signing or transport-level mTLS would close it; neither is implemented.

  • The local clock is assumed to be trustworthy. The middleware passes clock_is_trusted=True to the policy engine, so time-windowed policy conditions and certificate validity checks rely on the host clock. The engine has a degraded-clock path, but nothing feeds it a real clock-health signal yet.

  • Recovery from a network partition does not verify actuator state. While the ADAM-6060 is unreachable, the watchdog marks the system degraded and tries to drive all relays off, which cannot succeed while the link is down. When the device becomes reachable again, the degraded flag is cleared without reading the relay state back or resynchronizing the tracked channel state, so relays may still be energized. After any partition, check the physical state before resuming. A fix would drive all outputs off, read them back, and require operator clearance before leaving the degraded state.

  • Key directories assume trusted parents. Key directories are created owner-only and checked without following symlinks, but their existing parent directories are not validated, so they must not be writable by other users. Key storage refuses to run on platforms without POSIX file semantics.

  • Key protection is filesystem-level only. Private keys are created owner-only (0600) in owner-only directories. There is no hardware-backed (TPM) key protection.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Provides AI agents with safe, governed read access to industrial control systems (OPC-UA, Modbus, S7, Mitsubishi, MTConnect, MQTT/Sparkplug) plus cross-protocol diagnostics for troubleshooting data breaks, alarm floods, and unhealthy tags.
      157
      11
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An OT-aware authorization MCP server for OPC UA that applies process-aware policies (value ranges, rate limits, interlocks) to every agent call, enabling safe industrial control with optional human approval workflows.
      66 PyPI
      Apache 2.0
    • A
      license
      B
      quality
      C
      maintenance
      Exposes a deterministic IoT edge runtime — Modbus/CAN/J1939 acquisition, local rules, alarms, and history — to AI assistants as typed, governed MCP tools. Reads are safe by default; device control stays deny-by-default, explicitly confirmed, and audited.
      23
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to discover, browse, read, search, and safely write OPC UA industrial device data within controlled edge networks, with guarded two-phase writes and evidence-based root-cause diagnostics.
      1
      Apache 2.0