Integrate local MCP and standard Matter paths

ALYT’s local Model Context Protocol (MCP) server executes on the owning home hub with ALYT Cloud connected or disconnected. A supplied stdio transport adapter carries JSON-RPC over the hub’s existing encrypted LAN API. The adapter does not execute device actions itself. The existing LAN service remains available to ordinary clients at the same time. There is no additional HTTP listener, TLS service, or MCP task on the hub.

Prerequisites and Setup

• The local MCP runs on the home hub whether ALYT Cloud is online or offline.
• Use the encrypted LAN key authorized by the owner, kept private via the ALYT_LAN_NOISE_KEY environment variable. Never expose or transmit this credential in logs, docs, prompts, or source.
• Use Python 3.11 or newer. Install the optional alyt-sdk[local-mcp] package and import alyt_sdk.local_mcp.
• Launch the adapter with the discovered LAN host. Port 6053 is the existing hub service port, and the adapter frames bytes over stdio.
• The owner authorizes LAN key use for the chosen adapter; an installer may help with consent, but does not grant authority.

Discovery and Connection Process

• Use the installed hub’s discovered LAN address; do not configure port forwarding.
• The adapter refuses operation unless the connected hub advertises the local MCP service. A protocol reference response does not establish that a hub is ready.

Native MCP Workflow

• Use the protocol advertised by the connected hub. July 2026 requests carry params._meta with io.modelcontextprotocol/protocolVersion and object io.modelcontextprotocol/clientCapabilities, and those valid per-request metadata fields support stateless calls. server/discover reports versions, capabilities and server identity; legacy 2025-11-25 / 2025-06-18 initialization remains available alongside modern calls and ordinary encrypted LAN clients. No new MCU server, network task or TLS connection is introduced. An older installed hub must use its advertised legacy revision until its reviewed firmware is installed.
• The public local-MCP contract read returns the protocol version, supported methods, seven native tools, their exact JSON schemas, and size bounds. The tool definitions are exported from the actual firmware dispatcher. A legacy MCP client initializes through the stdio adapter; modern calls carry per-request metadata; pagination returns the complete tool set. Clients may borrow an already connected encrypted API client; they retain ownership of that connection.

GET /integrations/local-mcp/contract retains the legacy protocol/method enums for existing SDK clients. GET /integrations/local-mcp/contract/current exposes the current native contract including July discovery. Both require the same current home access and explicit tenant/property scope. Neither grants LAN access or starts a connection. Select the actual connected hub’s advertised protocol at runtime.

Request and Response Limits

• Request JSON is limited to 3072 UTF-8 bytes; the hub’s response limit is 8192 bytes. JSON-RPC batches and uninitialized tool calls are refused. An oversized or malformed native envelope is refused before argument allocation.

Owner Authorization and Recovery

• Before connecting, the homeowner must authorize use of the existing privileged encrypted LAN credential. Keep it in the adapter process’s private environment; never place it in a model prompt, tool arguments, logs, documentation, or a public repository. It is an owner credential, not a cloud OAuth token or a member-scoped grant. The transport does not provide independent per-person local permissions.
• Enumeration reads installed devices, local capabilities and known room IDs from the existing hub state. It does not create a second copy of household state. Empty rooms, people and occupancy cannot be inferred from a missing local record. Readings distinguish unknown, stale and known values. A refresh requests a bounded read; it does not turn an old cached value into a current physical observation. The events tool pages latest field observations after a monotonic cursor. It is not a durable history or a push subscription.

Available Native Tools

Tool	Description
alyt.enumerate	Page local device, capability, and room IDs. No invented people or empty rooms.
alyt.read	Read current fields; freshness may be known, stale, or unknown.
alyt.action	Trigger an authorized device action (admission ≠ physical completion). Requires effect/epoch.
alyt.multi_action	Up to eight independent actions, each admitted separately (not an atomic transaction).
alyt.events	Read latest per-field observations after a cursor. No durable event history or push subscription.
alyt.memory	Read internal/PSRAM heap stats for diagnostics.
alyt.matter	Operate Matter clusters with native TLV: read/write/invoke/subscribe/events/collect/cancel.

Device and Observation Semantics

• Enumeration reads reflect only what the hub knows now; empty or unknown rooms remain unknown. Missing record does not confirm absence.
• Readings identify known, stale, or unknown field values. Explicit refresh requests only a bounded read; they do not guarantee immediate sensor observations or update old cache.
• alyt.events pages latest field updates (not event history) after a monotonic cursor.

Performing Device Actions

• Each action requires: installed device ID, current boot epoch, and a fresh effect ID. The effect_identity helper uses decoded hub facts epoch and nowMonotonicMs; it returns the epoch/effectId pair from MCU time, not host time. Effect IDs expire in 30 seconds and are not renewed by retries.
• The hub always rechecks device, tenant, and property associations before dispatch. Multi-device actions are not atomic transactions; handle timeouts by inspecting present observations and previous outcomes.
• The adapter does not automatically retry uncertain effects or admitted-but-disconnected actions.

Matter Integration

• The Matter controller on the hub discovers endpoint DeviceTypeList, ServerList, ClientList and PartsList, plus cluster AttributeList, AcceptedCommandList, GeneratedCommandList, EventList, FeatureMap and ClusterRevision. The public Matter catalogue, device-type declaration, cluster declaration and owned endpoint profile reads expose standard schemas and discovered support. Supply the tenant and property explicitly; unrelated or narrowed memberships are refused. The reference contains 91 standardized types: 82 application and 9 utility types. These are not product SKUs or qualified-product counts and must not be added to the Zigbee model count.

Operating via alyt.matter

• The advanced local Matter tool can read, write, invoke, subscribe to attributes, read or subscribe to events, collect a bounded handle, and cancel it. It uses native Matter TLV and discovered full-width path IDs. Up to four generation-bound handles are retained, with bounded reports and request payloads. Writes and invocations require the same current-home and fresh-effect checks. Standard access restrictions still apply. Fabric-management paths and vendor-specific effects are refused.
• Unknown future types retain their discovered IDs without invented semantics; a published reference declaration may be unavailable. Vendor extensions require their own documented semantics and authorization.

Endpoint and Feature Cautions

• Use ordinary normalized controls for supported lights, switches, covers, locks and sensor readings. Generic cluster access does not imply that every standardized type has a purpose-built household UI, routine mapping, client-cluster behavior, media implementation or physical qualification. Inspect each endpoint’s reported features. Conditional features and cluster-list membership decide which standard paths exist; do not infer support from the product name or a catalogue row.
• The hub’s Matter controller owns its fabric and private keys. The MG24 provides the existing radio controllers over CPC; the ESP32 hardware Bluetooth controller remains disabled. Matter-over-Thread needs an attached Thread network; Matter over Wi-Fi uses IP on the home network. Existing fabrics and Zigbee/BLE connections remain under their existing owners.

Security and Credential Boundaries

• The encrypted LAN key only authorizes fully owner-level access on the given hub in its present home context.
• No per-user, member, or session-scoped access is enforced by the local MCP adapter or transport.

Product compatibility counts

Hub and Connectors publish a searchable model catalogue with the same brand / model unit for both protocols. The reviewed snapshot contains 4478 Zigbee models and 3249 certified Matter models, with four exact cross-protocol model overlaps: 7723 distinct models across 805 published brands / vendor names. Software certificate editions are grouped; test vendors, unnamed entries and utility-only / unknown-type entries are excluded. CSA DCL provenance and separate protocol lists are retained. Certification and catalogue inclusion do not prove ALYT physical testing of every product or household UI support for every optional / media / vendor feature. The 91 Matter Device Library categories remain a separate engineering reference, never added to the product totals. The catalogue stays entirely outside ESP32 memory.

Local MCP and Matter paths provide standardized device control bounded by the hub’s current ownership, secure local credentials, and strict request / response sizing whenever the ALYT cloud is unreachable.