onvif-mcp

The governed doorway between AI agents and video infrastructure.

Every tool call passes a fail-closed policy gate and emits a hash-chained, signed receipt — including denials.
The audit trail records what agents tried, not just what they did.

AAR specification · Conformance plan · Quick start · Report an issue

---

Agents are getting wired into everything. Nobody has shipped agent access to cameras and video systems that a security director could approve. This is that attempt.

Features

• Config drift executor — baseline, diff, and safe remediation tools are VAPIX-only for now
• MCP tools over stdio: list_cameras, get_snapshot, ptz_move, ptz_preset, get_receipts, plus the config-drift trio
• Inline snapshots — JPEG snapshots return MCP image content alongside the saved file path and SHA-256 hash
• Fail-closed per-agent policy — tool allowlist, camera allowlist, PTZ step bounds per agent identity; unknown agents get nothing
• Signed receipts on every call — hash-chained JSONL, ed25519-signed, produced frames content-hashed into the receipt; verification detects changes to signed receipt content at the affected sequence number. Verifiers also require each receipt line to equal JSON.stringify(parsed) and each handoff file to equal JSON.stringify(parsed, null, 2) + "\n" (parsed key order).
• Dual transport — AXIS VAPIX and ONVIF SOAP behind one tool contract, selected per camera
• No secrets on disk — camera credentials resolve from a local credential store at startup and are never written or logged

Commissioning-as-code turns a specs/*.yaml desired-state file into a read-only plan, an explicitly approved and postcondition-verified apply, or a later conformance check. Applies snapshot every changed parameter for rollback, verify PTZ presets by name, and merge named AXIS Object Analytics scenarios without removing unmanaged scenarios. Approved AOA writes require config.aoa: true; after readback, apply observes filtered AOA topics with a Bun WebSocket using Basic authentication over TLS (accepting the camera's self-signed certificate, like curl -k) and records counts and warnings in the signed handoff. Apply/verify runs emit signed JSON handoffs in handoff/, while parameter access stays inside the existing config grant and hard denylist. Both tools accept optional free-text notes (up to 2000 characters) to record installer or agent observations in the signed handoff; omitted notes are stored as null. Both tools also accept optional location (up to 200 characters), stored verbatim in the signed handoff and included in the public JSON as installer-entered, unverified text. Scene observations capture a reference JPEG and, for PTZ cameras, a subsequent device-reported position. Scene failures do not affect camspec conformance. Captured JPEGs stay out of the public repository (handoff/*.jpg); the signature authenticates the recorded frame hash, not the .jpg sitting next to it. The renderer checks the sidecar bytes against that signed hash.

Quick start

bun install

Describe your cameras in cameras.json:

{
  "lobby": { "base": "http://192.168.1.33", "user": "root", "credKey": "cam-lobby",
             "ptz": true, "protocol": "vapix" },
  "gate":  { "base": "http://192.168.1.32", "user": "root", "credKey": "cam-gate",
             "ptz": true, "protocol": "onvif", "profile": "profile_1_jpeg" }
}

Grant agents authority in policy.json (anything not granted is denied):

{
  "agents": {
    "claude-main": {
      "tools": ["list_cameras", "get_snapshot", "ptz_move", "get_receipts"],
      "cameras": ["lobby", "gate"],
      "ptz": { "maxStep": 30 }
    }
  }
}

The policy.json file is checked once at startup, and a wrong-typed value in any agent's grant stops the server with one line naming the agent and the field. Required keys are checked too, so a ptz grant without maxStep, a config grant without groups, or null in place of a grant stops the server even when that grant is never used, and a gateway restarted with such a file stays down until the file is corrected.

Register with an MCP client (Claude Code shown):

claude mcp add cameras -- env AGENT_ID=claude-main bun /path/to/onvif-mcp/index.ts

Audit the receipt chain any time:

bun index.ts --verify
# chain OK — every hash linked + signature valid

Tools

All tools persist receipts; some also save artifacts, replace baselines, or change camera state. MCP annotations are advisory; server policy still governs calls.

Tool	Does	Policy checks
list_cameras	Live device info for cameras this agent may see	agent known, tool granted
get_snapshot	Capture a JPEG, return path + SHA-256	+ camera granted
clock_check	Read the camera clock offset against this host (host sync not checked) and device-reported NTP status. Axis documents getDateTimeInfo as Viewer and getNTPInfo as Administrator, so under a viewer account NTP shows unavailable (no elevated retry).	+ camera granted
ptz_move	Relative pan/tilt/zoom in degrees	+ camera granted, camera is PTZ, step within maxStep
ptz_preset	Recall a named PTZ preset (VAPIX); emits an AAR wire bundle	+ camera granted, camera is PTZ, ptz grant
commission_plan	Diff parameters and named AOA scenarios; list applicable presets; no writes	+ camera granted, config groups granted, all params allowed, AOA grant for scenario specs
commission_apply	Dry-run unless approve:true; apply, read back, observe AOA events, roll back parameters on failure, emit signed handoff; optional notes (string, max 2000 characters)	+ plan checks, config remediation grant for approved writes, config.aoa for scenarios, ptz grant when an approved spec has presets on a PTZ camera
commission_verify	Check parameter, preset-name, and AOA scenario conformance; emit a signed handoff; optional notes (string, max 2000 characters)	+ camera granted, config groups granted, all params allowed, AOA grant for scenarios
get_receipts	Tail the signed receipt chain	agent known, tool granted

Every call — allowed or denied — appends a receipt. A denial looks like this:

{ "seq": 19, "profile": "aar-0.2-draft-alignment",
  "principal": { "role": "agent", "type": "service", "id": "claude-main" },
  "enforcement_point": "onvif-mcp/0.1.0", "node_kind": "authorization",
  "action": { "tool": "ptz_move", "params": { "camera": "gate", "pan": 90 } },
  "decision": "deny", "detail": "step exceeds policy maxStep 30°",
  "prev": "8fb7…", "hash": "8322…", "sig": "jRld…" }

Receipts and the AAR spec

Receipt semantics follow the Agent Action Receipts (AAR) v0.2 vocabulary: principals, enforcement points, node kinds (observation, action_attempt, authorization), and calibrated outcome-evidence levels (device_acknowledged, unknown). independently_sensed needs an observer outside the commanded device, so this server never emits it.

New snapshot/preset bundles are AAR v0.2.3 wire (pinned aar 96fb57b), with the attempt journaled before the camera send; the JSONL chain stays draft and bundles from before 2026-10-12 stay on the August pre-release wire. See alignment and offline validation.

Transports

Set protocol per camera: "vapix" (AXIS HTTP CGI) or "onvif" (SOAP services). Verified live against AXIS hardware: on AXIS OS 12.9.57 the admin user works for ONVIF over HTTP digest; older 12.x firmware requires a separate ONVIF account provisioned in the web UI. ONVIF RelativeMove uses the generic translation space — pan converts as degrees/360 (measured exact on hardware); tilt/zoom mapping is linear-approximate.

Status

Experimental (v0.1.0). Verified live against three AXIS cameras (two PTZ, one fixed dome) through real MCP client round-trips: physical PTZ motion with before/after frame proof, all denial paths exercised and receipted, and tamper-detection confirmed by mutating a receipt and watching --verify flag the exact sequence. Not production software — see the roadmap.

Roadmap

• AAR v0.2 wire-conformant receipt producer SHIPPED 2026-08-15 — receipts-aar/ emits deterministic-CBOR + COSE_Sign1 ES256 bundles for the pinned-ontology actions (camera.stream.view, camera.ptz.preset), offline-verified conformant by the spec's independent pyref verifier: bun index.ts --verify-aar. A conformant verdict proves wire integrity + binding, not receipt-body truth — scope, remaining narrative residue, and same-operator disclosures: docs/aar-alignment.md. Policy denials wire-emit too (decision deny, real refusal reason); receipt bodies carry real narrative (timestamps, agent identity, policy.json digest)
• Per-agent signing keys and signed policy objects (agent commissioning)
• Clip/recording export
• Non-AXIS ONVIF hardware validation
• Align to MCP spec 2026-07-28 once official SDK support lands — the stateless request/response core removes session plumbing and opens a serverless/edge deploy path for the gateway

Trademark note

ONVIF® is a trademark of ONVIF, Inc. This project is not affiliated with, endorsed by, or certified by ONVIF, Inc. The name is purely descriptive — this server speaks the ONVIF protocol as published in the open specifications. No ONVIF conformance is claimed or implied. No ONVIF logos are used and no WSDL files are redistributed; the SOAP envelopes are hand-authored.

License

MIT © 2026 Matthew Visher.

The AAR specification this project aligns with is separately licensed: spec text CC BY 4.0, reference code Apache-2.0.

Render a handoff for the customer: bun render-handoff.ts handoff/<file>.json --pdf (HTML + PDF next to the JSON; JSON stays the signed source of truth).

Known device quirk (AXIS Q6358-LE, OS 12.9.57): ptz.cgi?setserverpresetname=<new> returns 204 but the preset is not persisted; commission_verify catches this via query=presetposcam readback and reports preset:<name> as failed — which is the reason readback exists.

VAPIX OpenAPI + llms.txt (the quirks this server learned the hard way): https://github.com/oneshot2001/vapix-openapi