Documentation · design

API and MCP

Design document. Everything the web interface shows is also available to a script, a reporting job, or an assistant, with the same provenance and the same permissions as the person asking.

API

Versioned under /api/v1. The OpenAPI description is generated from the same schemas the UI uses and is served by the edge itself, offline, at /api/v1/openapi.json.
Resources follow the model: /sites, /equipment/{id}, /equipment/{id}/points, /points/{id}/history, /alarms, /questions, /snapshots, /snapshots/{a}/diff/{b}, /artifacts/{hash}/assertions. Never the artifact bytes.
Every entity and relationship in a response carries its provenance.
Connector detail appears only inside a binding's native reference and a reading's source, never in a resource path. The API has no vendor words in it.

MCP

A Model Context Protocol server inside the edge, over stdio and HTTP, sharing the service layer and the authorization check with the API. The first tool set is read-only and scoped: no tool returns an unbounded point dump.

list_sites            find_equipment(query, scope)     describe_equipment(id)
get_point_values(ids) get_history(id, range)           list_alarms(scope, state)
list_open_questions   explain_assertion(id)            # returns the provenance chain
confirm_question(id, answer)                           # the only write in 0.1; writes to the model, not to a building

One authorization check

A single function sits under UI, API and MCP. An MCP session carries a user identity and role; an assistant cannot see more than the person who started it. Write tools to a building live in a separate capability set that is off unless a role grants it, and every call is audited.

No model inside

The edge contains no language model and calls none. MCP is the one place an operator can point a model of their choosing, including none, at the building's model. Nothing leaves the box unless the operator's own client sends it.