What it is
Checked against the Orcyx source tree at c339cf993 on 2026-09-14. Where this page describes something the build does not do yet, it says so in place rather than describing the intention.
Orcyx runs a Model Context Protocol server inside the app. It is how an agent — one of the app's own panes, or a separate tool you point at it — reads and writes the things the app owns: the Vault (the memory graph), the Ledger (the requirements record), kanban, swarm control, Time travel checkpoints, code retrieval, recipes and skills, and the audit scanner.
The surface is large. At the commit stamped above it is 86 tools, each with an access level, and there is a tool whose only job is to return the documentation for all of them — so an agent can learn the wire format of a call before making it, instead of guessing from a name.
Finding a running server
The server binds a random loopback port and mints a new bearer token on every boot. Both rotate together, which is the right security posture and the reason endpoint discovery needs a file rather than a convention.
On bind, the app writes the live endpoint next to the token file in its application data directory:
<app data>/orcyx/mcp-endpoint.json
That file is the single on-disk source an external process reads to find the server. The server itself writes it, so there is no second copy of the format to drift out of step. It carries the URL and the token, and also a pid and a version — which exist to solve the two failures below.
It carries a bearer token. It is created with owner-only permissions where the operating system supports them; treat it as a credential and never log its contents.
The failure you will actually hit
Restarting the app rotates the port and the token. An agent session that was already running when you restarted is holding a dead URL, and it has no way to learn that from the protocol — the next call simply fails to connect.
- A missing endpoint file means no app is running. That is reported as such, not as a generic connection failure.
- A rejected token is a different fact from a missing file, and is worth distinguishing, because the fix is different: one means start the app, the other means re-read the file.
- If an agent pane's tools stop answering after an app restart, the pane is pinned to the previous port. Re-establishing the connection is what fixes it; retrying the call is not.
Why the file carries a pid and a version
A descriptor left behind by an app that has since died looks exactly like one written by a live app a second ago — same URL, same token, same file. The pid is what separates them: a reader checks that the process is still alive before trusting the endpoint, rather than discovering it is not by timing out against a closed port.
The version is the same idea applied to the tool surface. A descriptor written by a different build can name tools that no longer exist, and a caller that trusts it issues a call that fails deep in the protocol instead of being told, up front, that it is talking to the wrong version.
A descriptor written by a build that predates these fields is treated as UNVERIFIABLE, not as good enough. The orcyx CLI reports it as such and refuses to proceed — which is exactly what happened on the machine that wrote these pages. See the CLI page for the verbatim message.
Access levels
Every tool carries an access level, so a caller can be granted reading without being granted writing. Calls are audited. Do not treat the loopback binding as the security boundary — the token is the boundary, and the file that holds it is the thing worth protecting.