marklayer-mcp
MCP (Model Context Protocol) server that bridges MarkLayer annotations to AI coding agents.
When users annotate any webpage with MarkLayer, your agent receives the comments as a structured work queue: it can acknowledge, resolve, dismiss, and reply to each one β and the human sees the status updates live. It also works the other way: point an agent at a room and ask it to review the page, and it can leave its own comments and copy-edit suggestions for the human to triage.
Install
You may not need to. Every MarkLayer share link is already a remote MCP server at the same address plus /mcp, so a client that supports remote (Streamable HTTP) servers connects with nothing installed:
claude mcp add --transport http marklayer https://marklayer.app/s/abc123/mcp
Append ?agent=cursor, or any name, so the people in the room see who is working; it defaults to agent. That endpoint is bound to its room, so it has every tool below except marklayer_connect_room.
This package is the stdio version of the same tools, with no Claude-specific wiring. Use it when a client cannot reach remote servers, or when you want one install that covers every room (Claude Code, Cursor, Windsurf, VS Code, Codex CLI, etc.):
claude mcp add marklayer -- npx -y marklayer-mcp
claude mcp add marklayer -- npx -y marklayer-mcp --room https://marklayer.app/s/abc123
For any other MCP client, add a stdio server entry pointing at the same command (adjust the config file/key to your client β Cursor's ~/.cursor/mcp.json, Windsurf's mcp_config.json, VS Code's .vscode/mcp.json, etc.):
{
"mcpServers": {
"marklayer": {
"command": "npx",
"args": ["-y", "marklayer-mcp"],
"env": { "MARKLAYER_AGENT": "cursor" }
}
}
}
Set MARKLAYER_AGENT (or --agent) to identify which agent this is β it's what humans see as the comment author and the "assigned to" badge, so a non-Claude client should not leave it at the default.
Usage
In your agent prompt:
Watch my MarkLayer annotations. For each one, acknowledge it, make the fix, then resolve it with a summary.
The agent will call marklayer_watch_annotations in a loop and process incoming feedback as it arrives.
| Tool | Description |
|---|
marklayer_connect_room | Connect to a room by share URL or bare id. |
marklayer_room_info | Page URL, viewport width, timestamps. |
marklayer_read_page | The page's headings, text, links and controls, with selectors. Lets the agent review a page nobody has annotated yet. |
marklayer_list_annotations | List annotations, optionally filtered by status. |
marklayer_get_annotation | Full detail + reply thread for one annotation. |
marklayer_watch_annotations | Block until new annotations arrive, return a batch. |
marklayer_acknowledge | Mark in-progress and tag with this agent. |
marklayer_resolve | Mark resolved, optionally posting a reply with the summary. |
marklayer_dismiss | Mark dismissed with a reason the human will see. |
marklayer_reply | Post a reply without changing status (e.g. clarifying questions). |
marklayer_create_annotation | Leave a new comment yourself β proactive feedback rather than a response. |
marklayer_suggest_edit | Propose an exact copy/grammar fix for a piece of text, as a diff the human can accept. |
marklayer_share_preview | Open a new review room on a URL you built and connect to it. Same repo + branch as the room you are in (or previous) makes it the next version. |
marklayer_set_next_steps | Publish an ordered checklist, each step linked to annotation ids. Replaces the previous list. |
marklayer_complete_next_step | Tick a step off; reviewers see it live. |
marklayer_ask | Put a 2-6 option poll to the room. One vote per reviewer, revotable. |
marklayer_get_feedback | One read: annotation counts by status, open annotations, checklist progress, poll tallies. |
Options
--room <url-or-id> Connect at startup; otherwise call marklayer_connect_room.
--api-base <url> Override worker URL (default https://marklayer.app).
--agent <name> Identifier shown to humans (default "claude-code").
Equivalent env vars: MARKLAYER_ROOM, MARKLAYER_API_BASE, MARKLAYER_AGENT. For a password-protected room set MARKLAYER_PASSWORD (environment only, never a flag).
Troubleshooting
"Connection closed" on first start. npx -y downloads the package on the
first run, and a cold download can outlast the MCP client's startup timeout.
Prime the cache once (npx -y marklayer-mcp --help) and reconnect, or install
it up front with npm i -g marklayer-mcp and point the client at the binary.
Tools return "room is not connected". The WebSocket dropped β rooms are held
open by a Durable Object and a long-idle agent can be disconnected. Call
marklayer_connect_room with the same URL to reattach.
Creating rooms programmatically
This server consumes an existing share link. To mint one (or many) from code β e.g. seed a room per page in a batch of URLs before pointing the agent at it β POST directly to the public HTTP API:
curl -X POST https://marklayer.app/api/$ID \
-H 'Content-Type: application/json' \
-d '{"ops":[],"url":"https://example.com/page-1","width":1440,"expires_in":2592000}'
For a review room on a preview build, POST /api/$ID/preview takes { url, title, repo?, branch?, sha?, note?, questions?, previous? } and never overwrites an existing id. Versions chain only through previous, a room you already hold: two rooms are never linked by repo and branch alone, because the version switcher shows each room's neighbours. marklayer_share_preview calls this route over stdio; over HTTP (/s/:id/mcp) it creates the room in the Worker, chains from the room in the URL, and returns an mcpUrl to reconnect to, since that endpoint stays bound to its own room.
$ID is caller-supplied (use nanoid / crypto.randomUUID() β it's the access token). No auth, no SDK. Full details: https://marklayer.app/llms-full.txt