Selvage for agents
OfficialSummary: Selvage for agents lets an AI agent host or join a live collaborative Selvage room and read, edit, and write the shared files alongside people and other clients.
Host a room (
session_host): share a folder, get apage:link for people and aninvite:link for clients, each carrying the room key.Join a room (
session_join): enter from either invite form, learning the room id, role, participants, and path count.Inspect the session (
session_status): see room, role, mode, granted paths, open documents, participants, and unresolved problems (answers even with no session).Leave the room (
session_leave): free the process to host or join again (a host leaving closes the room for everyone).List shared files (
list_paths): sorted paths, filterable by prefix, capped at 100 by default (max 1000), truncation reported.Read files (
read_file): fetch a granted path's shared text as the room holds it.Edit files (
edit_file): replace an exact string, refusing absent or ambiguous matches unlessreplace_all.Write files (
write_file): replace a path's whole text (host only; cannot create files the folder lacks).See participants (
list_participants): each seat's name, role, cursor status, and resolved line/column position.Wait for changes (
wait_for_change): block until a watched path changes and get bounded diff hunks, with a deadline and change backlog.Opt-in notifications: publish a cursor (
publish_cursor) and push room activity to the client as MCP notifications (notify_changes).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Selvage for agents host my ~/notes folder and give me the invite link"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Selvage for agents
A Model Context Protocol server that lets an agent take part in a Selvage session: host a folder, or join an invite link, and read, edit and write the files the room shares.
It is a client of the session protocol, like the editor clients: it drives the same sync engine and speaks the same wire, so an agent and a person edit the same documents and see each other's changes.
Status: v1 in progress. Hosting, joining by invite, and editing in both directions work today.
Get it working
You need:
Node 22.18 or newer on
PATH. The sync engine runs at every end of a session, so an agent that edits a room runs the same code an editor does.A
selvagedto connect to. Start one and note the address it prints.
It is a stdio server — one JSON-RPC message per line — and its diagnostics go to stderr. There are two ways to start it, and they start the same program. An agent should have it configured in its client, not drive it by hand.
From a checkout. npm ci installs the dependencies and builds the runnable artifact, because
prepare runs npm run build: a bundle of the sources and the vendored engine, written to
dist/. Point a client at it — this is the mcp.json entry (mcpServers is the key every
client reads):
{
"mcpServers": {
"selvage": {
"command": "node",
"args": ["/path/to/mcp/dist/main.js"],
"cwd": "/path/to/mcp",
"env": {
"SELVAGE_SERVER_URL": "ws://127.0.0.1:8080",
"SELVAGE_DISPLAY_NAME": "agent",
"SELVAGE_NOTIFY_CHANGES": "true"
}
}
}
}pi's own command line writes the same entry, which is the one-liner to hand an agent that runs
under pi:
pi mcp add selvage \
--env SELVAGE_SERVER_URL=ws://127.0.0.1:8080 \
--env SELVAGE_DISPLAY_NAME=agent \
--cwd /path/to/mcp \
-- node /path/to/mcp/dist/main.js-l writes .pi/mcp.json in the project rather than the global ~/.pi/agent/mcp.json. Either
way the server is a tool the client starts and the agent just calls.
dist/main.js carries a shebang and the executable bit, so it is also the command bin names:
selvage-mcp and node <path>/dist/main.js are the same process. npm run build alone rebuilds
it. src/main.ts is the same server run straight from the sources — Node 22.18 strips the types
as it loads it — so node <path>/src/main.ts works too, with no build at all.
From git, with no checkout. npx fetches the repository, installs it, which runs the same
build, and starts the command the package declares:
{
"mcpServers": {
"selvage": {
"command": "npx",
"args": ["-y", "github:selvage-protocol/mcp"],
"env": {
"SELVAGE_SERVER_URL": "ws://127.0.0.1:8080",
"SELVAGE_DISPLAY_NAME": "agent"
}
}
}
}There is no cwd to set: the server reads its own package.json from where it was installed, and
everything else it needs arrives through the environment or through a tool call.
The package is not on npm, and npx selvage-mcp does not exist. It stays private: true:
publishing needs an account and a token for the scope, and that is not a decision this repository
takes on its own. The git form above is the same package a publish would carry.
SELVAGE_SERVER_URL is the Selvage server's address, and it matters because it is the only way
the address arrives without being asked for: a client starts this server as a subprocess and has
nothing to answer a question with, so session_host falls back to this variable when its
server_url argument is left out, and refuses, naming both, when neither is there. A bare
ws://host:port is enough — the engine adds the /session path — and what you hand it is the
address selvaged prints. SELVAGE_DISPLAY_NAME is the name the other seats see; without it
this server seats itself as agent.
SELVAGE_PUBLISH_CURSOR is the fallback for a publish_cursor argument on either session tool,
and it is off unless it is set to one of 1, true, yes or on. With it on, the server
publishes a cursor for the path each read_file, edit_file and write_file touches — a
position in the room's document, renewed on the room's awareness clock and cleared when the
session ends — so a person sharing the file can see which file the agent has open and roughly
where in it. It is off by default because a caret in someone's editor says the agent is there,
and an agent that never asked for that should not have one invented for it. It is a position and
nothing more: it says the last tool call landed there, not that the agent is looking.
A first session:
Start
selvagedand note the address it prints.Ask the agent to call
session_hostwith the folder to share. It answers with two links, each carrying the key fragment:page:is the link a person opens in a browser, andinvite:is the link a client joins with.Give a person the
page:link (:SelvageJoin <link>in the Neovim client, or the VS Code one, or a browser). Give a peer theinvite:link, or paste either intosession_join— both forms name the same room, token and fragment. The fragment is the room's key, so hand out a link only to whoever should join, and hand it over whole.Both read and edit the same files. A guest's edit arrives in the room and on the host's disk; a host's write arrives in every guest's
read_file.To work live rather than poll, have the agent call
wait_for_change: it blocks until the other seat edits something and answers with the changed region, not the file. See "An agent as a live collaborator" below.
Related MCP server: Human-Agent Chatroom MCP
Tools
| Share a folder and host the room. The folder is walked once, here. Answers with the room id, the path count, and two links that carry the same key fragment: a |
| Join a room from either link |
| Where this server stands: room, role, mode, granted paths, open documents, participants, and any problem the session could not fix. Answers with no session too. |
| Leave the room and free the process to host or join again. A host leaving closes the room for everyone. |
| The room's shared paths, sorted, filtered by |
| The room's text for one shared path. |
| Replace |
| Replace a shared file's whole text. |
| One line per seat: name, role, whether it is this connection, the cursor a seat publishes — which this server does only when asked to — and where that peer is: the document its cursor names and the line and column the engine resolved. A peer that publishes nothing says so. |
| Block until the room changes a watched path, then answer with a bounded partial report — the changed region as a small diff hunk, not whole files. Returns at the first change or at its deadline, and reports what changed since the previous wait. |
An agent as a live collaborator
An agent that works with a person has a different loop from one that answers a question: it has
to be told when the room moves, and it must not be handed the whole document every time. That
loop is session_host or session_join, then wait_for_change, then edit_file on what the
wait reported, then wait_for_change again.
wait_for_change blocks until a watched path actually changes, or until its deadline. It is
always bounded: it never polls and never spins, a deadline that passes says no change within N ms rather than looking like a change, and timeout_ms is capped at five minutes. Watching is
the whole grant and the open documents unless paths names a subset.
What it returns is a partial update, never a file. For each path that changed it gives the
changed region as a small diff hunk — - lines for the old text, + for the new, a few lines of
context, line numbers — and the path's new length in characters. A path that appeared or
disappeared is said in words instead of a hunk. The report is capped in size and says how many
changes it left out; those stay pending and the next wait carries them. It reports what changed
since the previous wait, not since the call, so a change that lands while the agent is thinking
between two waits is reported by the next one rather than swallowed.
edit_file is the writing half: the agent applies the smallest change to the region the wait
showed it, and the room and the other seats see it. The agent's own edit is not reported back to
it; only what the room did after is.
Being told without asking
With notify_changes: true on session_host or session_join — or SELVAGE_NOTIFY_CHANGES set
in the server's environment, the way SELVAGE_SERVER_URL works — the server also tells its client
about room activity as it happens, as MCP notifications/message messages: document changes with
the same bounded hunk, and peers joining and leaving. It is off by default. The messages are rate
limited (at most one per path per half second, and at most twenty in a second across the room),
never carry the invite, and are a second channel rather than a replacement for wait_for_change:
a notification is best-effort, and the wait still owes the change it announced.
A client that wants none of them can set a higher level with logging/setLevel; the messages are
all info, so a warning floor silences them. That method exists only because the logging
capability is declared, and the capability is declared only when this server has a channel to
send through.
Where the other people are
list_participants reads the awareness peers publish — which is anchored to relative positions —
and reports each peer's document and selection as a line and column, so an agent can see where a
person is typing and answer them there:
grace (guest, publishes a cursor) in src/main.rs selecting line 12, column 3 to line 12, column 9
ada (host, this connection, no cursor seen)A peer that publishes nothing is reported as such, and one whose anchors this replica cannot place is reported with its document and no position, rather than at a position this server invented.
What it cannot do
A host cannot create a file its folder does not already hold. The write side of the path clamp is a read: a write happens only for a path the folder already resolves to a plain file of it, so a path the room has and the folder does not is a recorded refusal, not a new file.
Queued host write-back is not generation-bound.
applyFromRoomreads the current engine and root inside a serialized callback; ending a session clears the write queue map without canceling callbacks already queued. A callback could therefore observe a subsequent session's engine and folder. This is an unreproduced lifecycle limitation, not a demonstrated failure or a claimed fix. The absent-document guard does not establish session-generation isolation.Nothing republishes the listing after the initial walk. The paths a host's walk finds are the room's listing for the life of the session; a file added to the folder later is not listed until a new session, and no folder watcher runs on this side.
A guest writes nothing to disk. The room's text lives in the agent's replica; a guest's edits go to the room and nowhere else. Hosting is the only direction that touches a disk.
A published cursor is a position, not attention. Off by default, and when on it sits where the last
read_file,edit_fileorwrite_filetouched the path — the end of the range an edit changed, the start of the file for a read — and stays there between calls. It is renewed on the room's awareness clock and cleared when the session ends, and it says nothing about what the agent is reading.A change names a path, never its author. The engine reports that a document changed but not which peer changed it, so a wait or a notification says a path moved and never names the peer who moved it.
The invite fragment is a credential. Both links
session_hostanswers with carry the same room key in their fragment, so either one is as sensitive as the room itself: anything that holds a link can join and read what the host shares. A failed join reports the URL as[invite]rather than echoing the key.
Which link goes to whom, in one place: the page: link is what a person opens — a browser
fetches the client at the server's page root — and the invite: link is what a client dials,
and what session_join takes. A person given the invite: form, or a client given the page:
form, may still get in — the two are one invitation — but the page link is the one that opens as
a page.
Tests
After npm ci, npm run typecheck and npm test run the server-free checks in CI. The suite
includes interop against a real third-party client, the official @modelcontextprotocol/sdk,
driving the shipped process.
test/packed.test.ts is the packaging proof rather than the exercise: it runs npm pack here,
installs the tarball into a scratch project outside this checkout, and drives the installed command
— not the sources — through initialize and tools/list. It fails, rather than skipping, when the
artifact is not in the tarball.
npm run test:e2e is the proof rather than the exercise: two MCP servers over their real stdio,
editing one room on a real selvaged, converging in both directions. It fails rather than
skipping when there is no server binary, naming the command that builds one, and finds the binary
through SELVAGE_SELVAGED or as a sibling reference_server's build. The runner has no such
checkout, so CI and scripts/ci-local.sh e2e both take the published binary from its image
instead — scripts/fetch-selvaged.sh, a second of network — and name it in SELVAGE_SELVAGED.
nix develop . --max-jobs 2 -c ./scripts/ci-local.sh all runs this checkout's local gate: lint,
checks, released-server e2e, links.
Current-source server compatibility
The separate public current-server.yml workflow runs weekly and on manual dispatch. It
checks out public reference_server main, logs its resolved SHA and the MCP candidate SHA,
builds a fresh selvaged with Rust 1.99.1 and cargo build --locked, then runs the existing
npm run test:e2e suite with Node 26.13.0. It has a 40-minute job timeout, shorter build/test
step timeouts, and retains build/test logs for seven days on failure. It does not replace the
digest-checked released-server E2E in ci.yml; a current-source build or test failure is red,
not treated as evidence of compatibility.
To run against an explicit local source build instead:
cargo build --locked --manifest-path /path/to/reference_server/Cargo.toml -p selvaged
npm ci
SELVAGE_SELVAGED=/path/to/reference_server/target/debug/selvaged npm run test:e2ePublic copy contracts
contracts.yml runs the public specification's scripts/check-workspace.py against this
candidate's committed HEAD and current public VS Code main. It compares engine
and bridge copies and CRDT dependency versions. It logs every resolved input SHA,
uses read-only permissions, and does not persist checkout credentials. The executable
checker is pinned to a reviewed public specification commit; canonical VS Code source
resolves once from main so upstream changes remain visible. Sync from the exact canonical
commit reported by the job; do not freeze that ref or hand-edit vendored sources to make
the check pass.
Locally, arrange Git repositories named mcp, vscode_client, and specification under an
explicit workspace (a symlink to this worktree is fine), then supply the revisions:
bash scripts/ci-local.sh contracts /path/to/workspace SPECIFICATION_SHA \
--revision mcp=HEAD --revision vscode_client=VSCODE_SHAThe wrapper extracts the checker from the supplied specification commit with git show and
passes --revision specification=RESOLVED_SHA. It does not execute an uncommitted checker.
The equivalent public command, using the checker checked out at SPECIFICATION_SHA, is:
python3 /path/to/specification/scripts/check-workspace.py \
--workspace /path/to/workspace --consumer mcp \
--revision mcp=HEAD --revision vscode_client=VSCODE_SHA \
--revision specification=SPECIFICATION_SHANo Neovim checkout or private coordination files are needed. Missing repositories or refs fail
rather than falling back to working-tree files. HEAD compares committed content, so commit
candidate changes before relying on the comparison. Contracts are separate from all, since
the workspace and every compared revision must be explicit.
Licence
MIT OR Apache-2.0: LICENSE-MIT and LICENSE-APACHE.
Available Tools
10 toolsedit_fileA
Replace "old_string" with "new_string" in one granted path's shared text. Refuses, changing nothing, when "old_string" does not appear, when it appears more than once unless "replace_all" is true, and when "new_string" writes two lines the document already holds again: an ambiguous edit is never guessed at, and a piece of the document written a second time through a line-level tool is what "write_file" is for. Only the changed range is published to the room, and a viewer's edit is refused. A host's own folder follows the room, but this cannot create a file the folder does not already hold.
Inputs: path (required), new_string (required), old_string (required), replace_all.
list_participantsA
List the seats in the room: each display name, its role, whether it is this connection, whether a cursor is published, and where the peer is — the document its cursor names and the line and column the engine resolved from the awareness it publishes, so an agent can see where a person is typing and answer them there. This server publishes a cursor only when a session was opened with "publish_cursor", so its own seat has one only then; a peer that publishes nothing says "no cursor seen" rather than being shown at an invented position. The roster is as current as the last event from the room, so a seat that has just arrived or left may still be reported as it was.
Inputs: no named parameters.
list_pathsA
List the paths the room's grant names, sorted, optionally filtered by a prefix and capped at 100 unless a higher limit is asked for (at most 1000). The listing is what the host walked when the room opened and is not live: a file the folder gained since is not in it, and one the folder lost still is, until a new session. A truncated answer says so and names the limit. Takes the optional prefix and limit.
Inputs: limit, prefix.
read_fileA
Read one granted path's shared text as the room holds it. Only a path the room's grant names can be read; a path that is not text, or is over the size a session carries, is refused rather than answered. The text is the room's — the host folder's copy where the host is keeping that true — and this tool never reads the disk itself. A guest waits for the room to send the document and is refused if it does not arrive in time.
Inputs: path (required).
session_hostA
Share a folder with a room and host it, and answer with the two links that open it. The folder is walked once, here: the paths the walk finds are the room's listing, and only a file the folder holds at that moment can be listed, so a file that appears in the folder later is not listed until a new session, because nothing republishes the listing — and a host cannot create a file its folder does not already hold. A person opens the page link in a browser; a client — another session_join included — joins with the client invite, and either form works. Both links carry the same room, token and key fragment, and the fragment is the credential: hand a link, whole, only to whoever should join. A host leaving closes the room for everyone. Takes the folder, the server address, a display name, and the two opt-ins: whether to publish a cursor, and whether to tell the client about room activity as it happens.
Inputs: folder (required), server_url, display_name, notify_changes, +1 more.
session_joinA
Join a room from an invite URL in either form session_host answered with — the page link a person would open, or the client invite — which has to carry the key in its fragment. Answers with the room id, this seat's role, the participants and how many paths the host granted. The listing is what the host shared when the room opened, so a path shared afterwards is not in it until a new session. A guest edits the room's shared text and writes nothing to its own disk. Takes the invite, a display name, and the two opt-ins: whether to publish a cursor, and whether to tell the client about room activity as it happens.
Inputs: invite (required), display_name, notify_changes, publish_cursor.
session_leaveA
Leave the room this server is in, closing the connection and freeing the session so it can host or join again. A host leaving closes the room for everyone: the other seats are disconnected and the room ends, and the only way back is to host again or to join another invite. With no session it is a caller error, because there is nothing to leave.
Inputs: no named parameters.
session_statusA
Report the live session: role, room, mode, participants, whether the connection is carrying traffic, the granted paths this replica holds, the room's open documents, and any problem the session could not fix (a room change a host could not put on disk, a granted path the folder would not read). With no session open it still answers, saying there is none, rather than failing: asking where this server stands is not a mistake.
Inputs: no named parameters.
wait_for_changeA
Block until the room changes a watched path, then answer with a bounded partial report rather than whole files: for each path that changed, the changed region as a small diff hunk with line numbers and a few lines of context, and the path's new length; a path that appeared or disappeared is said in words instead of a hunk. Watching is the whole grant and the open documents unless "paths" names a subset. It returns at the first change or at "timeout_ms" (default 30000, at most 300000), never spinning, and a deadline that passes says so plainly rather than looking like a change. It reports what changed since the previous wait, not since the call: a change that lands while the agent is thinking is reported by the next wait, so nothing is lost between two waits. The report is capped in size and says how many changes it left out.
Inputs: paths, timeout_ms.
write_fileA
Replace a granted path's whole shared text with "content". This is how a host changes a file its folder already holds: the folder follows the room, but a file the folder does not hold cannot be created, and a path the room did not grant cannot be written at all. A viewer is refused, and text over the size a session carries is refused. Prefer edit_file where a small change is meant.
Inputs: path (required), content (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct action or resource: session lifecycle tools are separate from file operations, listing, participant inspection, and change waiting. The only mild overlap is session_status vs list_participants, but the descriptions clearly distinguish an overall session report from a detailed seat roster.
Most names follow predictable snake_case patterns: session_* for lifecycle, list_* for collections, and verb_noun for file operations. wait_for_change is a minor deviation, but the set remains highly readable and consistent overall.
Ten tools are well-scoped for a collaborative room/session server, covering session lifecycle, shared file reading/writing/editing, path listing, participant listing, and change watching without obvious redundancy.
The surface covers core room and file collaboration workflows, including read, write, edit, list, join, host, leave, and wait for changes. Minor gaps exist around creating, deleting, or renaming shared files and modifying grants after hosting, but these appear partly by design since the host folder supplies the file set.
Maintenance
Related MCP Connectors
A real-time, multiplayer filesystem for agents and humans: shared files, live edits, history.
Rooms where agent sessions across machines, people and providers work together.
Create and improve live, shared interactive documents with your agent.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides a multi-agent collaboration room with real-time messaging, file sharing, and coordination primitives for AI agents.2MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to join ephemeral collaborative chatrooms, read room context, poll messages, publish findings, and update their status alongside human participants.-
- AlicenseAqualityBmaintenanceEnables an AI agent to join a live Excalidraw collaboration room as a headless participant, read the drawing in real time, and add or modify elements on the shared canvas.1868 npm4MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to create, read, update, list, restore, and renew client-side-encrypted shared workspaces that are reachable by a single link, so several agents and people can collaborate on the same living document with version-checked writes that refuse to clobber each other.19 npmMIT