MCP Server

Overview

The agentation-mcp package provides an MCP server that allows AI coding agents (like Claude Code) to receive and respond to web page annotations created with the Agentation toolbar. This bypasses copy-paste entirely — just annotate and talk to your agent. It already has full context.

It runs both an HTTP server (for the browser toolbar) and an MCP server (for agents via stdio), sharing the same data store.

toolbar → server → agent

Installation

npm install agentation-mcp
# or
pnpm add agentation-mcp

Quick Start

1. Add to your agent

The fastest way to configure Agentation across any supported agent:

npx add-mcp "npx -y agentation-mcp server"

Uses add-mcp to auto-detect installed agents (Claude Code, Cursor, Codex, Windsurf, and more) and write the correct config.

Or use the interactive wizard for Claude Code specifically:

npx agentation-mcp init

2. Verify your setup

npx agentation-mcp doctor

Checks Node.js version, agent config, and server connectivity.

CLI Commands

npx agentation-mcp init      # Setup wizard
npx agentation-mcp server    # Start server
npx agentation-mcp doctor    # Check setup
npx agentation-mcp help      # Show help

Server Options

--port <port>      # HTTP server port (default: 4747)
--mcp-only         # Skip HTTP server, only run MCP on stdio
--http-url <url>   # HTTP server URL for MCP to fetch from

Claude Code

To connect Claude Code to the Agentation MCP server:

1. Add the MCP server

npx add-mcp "npx -y agentation-mcp server"

Or use claude mcp add agentation -- npx agentation-mcp server or the interactive wizard: npx agentation-mcp init

2. Restart Claude Code

The MCP server starts automatically when Claude Code launches. Once connected, Claude can use all the Agentation tools to read and respond to your annotations.

3. Verify the connection

In Claude Code, you can verify the server is connected by asking Claude to list your annotation sessions. If the server is running, Claude will be able to use the agentation_list_sessions tool.

MCP Tools

Nine tools are exposed to AI agents via the Model Context Protocol:

Tool Details

agentation_list_sessions

List all active annotation sessions. Use this to discover which pages have feedback.

agentation_get_session

Get a session with all its annotations. Input: sessionId

agentation_get_pending

Get all pending (unacknowledged) annotations for a session. Use this to see what feedback needs attention. Input: sessionId

// Response
{
  "count": 1,
  "annotations": [{
    "id": "ann_123",
    "comment": "Button is cut off on mobile",
    "element": "button",
    "elementPath": "body > main > .hero > button.cta",
    "reactComponents": "App > LandingPage > HeroSection > Button",
    "intent": "fix",
    "severity": "blocking"
  }]
}

agentation_get_all_pending

Get all pending annotations across ALL sessions. Use this to see all unaddressed feedback from the human across all pages.

agentation_acknowledge

Mark an annotation as acknowledged. Use this to let the human know you've seen their feedback and will address it. Input: annotationId

agentation_resolve

Mark an annotation as resolved. Use this after you've addressed the feedback. Optionally include a summary of what you did. Input: annotationId, optional summary

agentation_dismiss

Dismiss an annotation. Use this when you've decided not to address the feedback, with a reason why. Input: annotationId, reason

agentation_reply

Add a reply to an annotation's thread. Use this to ask clarifying questions or provide updates to the human. Input: annotationId, message

agentation_watch_annotations

Block until new annotations appear, then collect a batch and return them. Triggers automatically when annotations are created — the user just annotates in the browser and the agent picks them up. After detecting the first new annotation, waits for a batch window to collect more before returning. Use in a loop for hands-free feedback processing. Input: optional sessionId, optional batchWindowSeconds (default: 10, max: 60), optional timeoutSeconds (default: 120, max: 300)

Hands-Free Mode

Use agentation_watch_annotations in a loop for automatic feedback processing — the agent automatically picks up new annotations as they're created:

1. Agent calls agentation_watch_annotations (blocks until annotations appear)
2. Annotations arrive — agent receives batch after collection window
3. Agent processes each annotation:
   • agentation_acknowledge — mark as seen
   • Make code changes
   • agentation_resolve — mark as done (annotation disappears from browser)
4. Agent calls agentation_watch_annotations again (loop)

# Example CLAUDE.md instructions
When I say "watch mode", call agentation_watch_annotations in a loop.
For each annotation: acknowledge it, make the fix, then resolve it with a summary.
Continue watching until I say stop or timeout is reached.

Critique Mode

Hands-free mode waits for you to annotate. Critique mode flips that — the agent opens a headed browser, scrolls through your page top-to-bottom, and adds design annotations through the toolbar on your behalf. You watch the cursor move across the page in real time.

Critique the UI at http://localhost:3000

1. Agent opens a headed browser to your page
2. Scrolls top-to-bottom, picking elements to critique
3. Moves cursor to each element, clicks to open the annotation dialog
4. Types specific, actionable feedback and submits
5. Repeats for 5–8 annotations across hierarchy, spacing, typography, navigation, and CTAs

You review them in the toolbar and decide what to fix.

Requires

npx skills add vercel-labs/agent-browser

Self-Driving Mode

Critique mode leaves annotations for you to review. Self-driving mode goes further — the same agent also fixes each issue after annotating it.

Self-driving mode on http://localhost:3000

1. Agent opens a headed browser to your page
2. Scrolls to an element, adds a critique annotation (visible in the toolbar)
3. Reads the relevant source code and edits it to fix the issue
4. Calls agentation_resolve — annotation disappears from the browser
5. Verifies the fix in the browser (if a dev server is running)
6. Moves to the next element, repeats

One Claude Code session handles everything — browser, code, and annotations.

Requires

Everything from critique mode, plus the self-driving skill:

ln -s "$(pwd)/skills/agentation-self-driving" ~/.claude/skills/agentation-self-driving

TypeScript Types

Key types for building your own integrations:

import type {
  Annotation,
  AnnotationIntent,    // "fix" | "change" | "question" | "approve"
  AnnotationSeverity,  // "blocking" | "important" | "suggestion"
  AnnotationStatus,    // "pending" | "acknowledged" | "resolved" | "dismissed"
  Session,
  SessionStatus,       // "active" | "approved" | "closed"
  SessionWithAnnotations,
  ThreadMessage,
  AFSEvent,
  AFSEventType,
  ActionRequest,
} from 'agentation-mcp';