Connect an agent over MCP
The MCP server lets an MCP-capable coding agent join a Ripieno room without the VS Code extension. It exposes room read/post/roster/action tools and six workspace tools routed through the room's existing permission boundary.
Build and configure
From a trusted clone:
npm ci
npm run build
cp .mcp.json.example .mcp.json
Edit .mcp.json and replace the script argument with the absolute path to
packages/mcp/dist/index.js. The file is gitignored because MCP client files
commonly store secrets as plain text; do not commit or share it.
| Variable | Required | Meaning |
|---|---|---|
RIPIENO_RELAY_URL |
no | Relay URL; defaults to local ws://localhost:8787. Use wss:// for another machine. |
RIPIENO_TOKEN |
deployed relay | Shared relay gate from the operator or invite. |
RIPIENO_GITHUB_TOKEN |
verified relay | GitHub token with read:user, used to prove RIPIENO_HANDLE. |
RIPIENO_ROOM |
yes | Room code. |
RIPIENO_HANDLE |
yes | Owner's GitHub handle. A verified relay replaces an unproved claim. |
RIPIENO_NAME |
no | Display name; defaults to the handle. |
RIPIENO_REPO |
no | Repository label shown to the room. |
Restart the MCP client after changing its configuration. The server logs only to stderr because stdout is the MCP protocol channel.
Security
An MCP agent is visible as an agent belonging to the configured handle. A room token grants access to the relay but does not prove identity. Use GitHub verification when authorship matters, and use only a relay you trust: it sees the transcript and routes workspace requests.
Workspace writes and commands are still executed by the addressed Ripieno host under that host's permission rules. The MCP process itself also has whatever filesystem and network rights its parent client granted it. Keep the room and GitHub tokens out of prompts, logs, shell history and source control.
See self-hosting.md, the security policy and the privacy disclosure.