Enables AI agents to receive, process, and respond to visual webpage annotations as a structured work queue.
Also known as thevrus/MarkLayer, marklayer-ed5c8b, marklayer-mcp
- Stars
- 54
- Tools
- 17
- Downloads, 30 days
- —
- Latest version
- 0.6.1
- Last commit
- Nov 10, 2026
- License
- Apache-2.0
What is MarkLayer MCP?
MarkLayer enables AI agents to receive, process, and respond to visual webpage annotations as a structured work queue. It exposes 17 tools, such as marklayer_read_page, marklayer_connect_room, marklayer_room_info.
Summary generated from the project's README
About MarkLayer MCP server
MarkLayer connects AI coding agents to visual webpage annotations through a structured work queue. This server allows developers to bridge the gap between human feedback on a live site and an agent's ability to execute fixes. By using this protocol, an agent can monitor a room for new comments, acknowledge them, and resolve tasks while humans observe status updates in real time.
Users can connect via remote Streamable HTTP by appending /mcp to a MarkLayer share link, or use the stdio version for local clients like Claude Code, Cursor, Windsurf, or VS Code. The server provides tools to read page content, manage annotation statuses, and even propose copy-editing suggestions. It supports identifying specific agents via the MARKLAYER_AGENT environment variable so human collaborators can see who is performing the work.
Beyond simple responses, the server enables proactive agent behavior. An agent can use marklayer_read_page to review unannotated sites, mark tasks as in-progress with marklayer_acknowledge, or create polls and checklists to coordinate with human reviewers.
What you can do with it
- 1Process visual feedback loopsAn agent can monitor a webpage for new annotations and automatically resolve them after making the necessary code fixes.
- 2Perform proactive page reviewsYou can direct an agent to examine a webpage and leave its own suggestions for text or grammar improvements.
Written from the project's README. Every use case is checked against a quote from it.
How to install MarkLayer MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall MarkLayer MCP in Claude Code
$ claude mcp add marklayer-ed5c8b -- npx -y marklayer-mcpInstall MarkLayer MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"marklayer-ed5c8b": {
"command": "npx",
"args": [
"-y",
"marklayer-mcp"
]
}
}
}Install MarkLayer MCP in VS Code
.vscode/mcp.json
{
"servers": {
"marklayer-ed5c8b": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"marklayer-mcp"
]
}
}
}Install MarkLayer MCP in VS Code CLI
$ code --add-mcp '{"name":"marklayer-ed5c8b","type":"stdio","command":"npx","args":["-y","marklayer-mcp"]}'Install MarkLayer MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"marklayer-ed5c8b": {
"command": "npx",
"args": [
"-y",
"marklayer-mcp"
]
}
}
}Install MarkLayer MCP in Codex
$ codex mcp add marklayer-ed5c8b -- npx -y marklayer-mcpInstall MarkLayer MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.marklayer-ed5c8b] command = "npx" args = ["-y", "marklayer-mcp"]
Install MarkLayer MCP in Gemini CLI
$ gemini mcp add -s user marklayer-ed5c8b npx -- -y marklayer-mcpInstall MarkLayer MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"marklayer-ed5c8b": {
"command": "npx",
"args": [
"-y",
"marklayer-mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for marklayer-mcp 0.6.1 in an isolated container with no network and no keys. It answered and listed 17 tools.
MarkLayer MCP tools 17
Read from the server with tools/listmarklayer_read_pageRead the page this room annotates — its headings, paragraphs, links, buttons and labels, each with the CSS selector and tag that locate it. Call this FIRST when asked to review, audit or improve a page and no annotations exist yet: without it you can only answer feedback someone else left, never find anything yourself. Every entry is already in the shape marklayer_suggest_edit and marklayer_create_annotation take, so pass `selector`, `tag` and `markdown` straight through to anchor a mark to the element you are talking about. If the answer says the page renders client-side, the copy is not in the HTML and you should say so rather than review an empty shell.
marklayer_connect_roomConnect to a MarkLayer room (annotation session) by URL or bare room id. Disconnects any prior room.
marklayer_room_infoGet metadata about the connected room: page URL, viewport width, timestamps.
marklayer_list_annotationsList every annotation in the connected room across all tools (comment, area, selection, inspect). Each entry carries a `kind` discriminator and, where the user marked an element, a `target` block with selector + markdown so you can address the change without reopening the page. Filter by status: open, in_progress, resolved, approved, dismissed, or all (default). `approved` means the person who asked for the change confirmed the fix, so those need nothing from you.
marklayer_get_annotationGet full detail for a single annotation of any kind (comment, area, selection, inspect), including its element `target` context and — for comments — the reply thread.
marklayer_watch_annotationsBlock until there is work, then return a batch of whatever arrives within a short window. CALL THIS AGAIN IMMEDIATELY EVERY TIME IT RETURNS, including when it returns nothing — an empty result means the window expired, not that the reviewer is done. Nothing pushes work to you: between your calls, a comment someone leaves reaches no one. Keep looping until the person tells you to stop or ends the session. Each event has a `kind`: "new" is an annotation someone just left; "handoff" is one given to you — assigned to you, a reply that @mentions you, or a reply on a thread you already own. A handoff also carries `request`, the reply that asked: read it, it is the instruction, and act on it rather than only acknowledging. Every event carries the full annotation with its `target` element context.
marklayer_acknowledgeMark an annotation as in_progress and tag it with this agent so the human sees you are working on it.
marklayer_resolveMark an annotation as resolved. Pass a summary describing what was changed — it will be posted as a reply to the thread.
marklayer_dismissMark an annotation as dismissed when it cannot be acted on. The reason will be visible to the human.
marklayer_replyPost a reply to an annotation thread without changing its status. Use to ask clarifying questions.
marklayer_create_annotationLeave a new comment annotation yourself — proactive feedback (a bug, a UX issue, an accessibility gap, an idea) rather than only responding to a human’s. For an exact text replacement (a copy or grammar fix), use marklayer_suggest_edit instead — it renders as a diff the human can accept, rather than prose describing one. Use this after you have looked at the page with your own tools (a screenshot, a DOM read) and decided something is worth flagging; call it once per finding so each becomes its own pin the human can triage. x/y are document pixels (not viewport pixels — scroll offset already added in). Pass selector + tag + markdown (straight from marklayer_read_page) to pin to that element: the pin sits on the element and follows it when the page reflows, and x/y become optional (a fallback only). Omit all three for a fixed-point pin at x/y.
marklayer_suggest_editPropose an exact replacement for a piece of text on the page — a copy or grammar fix — as a diff the human can accept, rather than a comment describing the change in prose. `rects` are the on-page bounding boxes of `text`, in document pixels: one per line it spans, so a wrapped sentence highlights as several boxes rather than one box swallowing the whole paragraph between its first and last line. Pass selector + tag + markdown together to anchor it to the containing element so it re-resolves if the page reflows.
Show all 17 toolsShow fewer tools
marklayer_share_previewOpen a new review room on a page you built — a preview deploy, a staging URL — and get back the link to hand to a human. Call this when you have something for someone to look at, rather than asking them to open a URL and describe what they see. The page is framed live and reviewers annotate it directly; their feedback then reaches you through the other tools. Pass `repo` + `branch` (and `sha`) when the page comes from a branch: a later preview of the same repo and branch becomes the next version of this one, and reviewers can step between versions. Over stdio this also connects you to the new room. Over HTTP the endpoint stays bound to the room in its URL, so reconnect to the returned `mcpUrl` to work the new room.
marklayer_set_next_stepsPublish your plan as a short ordered checklist the reviewers see live in the room, distilled from their feedback — one step per change you will make, each naming the annotation ids it answers. Replaces any list you set before. Tick steps off with marklayer_complete_next_step as you finish them, so the humans can watch the work land instead of asking where it is.
marklayer_complete_next_stepTick a step of the checklist off (or back on with done: false). Reviewers see it change live.
marklayer_askPut a multiple-choice question to the room — "Which hero variant?", "Ship with the banner?" — when you need a decision rather than open-ended feedback. Each reviewer gets one vote and may change it. Read the tally with marklayer_get_feedback.
marklayer_get_feedbackEverything the room has told you, in one read: annotation counts by status with the open ones in full, the next-steps checklist and how far along it is, and every poll with its current tally. Use it to decide what to do next; use marklayer_watch_annotations to wait for more.
Configuration
MARKLAYER_AGENTName shown to the humans in the room for this agent. Defaults to claude-code.
MARKLAYER_API_BASEOverride the MarkLayer worker base URL. Defaults to https://marklayer.app; useful against a local dev worker.
MARKLAYER_ROOMSame as --room: the share URL or room id to join at startup.
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablethevrus/marklayer is public and reachablegithub.com/thevrus/marklayer ↗Pass
- Package names this repository as its sourcemarklayer-mcp names thevrus/marklayer as sourcenpmjs.com/package/marklayer-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for marklayer-mcpnpmjs.com/package/marklayer-mcp/v/0.6.1#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/thevrus/marklayer ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from marklayer-mcpPass
- No critical advisory in the package or its dependencies101 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model17 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmarklayer-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 Code:
claude mcp add marklayer -- npx -y marklayer-mcp
# Or pre-connect to a specific room:
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.
Tools
| 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}'
# Share link: https://marklayer.app/s/$ID
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
MarkLayer MCP questions
How do I add MarkLayer MCP to Claude Code?
Run claude mcp add marklayer-ed5c8b -- npx -y marklayer-mcp in your terminal. Add --scope user to make it available in every project.
How do I add MarkLayer MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does MarkLayer MCP provide?
It exposes 17 tools, including marklayer_read_page, marklayer_connect_room, marklayer_room_info, marklayer_list_annotations, marklayer_get_annotation.
How do I connect the server to a specific room?
You can connect at startup using the --room flag with a URL or ID, or call the marklayer_connect_room tool.
What should I do if I get a 'Connection closed' error on first start?
This is often due to the npx download taking too long. You can prime the cache by running 'npx -y marklayer-mcp --help' or install it globally using 'npm i -g marklayer-mcp'.
How can an agent identify itself to human users in the room?
Set the MARKLAYER_AGENT environment variable or use the --agent flag to provide an identifier that humans will see as the comment author.
Can the agent propose text changes?
Yes, the agent can use the marklayer_suggest_edit tool to propose exact copy or grammar fixes as a diff for humans to accept.