I’ve been playing with Cynitor this weekend and it has a lot of promise. I was able to get it working on an Arduino UnoQ which was neat.
Looking at how Cynitor’s server and dashboard communicate over a REST API (/api/...) and a WebSocket stream (/ws) and I’m wanting to have another level of formality here. Today the Python server is the specification, and WEBSOCKET_README.md describes it in prose. I want to write the protocol down as a versioned, machine-checkable specification built from five existing standards (see below). Then any server and any client (and any agent), in any language, can implement this protocol as a standard way to remotely monitor Cyphal systems.
This will also allow us to build an MCP server adapter in front of Cynitor servers which would unlock significant intellegence for Cyphal networks.
We also would include RFC 6750 Bearer tokens, OAuth 2 scopes, RFC 9728 metadata for authentication and authorization in the protocol.
Core rules (draft)
Versioning. The protocol has its own Semantic Version, independent of Cynitor’s release number. A server MUST report it as protocol_version. A server MUST accept the WebSocket subprotocol cynitor.v<major> (RFC 6455 §1.9). A client MAY offer that subprotocol.
Extensibility. Receivers MUST ignore object members and WebSocket message types they don’t recognise. Within a major version, senders MUST NOT remove a member or change its type or meaning. Adding members, message types or endpoints is a minor change.
WebSocket framing. Every WebSocket message MUST be a single JSON object in a text frame, with a string member type.
Errors. Every HTTP 4xx/5xx response MUST carry an RFC 9457 application/problem+json body. Endpoint-specific details are extension members. A WebSocket error MUST be sent as {"type": "error", "error": "<message>"}, and the connection stays open.
Numbers. A floating-point value that is NaN or infinite MUST be encoded as null, since JSON can’t represent those values.
Time.timestamp members MUST be RFC 3339 strings with a UTC offset. Members ending in _unix MUST be Unix seconds as a JSON number.
Mapping DSDL to JSON.PROTOCOL.md defines normatively how a decoded Cyphal value becomes JSON in attributes, for example that a port-ID bitmask becomes the list of IDs it sets. This part can’t be a fixed schema, because the types depend on the DSDL loaded at run time.
Deprecation. A deprecated member is marked "deprecated": true in its schema and kept until the next major version.
Authentication and authorization. A server that requires authentication MUST accept RFC 6750 Bearer tokens in the Authorization header. Every operation and every client WebSocket message type declares the scope it requires. A server MUST answer a request without valid credentials with 401 and one with insufficient scope with 403 , each with an RFC 9457 body and a WWW-Authenticate header. Since browsers cannot set headers on WebSocket or link requests, a server MUST also accept a single-use ticket from POST /api/tickets as the ticket query parameter. A server MUST close a WebSocket with code 4401 when its credential stops being valid.
Does it necessarily have to be an implementation-independent specification, as opposed to just a better and more formal specification of Cynitor’s protocol as part of the Cynitor project itself? One can still use it in third-party software, and Cynitor can be treated as the reference implementation.
decoded Cyphal value
The draft seems to implicitly treat DSDL as the only serialization format. This is a good format, but since Cyphal v1.1 is on track to disown DSDL as part of its own specification, the design must accommodate other serialization formats as well.
This is just a draft to start the discussion so other formats can be on the table, however, I do think it should be implementation independent. I’d like this to be stable which, necessarily, requires it is independent. It is, specifically, a network-first protocol regardless. In that sense it is a formalization of the Cynitor server and not an alternative to it. Again, I think it’s important to use this as the basis for a table MCP binding to a Cyphal network which would require the protocol stay stable for multiple, independent clients (i.e. the Cynitor client and the MCP adapter). Furthermore, this allows the Cynitor client to move to a PWA which means it can be persisted on a client machine and take on offline tooling which will be advantageous.
A Cyphal MCP makes sense, but why does it necessarily have to share the same API with Cynitor? I’m worried we might end up with a spec that attempts to cover use cases that are not similar enough for it to stay compact. If the MCP is the main use case, then the spec could be part of its implementation?
Fair. I guess I should prototype a MCP server first and then see how different it is from the Cynitor server. I’m confident we’ll want an HTTP protocol for the MCP since it allows clients to connect remotely and for the server itself to present as a node which it wouldn’t be able to do if it were stdio.
Have you already started to work on the MCP adapter?
I have just put my own design proposal on the cynitors feat/mcp_adapter branch.
P.S. Sorry, cannot post links.
The proposal seems reasonable. I would start, however, with read-only operations. I’d add OAuth and use scopes later, where the default would be this “monitor” scope. We would then add scopes for “manage” and “operate” for operations that allow modifying the bus (manage) and injecting events onto the bus (operate). You can also use ToolAnnotations to help guild the AI in this regard but the hard-line security should live in the server where it can refuse with 403, a RFC 9457 problem body, and insufficient_scope. Handing over access to a physical bus without such protections will get the software flagged as malicious so I’d avoid any interim release without the proper OAuth protection in front of dangerous operations.
As for streaming; we’re never going to want the MCP tool call to return bulk data directly as this goes right into the context window. MCP tool calls should be considered control commands, not data pipelines. We’d want, instead, ways to set up, control, and compose such streams. This allows AI to (for example) build a python filter, use an MCP tool to start a stream of bus data, and pipe that data through the python filter in order to look for certain events. This is why I wanted to also standardize the protocol between the client and the server; to allow the MCP to have a well-defined, strongly typed, and stable interface it can build on top of using MCP as the control plane. MCP should always remain a basic set of tools that provide a well defined and self-documenting entry point. AI would then be excellent at composing more complex functions out of well-defined primitives in the client protocol.
Do I understand correctly that “modifying” here means configuring the interface between the MCP server and the bus, or am I misreading it?
Handing over access to a physical bus without such protections will get the software flagged as malicious so I’d avoid any interim release without the proper OAuth protection in front of dangerous operations.
Do I understand correctly that “modifying” here means configuring the interface between the MCP server and the bus, or am I misreading it?
misreading. It means modifying things like registers and the parameters of the nodes themselves. This is just a proposal but the three roles that make sense to me are
monitor – Read-only access to the bus.
operate – Full access to the bus but only for a set of messages that are about participation in the system operation, not administering the system itself.
manage – Access to the bus as needed to update firmware, modify registers, set parameters, and other messages that can affect the operation of nodes.
A fourth role would be “administer” or “root” or “all” which is a full-access policy that may or may not be the same as operate OR manage and where both operate and manage imply read-write bus access.
Such roles align with typical safety cases for robotics systems that might require various human lockouts based on modes where management is enabled. The ability to switch modes might also be something a system would grant only to the administer role.
In general, the ability to define roles allows for safe AI access to a physical bus with the caveat that strong OAuth authentication is in use given the propensity for AI to work around guardrails that are only enforced by policy.
Flagged by whom?
Anybody doing a threat-model or security review of a system where the software was in use?