# Proposal: a formal, implementation-independent specification for the Cynitor server protocol

**URL:** <https://forum.opencyphal.org/t/proposal-a-formal-implementation-independent-specification-for-the-cynitor-server-protocol/2895>\
**Category:** Applications & Usage\
**Created:** [November 1, 2026, 3:11am UTC](https://forum.opencyphal.org/t/proposal-a-formal-implementation-independent-specification-for-the-cynitor-server-protocol/2895 "2026-11-01T03:11:01Z")\
**Posts on this page:** 10\
**Page:** 1

<div class="post-metadata">

**Author:** ![scottdixon](https://forum.opencyphal.org/user_avatar/forum.opencyphal.org/scottdixon/32/39_2.png) [@scottdixon](https://forum.opencyphal.org/u/scottdixon)\
**Post date:** [November 1, 2026, 3:11am UTC](https://forum.opencyphal.org/t/proposal-a-formal-implementation-independent-specification-for-the-cynitor-server-protocol/2895/1 "2026-11-01T03:11:01Z")

</div>

I’ve been playing with [Cynitor](https://github.com/OpenCyphal-Garage/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`](https://github.com/OpenCyphal-Garage/cynitor/blob/main/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.

## Proposal

| Layer | Standard | Describes |
| --- | --- | --- |
| Data types | [JSON Schema 2020-12](https://json-schema.org/draft/2020-12) | Every payload, defined and shared by both API documents. |
| DSDL | Cyphal technical document | DSDL json interop |
| REST | [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.1.html) | Endpoints, parameters, status codes, auth |
| WebSocket | [AsyncAPI 3.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0) | `/ws` messages: who sends which, which ones get a reply |
| Errors | [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problem Details | The body of every HTTP error |
| Behaviour | [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) / [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174) keywords | Semantics schemas can’t express: ordering, rates, filter matching |

We also would include **RFC 6750 Bearer tokens, OAuth 2 scopes, RFC 9728 metadata** for authentication and authorization in the protocol.

## Core rules (draft)

1. **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](https://www.rfc-editor.org/rfc/rfc6455#section-1.9)). A client MAY offer that subprotocol.
2. **Extensibility.** Receivers MUST ignore object members and WebSocket message `type`s 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.
3. **WebSocket framing.** Every WebSocket message MUST be a single JSON object in a text frame, with a string member `type`.
4. **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.
5. **Numbers.** A floating-point value that is NaN or infinite MUST be encoded as `null`, since JSON can’t represent those values.
6. **Time.** `timestamp` members MUST be [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) strings with a UTC offset. Members ending in `_unix` MUST be Unix seconds as a JSON number.
7. **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.
8. **Deprecation.** A deprecated member is marked `"deprecated": true` in its schema and kept until the next major version.
9. **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.

## References

- JSON Schema 2020-12: [https://json-schema.org/draft/2020-12](https://json-schema.org/draft/2020-12)
- OpenAPI 3.1: [https://spec.openapis.org/oas/v3.1.1.html](https://spec.openapis.org/oas/v3.1.1.html)
- AsyncAPI 3.0: [https://www.asyncapi.com/docs/reference/specification/v3.0.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0)
- RFC 9457, Problem Details for HTTP APIs: [https://www.rfc-editor.org/rfc/rfc9457](https://www.rfc-editor.org/rfc/rfc9457)
- RFC 2119 and RFC 8174 (BCP 14), requirement keywords: [https://www.rfc-editor.org/rfc/rfc2119](https://www.rfc-editor.org/rfc/rfc2119), [https://www.rfc-editor.org/rfc/rfc8174](https://www.rfc-editor.org/rfc/rfc8174)
- RFC 6455, The WebSocket Protocol: [https://www.rfc-editor.org/rfc/rfc6455](https://www.rfc-editor.org/rfc/rfc6455)
- RFC 3339, Date and Time on the Internet: [https://www.rfc-editor.org/rfc/rfc3339](https://www.rfc-editor.org/rfc/rfc3339)

---

<div class="post-metadata">

**Author:** ![pavel.kirienko](https://forum.opencyphal.org/user_avatar/forum.opencyphal.org/pavel.kirienko/32/9_2.png) [@pavel.kirienko](https://forum.opencyphal.org/u/pavel.kirienko)\
**Post date:** [November 1, 2026, 5:44pm UTC](https://forum.opencyphal.org/t/proposal-a-formal-implementation-independent-specification-for-the-cynitor-server-protocol/2895/2 "2026-11-01T17:44:11Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![scottdixon](https://forum.opencyphal.org/user_avatar/forum.opencyphal.org/scottdixon/32/39_2.png) [@scottdixon](https://forum.opencyphal.org/u/scottdixon)\
**Post date:** [November 2, 2026, 2:51am UTC](https://forum.opencyphal.org/t/proposal-a-formal-implementation-independent-specification-for-the-cynitor-server-protocol/2895/3 "2026-11-02T02:51:01Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![pavel.kirienko](https://forum.opencyphal.org/user_avatar/forum.opencyphal.org/pavel.kirienko/32/9_2.png) [@pavel.kirienko](https://forum.opencyphal.org/u/pavel.kirienko)\
**Post date:** [November 2, 2026, 8:46am UTC](https://forum.opencyphal.org/t/proposal-a-formal-implementation-independent-specification-for-the-cynitor-server-protocol/2895/4 "2026-11-02T08:46:33Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![scottdixon](https://forum.opencyphal.org/user_avatar/forum.opencyphal.org/scottdixon/32/39_2.png) [@scottdixon](https://forum.opencyphal.org/u/scottdixon)\
**Post date:** [November 2, 2026, 4:54pm UTC](https://forum.opencyphal.org/t/proposal-a-formal-implementation-independent-specification-for-the-cynitor-server-protocol/2895/5 "2026-11-02T16:54:47Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![maladzenkau](https://forum.opencyphal.org/user_avatar/forum.opencyphal.org/maladzenkau/32/1782_2.png) [@maladzenkau](https://forum.opencyphal.org/u/maladzenkau)\
**Post date:** [November 12, 2026, 10:18am UTC](https://forum.opencyphal.org/t/proposal-a-formal-implementation-independent-specification-for-the-cynitor-server-protocol/2895/6 "2026-11-12T10:18:27Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![scottdixon](https://forum.opencyphal.org/user_avatar/forum.opencyphal.org/scottdixon/32/39_2.png) [@scottdixon](https://forum.opencyphal.org/u/scottdixon)\
**Post date:** [November 12, 2026, 5:26pm UTC](https://forum.opencyphal.org/t/proposal-a-formal-implementation-independent-specification-for-the-cynitor-server-protocol/2895/7 "2026-11-12T17:26:10Z")

</div>

I have not started it. I’ll take a look at your proposal. Thanks.

---

<div class="post-metadata">

**Author:** ![scottdixon](https://forum.opencyphal.org/user_avatar/forum.opencyphal.org/scottdixon/32/39_2.png) [@scottdixon](https://forum.opencyphal.org/u/scottdixon)\
**Post date:** [November 18, 2026, 5:52pm UTC](https://forum.opencyphal.org/t/proposal-a-formal-implementation-independent-specification-for-the-cynitor-server-protocol/2895/8 "2026-11-18T17:52:21Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![pavel.kirienko](https://forum.opencyphal.org/user_avatar/forum.opencyphal.org/pavel.kirienko/32/9_2.png) [@pavel.kirienko](https://forum.opencyphal.org/u/pavel.kirienko)\
**Post date:** [November 20, 2026, 9:03pm UTC](https://forum.opencyphal.org/t/proposal-a-formal-implementation-independent-specification-for-the-cynitor-server-protocol/2895/9 "2026-11-20T21:03:08Z")

</div>

> [@scottdixon](#):
>
> We would then add scopes for “manage” and “operate” for operations that allow modifying the bus (manage) and injecting events onto the bus (operate).

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.

Flagged by whom?

---

<div class="post-metadata">

**Author:** ![scottdixon](https://forum.opencyphal.org/user_avatar/forum.opencyphal.org/scottdixon/32/39_2.png) [@scottdixon](https://forum.opencyphal.org/u/scottdixon)\
**Post date:** [November 21, 2026, 6:52pm UTC](https://forum.opencyphal.org/t/proposal-a-formal-implementation-independent-specification-for-the-cynitor-server-protocol/2895/10 "2026-11-21T18:52:49Z")

</div>

> 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

1. **monitor** – Read-only access to the bus.
2. **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.
3. **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?
