Overview

@plainwork/mcp is a Model Context Protocol server for Plainwork. It exposes read, query, search, and write operations over your workspace to any MCP-speaking agent — Claude Desktop, Claude Code, Cursor, n8n, or any custom client you build.

The server is a thin authenticated shim over the Plainwork HTTP API. It owns no workspace state. Every tool call turns into one or more requests to https://api.plainwork.xyz/v1 authenticated with an agent API key.

The mental model

• Reads are direct. list_collections, list_views, read_page, query_pages, and search_pages call the API and return results immediately. No approval gate, no proposal queue.
• Writes go through the approval gate. create_page, update_page, delete_page, and move_item submit an agent action to the workspace. Unless the agent is configured with auto-approve, the action is queued for a human to approve, edit, or reject. The tool response says whether the change was applied immediately or is waiting for review.
• Every action is attributed. Pages created or edited by an agent carry the agent's identity in createdByAgentId / lastEditedByAgentId. The workspace audit log records who approved what, when, and with what reason.

What's shipped

Nine tools covering the core Plainwork surface:

Tool	What it does	Approval
list_collections	Discover every collection the agent can see	—
list_views	List saved views on a collection	—
read_page	Fetch a page by ID	—
query_pages	Filter, sort, group, paginate within a collection	—
search_pages	Hybrid full-text + semantic search across the workspace	—
create_page	Propose a new page	required
update_page	Propose an update to a page	required
delete_page	Propose deletion	required
move_item	Propose a move to another collection or folder	required

Two transports ship today:

• stdio (default) — the common path. npx -y @plainwork/mcp pipes JSON-RPC over stdin/stdout. Used by Claude Desktop, Claude Code, and Cursor.
• HTTP + SSE — a remote/multi-process path for orchestrators or shared servers. Self-hosted via Docker or node dist/index.js --http. Details in Transports.

Each tool has its own page with arguments, return shape, and a runnable example. Start with Installation to get a key and wire up your first host.