Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
The Agent MCP surface
Dodaios' agent ecosystem, offered outwards over the Model Context Protocol. Any MCP client that holds the control key — Claude Desktop, Cursor, VS Code, Codex, another Dodaios — can find the team, talk to it, give it work, watch the board and answer its approval requests.
This document is the contract. It is pinned by
tests/contract/test_agent_mcp_surface.py; a change here that is not a change
there is a client somewhere breaking silently.
1. Two surfaces, one mount
| URL | What it offers | For whom |
|---|---|---|
/api/control/mcp |
Dodaios' tools — open-app, google-calendar, wiki-recall, every registered tool plugin |
a session Dodaios itself spawned, reaching back in |
/api/control/mcp/agents |
the ecosystem — roster, board, rooms, assignments, approvals | any client holding the control key |
Both are Streamable HTTP, both authenticate with the Control API's bearer key, and loopback does not bypass it: anything on the machine could otherwise open a socket and start driving somebody's team.
Note the trailing slash: the tools surface is addressed as
/api/control/mcp/ (what dodaios_harness has always sent). Without it
Starlette answers a redirect that MCP clients do not follow. The agents URL
needs no slash — /api/control/mcp/agents is a path inside the mount.
They share one Starlette mount and dispatch on the rest of the path. This is
not a stylistic choice. A Mount on /api/control/mcp/agents compiles to
^/api/control/mcp/agents(?P<path>/.*)$ — it requires a segment after the
prefix, so a plain POST /api/control/mcp/agents never matches it and falls
through to the shorter mount. The client would then get the tools catalog on
the agents URL: same transport, same auth, wrong tools, no error anywhere.
2. Connecting a client
Preferred — the stdio bridge. The client launches a small process that forwards to the HTTP surface:
python -m dodaios.mcp.agents.bridge
It needs no URL in the config, survives Dodaios changing port, works from
clients that cannot send an Authorization header, and finds the control key
the way the app does (keyring → env → file). When Dodaios is not running the
client still connects and is told what to start, rather than showing a red
"server failed" — which matters, because a desktop client launches the bridge
at its startup, long before anyone opens Dodaios.
Direct — Streamable HTTP. For a remote Dodaios or a client that cannot launch a process:
{ "type": "http",
"url": "http://127.0.0.1:47821/api/control/mcp/agents",
"headers": { "Authorization": "Bearer <control key>" } }
Fewer moving parts, but the key lives in a config file — and a key in a config file is a key in a backup (AP-12).
One click — POST /api/agent-mcp/pair. The intended path. It mints this
client its OWN credential and returns the finished config in the same answer:
POST /api/agent-mcp/pair
{ "name": "Claude Desktop - MacBook", "scope": "work", "client": "claude-desktop" }
The response carries config_text — paste it, restart the client, done — and
the secret appears there once and never again, because only its hash is kept.
Add "install": true to write it into the client's config directly, or
"base_url": "http://192.168.1.50:47821" when pairing a client on another
machine.
Other endpoints. GET /api/agent-mcp/clients lists which clients this
machine has; GET /api/agent-mcp/snippet?client=… returns a block to paste;
POST /api/agent-mcp/connect writes it into the client's own config. Writing
merges — every other server in that file survives — and goes through a sibling
temp file, because a client reading a half-written config loses all its
servers, not just ours. Codex is never written to: a hand-formatted
config.toml is easy to corrupt and hard to restore, so it gets a snippet.
The entry is written as dodaios-agents. A client connected before the rename
holds it as jarvis-agents, and that entry keeps working untouched: it
launches the same bridge and calls the same path. The next connect or
pair with "install": true replaces it with dodaios-agents instead of
adding a second one, so the client never lists every tool twice. Which entry
is ours is decided by its target (the bridge module, or the surface URL),
never by its name: a server somebody else put under jarvis-agents stays
where it is. When pasting a snippet by hand, remove an existing
jarvis-agents entry in the same step.
Environment overrides, for a Dodaios that is not on this box:
JARVIS_API_URL— base URL of the Dodaios to driveJARVIS_CONTROL_KEY— the control key
3. Credentials: one per client
Two things open the agent surface.
The control key is the owner at their own machine: full scope, everything. It is the master credential for the whole Control API, so it should not travel into a config file — a key in a config file is a key in every backup (AP-12).
An MCP token is what a paired client gets. It is named, scoped, individually revocable, and its last use is stamped, so "who has access?" and "cut that one off" are each one call. Only the hash is stored; a stolen token file yields nothing to replay, and a lost token is re-issued rather than recovered.
| Scope | May do |
|---|---|
read |
look, never spend: roster, board, quests, capabilities, approvals |
work |
that, plus talk to agents, post quests, assign, speak in rooms, hire |
full |
that, plus governance: resolve approvals, the kill switch, import a team |
Scope is enforced by not listing a tool, not by refusing it afterwards: a model shown a tool it may not call will call it, read the refusal, and try again. Not offering it is the only honest way to say no. A call that slips through anyway — a client that cached an old list — still gets a plain sentence naming the scope it would need.
Manage them at GET /api/agent-mcp/tokens and
DELETE /api/agent-mcp/tokens/{id}.
Why a token passes the CSRF guard
Worth knowing, because it looks like a hole and is not. The app's surface guard
treats cookie- and open-access requests as browser-shaped and demands an
Origin header on unsafe methods; Bearer credentials are exempt, because a
browser cannot silently mint one. An MCP token is such a credential, so it is
exempt too — but only on /api/control/mcp/agents. Everywhere else it is
an unknown Bearer and authenticates nothing. That narrowness is deliberate: the
desktop UI routes (/api/settings/*) are not key-gated and rely on this guard,
so a token accepted app-wide would have opened them.
4. The tools
Twenty-four, grouped by intent. Everything marked $ starts spend, work, or stops the house; a client should gate those and the description says so.
Discovery
| Tool | What it answers |
|---|---|
ecosystem_status |
the whole house at a glance: agents by run state, active runs, running rooms, pending approvals, connected capabilities, kill switch |
agents_list |
the roster with run_state (idle / working / paused) |
agent_get |
one agent: roster row, recent board events, active runs, learned skills |
Conversation
| Tool | What it does |
|---|---|
agent_chat $ |
write to an agent and get its answer back — one turn on that agent's own session, returning the reply text and the tools it used |
agent_message $ |
leave a note on the board — delivered, but starts no turn and has no reply |
agent_assign $ |
give a task; the scheduler decides whether it runs |
agent_chat is the centre of the surface — it is what makes an MCP client a
keyboard. It waits up to timeout_s (default 180 s, max 600 s); a turn still
running when that expires comes back as status: "still_running" with the turn
id, and the answer lands on the board where agent_inbox finds it.
Quests — the strongest verb here
| Tool | What it does |
|---|---|
quest_post $ |
post a job WITHOUT naming who does it |
quests_list · quest_get |
the Quest Board, and one job's whole story |
quest_cancel $ · quest_retry $ |
stop it, or route it again |
quest_post is the tool to reach for when you know what you want done but not
who should do it. Deterministic Python — never a model — scores every agent on
focus overlap, whether the quest names them, and current load; if nobody fits,
it forges a new teammate for the job. The answer names the taker and why,
so the choice is reviewable.
The board
| Tool | What it reads |
|---|---|
agent_inbox |
everything addressed to one agent; page with after_seq |
board_events |
the whole ecosystem stream; filter by agent or trace_id to follow one task end to end |
Roster, rooms, governance
agent_create · capabilities_list · rooms_list · room_open ·
room_say $ · room_settle $ · approvals_list ·
approval_resolve $ · kill_switch $
Moving a team to another machine
| Tool | What it does |
|---|---|
ecosystem_export |
the team as a portable bundle |
ecosystem_import $ |
apply a bundle here; full scope only |
A bundle carries the design — every agent with its role, focus, model, permissions and budget — and never the operation: no secrets, no chat history, no board, no workspace paths, no subscription seats. The safe subset is an allowlist, so a roster field added later cannot leak by accident; a test fails instead.
Import matches by name: agents already on the target are updated, the rest
are created. Run it with dry_run first to see the plan. Importing twice
changes nothing the second time, which is what makes a retry harmless.
5. Resources and prompts
A standard that ships only tools makes every client rediscover the same state by hand, so the surface also serves:
Resources (read-only, attachable as context without spending a tool call):
jarvis://ecosystem— the house at a glancejarvis://agents— the rosterjarvis://capabilities— plugins, CLIs, MCP servers and skills the agents can usejarvis://agent/<id>— one teammate, listed per agent
Prompts (openings worth having ready):
standup— what is everyone working on, what is waiting on mebrief_agent— check an agent has what it needs, then hand the task oversettle_question— put a question to a room and report the conclusion
6. The design rules
Held deliberately, because a standard other clients rely on cannot drift:
- One tool per intent, not per endpoint.
agent_chatseats a session, subscribes, sends and waits — the caller says one thing. MCP clients have tool budgets; a REST mirror would spend them on plumbing. - Answers use the field names the REST layer already uses — snake_case,
agent_id,run_state,seq. One vocabulary, not two. - A refusal is typed and says what to do next. An unknown agent lists the known ones; a busy agent says it is mid-turn; a stopped ecosystem names the kill switch. Every failure leaves as readable text, never as an MCP error — an error is a dead end for the model, a sentence is not.
- Anything that spends is marked
dangerousand says so in its own description, so a client can gate it and the model knows before it calls.
7. What the surface cannot do
The safety seam is the house's, not a new one:
- No spawn vehicle. No tool here starts a background worker that starts another — the recursion the router tiers exist to prevent (AP-5/AP-14). A client is a person with a keyboard, not a second router.
- Work goes through the scheduler.
agent_assignis subject to the kill switch, the tier wall, depth ≤ 2, budgets and caps, and a refusal comes back as a typedVETOwith a reason. Trusted Python decides, never a model. - The kill switch is real. Engaged,
agent_chatrefuses; nothing runs until it is released. - Approvals are not bypassed. A remote client is not one of Dodaios' own
spawned sessions, so there is no chat card to route an ask to; parked actions
surface through
approvals_listand are answered withapproval_resolve— the same path a person at the keyboard uses.
8. Keeping new features in harmony
The drift this surface is most likely to die of is nobody noticing. Somebody adds a society route, the app grows a button, and every MCP client stays a version behind — nothing breaks, so nothing gets fixed.
tests/contract/test_agent_mcp_harmony.py makes that impossible to ignore. It
enumerates the society's REST surface and requires every route to be either
COVERED (naming the tool that exposes it) or WITHHELD (with one line saying why
a remote client does not get it). A new route fails the build until somebody
decides. Answering takes a minute; the point is that the decision is made.
It earned its keep the day it was written: it immediately caught the Quest
Board and the chat-binding route, both added hours earlier by other work, and
quest_post exists because of it.
Two more floors hold the surface up:
tests/contract/test_agent_mcp_every_tool.pyruns EVERY published tool against a live society and then asserts that the set it ran equals the set the surface publishes — so a tool cannot ship untested.tests/contract/test_agent_mcp_surface.pypins the tool set and the dangerous flags. Adding a tool is a feature; renaming or removing one breaks every connected client, so it fails here first.
9. Verified end to end
Against a running instance (headless), a real MCP client saw:
/api/control/mcp/agents→ serverjarvis-agents, the full tool set, the three fixed resources plus one per agent, 3 prompts, liveecosystem_status;/api/control/mcp/→ serverjarvis, its own 89 tools, noagent_chat— the surfaces do not leak into each other;- the stdio bridge (
python -m dodaios.mcp.agents.bridge) → the same catalog and the same live answers, which is the path a desktop client takes; - an unauthenticated POST → rejected before it reaches either surface.
Pairing and scopes, over the wire with real tokens:
- a
worktoken saw 21 tools, areadtoken 13, the control key all 24; - the
readtoken was offered no spending tool at all, and callingkill_switchanyway got a sentence naming the scope it would need; - the
worktoken couldquest_postbut never sawkill_switch; ecosystem_exportreturned the team with no secret-shaped string anywhere in it, andecosystem_importwas correctly refused to theworktoken;- revoking one token killed it immediately while the other client kept working.
That live run is also what caught the CSRF-guard bug described in §3 — every
unit test was green while the feature did not work at all, because unit tests
mount the ASGI app directly and never meet the guard.
tests/unit/mcp/test_agent_mcp_origin_guard.py now covers it.
10. Where the code is
| File | Role |
|---|---|
dodaios/mcp/agents/tools.py |
the tool set: schemas, handlers, the refusal vocabulary |
dodaios/mcp/agents/server.py |
the MCP server: tools, resources, prompts |
dodaios/mcp/agents/context.py |
lazy access to the live runtime (AP-26: nothing on the boot path) |
dodaios/mcp/agents/bridge.py |
the stdio ↔ HTTP bridge for outside clients |
dodaios/mcp/agents/export.py |
per-client config paths, snippets, and the merge-safe write |
dodaios/mcp/agents/tokens.py |
per-client credentials: issue, scope, verify, revoke |
dodaios/mcp/agents/portable.py |
the export/import bundle and its allowlist |
dodaios/ui/web/mcp_server_routes.py |
the mount and the surface dispatch |
dodaios/ui/web/agent_mcp_routes.py |
/api/agent-mcp — status, clients, snippet, connect |
Tests: tests/contract/ holds the contract (_surface), the coverage floor
(_every_tool), the drift gate (_harmony) and portability (_portable);
tests/unit/mcp/ holds the chat path (_chat), the mount and pairing flow
(_routes), credentials (_tokens), the CSRF-guard regression
(_origin_guard) and client configs (_export).