DCP — Device Context Protocol

Status: Draft v0.3 — May 2026 · Hardware-validated on ESP32-WROOM-32

A protocol that lets LLM agents safely control physical devices,
down to dollar-class microcontrollers.

Intent-level, transport-agnostic, capability-scoped. Compact wire format
(sub-50-byte frames). Self-contained firmware under 16 KB.

Complementary to MCP — a reference
Bridge translates DCP ↔ MCP so any MCP host (Claude Desktop, Claude Code,
IDE assistants) works zero-config.

Contents

• Why DCP?
• Design principles
• Architecture
• Quickstart
• Add a feature in 5 steps
• Wire format · full SPEC.md
• Manifest
• Roadmap
• Design rationale: docs/RATIONALE.md — why
  not MCP-on-MCU, why not WoT, why not Matter.

Why DCP?

MCP is excellent for SaaS tools, but assumes JSON-RPC over WebSocket and runtime
tool discovery. On an MCU with 32 KB of RAM, that's a non-starter.

DCP keeps MCP's mental model (manifest + tool calls) but:

• compiles to a compact CBOR wire format
• uses a static intent table (no runtime negotiation)
• moves safety enforcement to a Bridge process

A reference Bridge translates DCP ↔ MCP, so any MCP-compatible LLM works
out of the box. DCP is the last mile to physical hardware.

Why this matters in one chart: the protocol's schema decides how many
hallucinated or adversarial calls are stopped before any byte reaches a
device. DCP catches all six categories at the wire layer; the others
catch what their existing schema happens to cover.

Design principles

1. Intent, not register. set_brightness(50%), not write_pwm(pin=5, duty=128).
2. Units in the protocol. Every number declares a unit. No ambiguity.
3. Static intent table. Manifest known at compile time; runtime is pure binary.
4. Safety lives in the Bridge. Devices trust the Bridge; LLMs never see raw GPIO.
5. Idempotent by default. Non-idempotent intents must declare themselves.
6. Transport-agnostic. UART, BLE, MQTT, USB-CDC, WebSocket — one frame.

Architecture

The Bridge is the sole trust boundary. On every call it issues and
verifies capability tokens, enforces range/type/unit checks from the
manifest, and supports dry-run as a wire-format primitive. Devices
remain simple enough to fit on commodity microcontrollers; everything
the LLM is allowed to do is enforced before any byte traverses the
device boundary.

Validated on real hardware

As of v0.3 the reference firmware is measured-validated on an
ESP32-WROOM-32 dev board over CH340 USB-Serial at 115 200 baud:

• 10/10 round-trip tests pass (tools/test_uart_roundtrip.py)
• 88/88 Python unit & conformance tests pass
• Compiled firmware: 294 KB flash, 22.7 KB globals (Arduino-ESP32 core 3.3.8)
• The pure DCP layer is approximately 14 KB over a baseline empty
  sketch (measurement script in docs/paper/figures/)

DCP design target sits roughly 5× under IoT-MCP and 20× under Matter on
the same class of MCU. Hatched bars are design targets, plain bars are
measured / typical of the cited sources.

See docs/RATIONALE.md §7 for what the hardware
validation does and does not prove.

Manifest

dcp: 0.3
device:
  id:     lamp-kitchen-01
  model:  smart_lamp_v1
  vendor: example.dev

intents:
  - name: set_brightness
    params:
      level: { type: float, unit: percent, range: [0, 100] }
      fade:  { type: duration, unit: ms, default: 0 }
    capability: lamp.write
    idempotent: true
    dry_run: true

  - name: read_brightness
    returns: { type: float, unit: percent }
    capability: lamp.read

events:
  - name: motion_detected
    payload:
      confidence: { type: float, unit: ratio, range: [0, 1] }
    capability: lamp.read

intent_id = crc16(name) — manifests and firmware stay in sync without
coordination.

Wire format

A frame is a 6-byte fixed header + CBOR payload + an optional 16-byte
truncated HMAC-SHA256. Header fields:

Reply status codes: ok, denied, range, busy, unknown_intent, capability_required.

A typical set_brightness(50) call is 19 bytes on the wire; the MCP
JSON-RPC equivalent is approximately 180 bytes. The full normative spec
lives at SPEC.md.

Adding a feature

See docs/ADDING_FEATURES.md for the full
5-step loop with a worked blink(times, period) example. The short
version: edit the manifest, add a C++ handler + binding, recompile,
flash, restart the MCP server — the LLM picks up the new tool
automatically. The Bridge needs no code change.

Quickstart

# As a user — install from PyPI:
pip install "pydcp[mcp,serial]"            # or [mcp,serial,mqtt,ble] for all transports
dcp inspect examples/lamp_manifest.yaml    # parsed manifest summary
dcp serve   examples/lamp_manifest.yaml --simulator

# As a contributor — editable install from source:
git clone https://github.com/device-context-protocol/dcp.git
cd dcp
pip install -e ".[mcp,serial,mqtt,ble,dev]"
pytest                                     # all 88 tests
python examples/lamp_demo.py               # in-process bridge ↔ fake lamp

The PyPI package is named pydcp (the bare dcp is squatted by an
unrelated package). The import name is dcp. The protocol name is DCP.

Run as an MCP server

The reference Bridge ships an MCP server that exposes each DCP intent as an
MCP tool. With --simulator it spins up an in-process fake device, so you
can demo with no hardware.

dcp serve examples/lamp_manifest.yaml --simulator               # no hardware
dcp serve examples/lamp_manifest.yaml --serial COM3             # real ESP32 over UART
dcp serve examples/lamp_manifest.yaml --mqtt broker.lan:1883 \  # MQTT
            --mqtt-prefix dcp/lamp-kitchen
dcp serve examples/lamp_manifest.yaml --ble AA:BB:CC:DD:EE:FF \ # BLE
            --ble-service 12345678-1234-5678-1234-567812345678

Capability tokens (HMAC-SHA256)

For multi-tenant or scoped access, mint short-lived HMAC tokens and pass them
to the Bridge:

export DCP_SECRET=$(dcp token keygen)
dcp token mint --caps lamp.write,lamp.read --ttl 3600
# eyJjYXBzIjpb...sig

Tokens are verified by the Bridge on every call. The device sees only
already-authorized frames. Devices themselves do not verify signatures
in v0.2 — that requires on-device HMAC, which is on the roadmap.

To wire it into Claude Desktop, add this to your
claude_desktop_config.json:

{
  "mcpServers": {
    "smart-lamp": {
      "command": "dcp",
      "args": [
        "serve",
        "C:/path/to/protocol/examples/lamp_manifest.yaml",
        "--simulator"
      ]
    }
  }
}

Then ask Claude "set the lamp to 60% brightness". The call flow:

Claude ─MCP─▶ dcp serve ─Bridge─▶ Loopback ─DCP wire─▶ GenericSimulator

For production use, replace GenericSimulator with a real transport
(UART / MQTT / BLE — coming next).

What's not in v0.3 (intentional)

• Multi-device atomic transactions
• Firmware OTA
• Mesh routing (use Thread / Zigbee underneath if you need it)
• LLM-side authentication (delegated to the MCP host's session model)
• Native CAN FD frames (ESP32-S3 TWAI is classic CAN; v0.4 ESP32-P4
  port enables true CAN FD)

License

MIT.

Roadmap

• Wire format + manifest parser
• Reference Python Bridge with loopback transport
• Lamp example
• MCP server wrapper + CLI (dcp serve)
• Generic in-process device simulator
• UART transport (COBS framing + CRC-16)
• ESP32 reference firmware (Arduino-compatible C++)
• Design rationale (docs/RATIONALE.md)
• CI (GitHub Actions, Linux + Windows, py 3.11–3.13)
• MQTT transport
• HMAC-SHA256 capability tokens (Bridge-side enforcement)
• Manifest compiler: dcp codegen (YAML → C header)
• Compile-time DCP_ID(name) macro in firmware
• BLE GATT transport (bleak)
• Release prep: CONTRIBUTING / CHANGELOG / CoC / SECURITY / issue templates
• On-device HMAC verification (per-frame signatures, ESP32 firmware)
• ESP32 BLE peripheral example (NimBLE-Arduino)
• Conformance test suite (golden frames, language-neutral YAML)
• Codegen --stubs: emits handler signatures + binding table
• Quickstart video script (docs/QUICKSTART_VIDEO.md)
• Real-hardware UART validation (ESP32-WROOM-32, 10/10 round-trips)
• Public repo at device-context-protocol/dcp (v0.3.0 released)
• PyPI release (pip install pydcp)
• T-Panel S3 + CAN bus demo (firmware ready, awaiting hardware)
• LLM-driven hallucination-rejection benchmark (planned for v0.4 paper)
• ESP32-P4 port for native CAN FD