rustpad-mcp

A Model Context Protocol (MCP) server for Rustpad, the efficient, minimal, self-hosted collaborative text editor.

Lets MCP clients like Claude Code, Claude Desktop or Codex read and write the pads of a Rustpad instance: fetch a document, create one, replace it wholesale or edit it in place.

Eight tools is the ceiling, not the floor: RUSTPAD_ALLOW_TOOLS=essential registers a curated five instead, and a model picks the right tool far more reliably from five than from eight — see choosing which tools load.

Reads go through Rustpad's HTTP API; writes speak the operational-transformation WebSocket protocol, so targeted edits (append_to_document, replace_in_document) merge cleanly with what human collaborators type at the same time instead of overwriting it. While the server edits a pad, it is visible to everyone in the pad as a collaborator named rustpad-mcp.

The two edits that cannot be undone ask a person. Where the client supports MCP elicitation, replacing a non-empty pad and search-replacing across more than one match raise a real dialog that the model cannot answer on its behalf — and the replace_in_document one says how many places are about to change. Where it does not, they fall back to a two-call token, and say so rather than implying somebody approved. ELICITATION=false takes that fallback deliberately; it never removes the guard. See Asking a person.

What makes it different

Real OT edits, not overwrites. append_to_document and replace_in_document retain everything they do not touch, and the Rustpad server transforms concurrent edits — a human typing in the same pad at the same moment loses nothing. The model shows up in the pad as a named collaborator.

Built for an unauthenticated world. Rustpad has no accounts, so every pad is untrusted by definition. Everything that comes out of one — reads, metadata, even upstream error bodies — is explicitly marked as data, never instructions, before a model sees it.

Requirements

• A reachable Rustpad instance (self-hosted; the server is stateless and needs no credentials — Rustpad has no authentication)
• Node.js >= 22, or Docker

Configuration

The same URL serves the HTTP API, the WebSocket endpoint and the share links returned by the tools (<RUSTPAD_URL>/#<pad-id>). The RUSTPAD_* booleans must be exactly true. The server starts and lists its tools without configuration; every call then fails with setup instructions.

ELICITATION is the odd one out twice over: it carries no prefix, so it reaches every MCP server in the same environment, and a value that is neither true nor false stops the server rather than falling back — it is the only variable here that defaults to on, and a typo would otherwise leave the dialog running while you believed it was off. A server started with it off prints one line saying so.

Keep in mind what Rustpad is: pads are ephemeral (lost on server restart and after 24 hours of inactivity, unless the instance is run with SQLITE_URI) and anyone who knows a pad id can read and write it. Do not put secrets in pads.

Choosing which tools load

RUSTPAD_ALLOW_TOOLS and RUSTPAD_DENY_TOOLS take comma-separated tool names; a trailing * matches a whole family. essential is a curated preset of five: get_document, get_document_info, create_document, set_document, append_to_document.

RUSTPAD_ALLOW_TOOLS=essential
RUSTPAD_ALLOW_TOOLS=get_document,append_to_document
RUSTPAD_DENY_TOOLS=set_document

One boundary is softer than the list suggests: Rustpad has no create operation, a pad exists under any id the moment it is written to, so denying create_document does not stop new pads — set_document or append_to_document on a fresh id makes one just the same. Deny the write tools you mean, or use RUSTPAD_READ_ONLY.

An entry that matches no tool aborts startup and names it, so a typo cannot silently hide a tool — an absent tool is not something anyone traces back to an environment variable. A filtered tool is never registered, so it is absent from tools/list and unknown to tools/call alike, exactly like a write tool under RUSTPAD_READ_ONLY.

If you run several of these servers at once, mcp-hub is the other answer — its /hub endpoint replaces every server's tools with six meta-tools.

Installation

Claude Code

claude mcp add rustpad --env RUSTPAD_URL=https://rustpad.example.net -- npx rustpad-mcp

Claude Desktop

{
  "mcpServers": {
    "rustpad": {
      "command": "npx",
      "args": ["rustpad-mcp"],
      "env": {
        "RUSTPAD_URL": "https://rustpad.example.net"
      }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.rustpad]
command = "npx"
args = ["-y", "rustpad-mcp"]

[mcp_servers.rustpad.env]
RUSTPAD_URL = "https://rustpad.example.net"

Docker

docker run -i --rm -e RUSTPAD_URL=https://rustpad.example.net ghcr.io/ni-c/rustpad-mcp

Through mcp-hub

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — reaches rustpad-mcp through mcp-hub: one container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login behind a single password and long-lived tokens for the clients that cannot do OAuth. Its /hub endpoint puts every server behind six meta-tools, so one connector reaches all of them without N×tool schemas in the model's context, and it speaks both protocol revisions — a question this server asks travels through it to the person at the far end.

Its /config/mcp.json uses Claude Code's format, so the entry is the one you already have:

{
  "mcpServers": {
    "rustpad": {
      "command": "npx",
      "args": ["-y", "rustpad-mcp"],
      "env": { "RUSTPAD_ALLOW_TOOLS": "essential" },
      "denyTools": ["set_document"]
    }
  }
}

allowTools and denyTools there are the hub's own per-server filter, which is not the same thing as *_ALLOW_TOOLS in env — the difference, and the mistake it invites, are in the client guide.

Tools