MCP Server

Overview

The agentation-mcp package provides an MCP server that allows AI coding agents (including Claude Code, Codex, Gemini CLI, and Grok Build) to receive and respond to web page annotations created with the Agentation toolbar. Once connected, your agent can read the feedback and element context directly.

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

Node.js 24 LTS is recommended. Node.js 22 LTS is also supported; Node.js 20 remains compatible. This requirement applies to the MCP server, not the browser toolbar.

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

Quick Start

1. Add to your agent

claude mcp add agentation -- npx -y agentation-mcp server

Restart your agent or reload its MCP servers after configuration. Keep the agent running while you annotate so the browser can reach its server.

2. Verify your setup

npx agentation-mcp doctor

Checks Node.js, the local server connection, and Claude Code configuration if present. For other clients, also check the server status in your agent.

3. Connect the browser toolbar

<Agentation endpoint="http://localhost:4747" />

Registering the MCP server with your agent does not configure the React component. Set the matching endpoint in your app, start the agent so its server runs, then add one note in the browser and ask the agent to list pending feedback.

doctor checks the server connection. A note making the complete browser-to-agent trip confirms that both sides are connected.

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
--host <address>   # Interface to bind (default: loopback only)

Browser origins and delivery

Set AGENTATION_CORS_ORIGINS to a comma-separated list of exact HTTP(S) origins, including ports. The policy also applies to event streams and errors.

AGENTATION_CORS_ORIGINS='http://localhost:3000,https://preview.example.com' npx agentation-mcp server

When unset, dev-server origins are allowed: localhost, *.localhost, loopback and private-network addresses, and .local, .test or .internal hostnames on any port. Set the variable for public origins, or to * to allow every origin. An empty value rejects every browser Origin. Requests without an Origin remain allowed; this setting is not authentication.

Server webhooks retry network failures, timeouts, HTTP 429 and 5xx responses. Each retry keeps the same X-Agentation-Delivery-Id so receivers can deduplicate. Delivery is best effort and in memory; pending deliveries do not survive a restart.

Configure delivery retries or bound in-memory event history.

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. Returns feedback, placement, and rearrange annotations. Use the kind field to distinguish between them. Input: sessionId

// Response — feedback annotation
{
  "count": 2,
  "annotations": [{
    "id": "ann_123",
    "comment": "Button is cut off on mobile",
    "element": "button",
    "elementPath": "body > main > .hero > button.cta",
    "kind": "feedback",
    "intent": "fix",
    "severity": "blocking"
  }, {
    "id": "ann_456",
    "comment": "Place a Hero component here",
    "kind": "placement",
    "placement": {
      "componentType": "Hero",
      "width": 800,
      "height": 400,
      "scrollY": 0
    }
  }]
}

agentation_get_all_pending

Get all pending annotations across ALL sessions. Returns all three annotation kinds: feedback, placement, and rearrange. Use this to see all unaddressed feedback and design requests from the human.

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. Picks up all annotation kinds: feedback, placement, and rearrange. Layout mode placements and rearrange changes trigger the watcher just like regular feedback annotations. 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, and the agent receives the batch after the collection window
3. Agent processes each annotation:
   • agentation_acknowledge: mark as seen
   • Make code changes and verify the result, including a browser check for visual feedback
   • agentation_resolve: mark verified work 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: read its thread, acknowledge actionable work, make the fix,
and verify it before resolving with a summary. Leave questions and unverified
work unresolved.
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';