agentation-mcp

Agentation is an agent-agnostic visual feedback tool. Click elements on your page, add notes, and copy structured output that helps AI coding agents find the exact code you're referring to.

The MCP (Model Context Protocol) server connects Agentation to Claude Code, Codex, Gemini CLI, Grok Build, and other compatible agents, so they can receive and respond to your annotations directly.

Runtime requirement

Node.js 24 LTS is recommended; Node.js 22 LTS is also supported. The minimum is Node.js 20, which remains compatible but is no longer maintained by Node.js. The browser toolbar has no Node.js runtime requirement.

The previous MCP release advertised Node.js 18, but its SQLite dependency already required Node.js 20 or newer. This release corrects that metadata; it does not introduce a new SQLite runtime minimum.

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 detect supported installed clients. The setup guide also includes direct commands for Claude Code, Codex, Gemini CLI, and Grok Build.

Or for Claude Code specifically:

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

2. Start your agent

Restart the agent after registering the server. It launches Agentation as a local stdio MCP process; keep that agent session running while annotating. The server provides both:

• HTTP server (port 4747) - receives annotations from the browser toolbar
• MCP server (stdio) - exposes tools for your connected agent

3. Connect the browser toolbar

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

Use the same server URL as the agent, including a custom port if configured. Without endpoint, the toolbar saves feedback locally for manual copying.

4. Verify browser-to-agent delivery

npx agentation-mcp doctor
# Custom server:
npx agentation-mcp doctor --http-url http://localhost:4747

Doctor checks services, not browser delivery. Add one test annotation in the app, then ask your agent to call agentation_get_all_pending. Confirm its exact comment and page. If it is missing, check the component endpoint and that both clients point to the same server.

CLI Commands

agentation-mcp init                    # Setup wizard (registers via claude mcp add)
agentation-mcp server [options]        # Start the annotation server
agentation-mcp doctor                  # Check your setup
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)

MCP Tools

The MCP server exposes these tools to AI agents:

Tool	Description
agentation_list_sessions	List all active annotation sessions
agentation_get_session	Get a session with all its annotations
agentation_get_pending	Get pending annotations for a session
agentation_get_all_pending	Get pending annotations across all sessions
agentation_acknowledge	Mark an annotation as acknowledged
agentation_resolve	Mark an annotation as resolved
agentation_dismiss	Dismiss an annotation with a reason
agentation_reply	Add a reply to an annotation thread
agentation_watch_annotations	Block until new annotations appear, then return batch

HTTP API

The HTTP server provides a REST API for the browser toolbar:

Sessions

• POST /sessions - Create a new session
• GET /sessions - List all sessions
• GET /sessions/:id - Get session with annotations

Annotations

• POST /sessions/:id/annotations - Add annotation
• GET /annotations/:id - Get annotation
• PATCH /annotations/:id - Update annotation
• DELETE /annotations/:id - Delete annotation
• GET /sessions/:id/pending - Get pending annotations
• GET /pending - Get all pending annotations

Events (SSE)

• GET /sessions/:id/events - Session event stream
• GET /events - Global event stream (optionally filter with ?domain=...)

Health

• GET /health - Health check
• GET /status - Server status

Hands-Free Mode

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

• Agent calls agentation_watch_annotations (blocks until annotations appear)
• Annotations arrive -- agent receives batch after collection window
• Agent processes each annotation:
  • agentation_acknowledge -- mark as seen
  • Make code changes
  • agentation_resolve -- mark as done with summary
• 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.

Webhooks

Configure webhooks to receive notifications when users request agent action:

# Single webhook
export AGENTATION_WEBHOOK_URL=https://your-server.com/webhook

# Multiple webhooks (comma-separated)
export AGENTATION_WEBHOOKS=https://server1.com/hook,https://server2.com/hook

Environment Variables

Variable	Description	Default
AGENTATION_STORE	Storage backend (memory or sqlite)	sqlite
AGENTATION_WEBHOOK_URL	Single webhook URL	-
AGENTATION_WEBHOOKS	Comma-separated webhook URLs	-
AGENTATION_EVENT_RETENTION_DAYS	Days to keep SQLite events	7
AGENTATION_CORS_ORIGINS	Allowed browser origins; see below	dev-server origins
AGENTATION_HOST	Interface to bind; a non-loopback address enables remote clients	loopback only

Programmatic Usage

import { startHttpServer, startMcpServer } from 'agentation-mcp';

// Start HTTP server on port 4747
startHttpServer(4747);

// Start MCP server (connects via stdio)
await startMcpServer('http://localhost:4747');

Storage

By default, data is persisted to SQLite at ~/.agentation/store.db. To use in-memory storage:

AGENTATION_STORE=memory agentation-mcp server

Network access

The server is for the browser on the same machine. By default it only answers clients connecting over loopback that address a local hostname (localhost, 127.0.0.1, [::1] or *.localhost), so other devices on the network and DNS-rebinding pages get HTTP 403. To serve other machines deliberately, bind a specific interface with --host or AGENTATION_HOST:

agentation-mcp server --host 0.0.0.0

The bundled stdio tools follow that address automatically unless --http-url is set.

Pages served from that machine's private address are already allowed by the default origin policy below; use AGENTATION_CORS_ORIGINS for public origins.

Containers, Codespaces and remote dev

When the browser reaches the server through a port forward or a container bridge, the connection is not loopback and the page origin is public. Allow both explicitly:

AGENTATION_CORS_ORIGINS='https://your-forwarded-app-origin' agentation-mcp server --host 0.0.0.0

agentation-mcp doctor reports the address it can reach the server on.

Browser origins

AGENTATION_CORS_ORIGINS controls which browser origins may call the HTTP server. It applies to normal responses, errors, preflight requests, event streams, MCP transport and cloud proxy routes. A disallowed Origin receives HTTP 403 before the request can change data or be forwarded.

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

Use exact HTTP(S) origins, including the port when present. Paths, credentials, query strings, regular expressions and a wildcard mixed with other origins are rejected at startup. A trailing slash is accepted and normalized.

When unset, dev-server origins are allowed: localhost, *.localhost, 127.0.0.1, [::1], private-network addresses (10.*, 192.168.*, 172.16-31.*) and .local, .test or .internal hostnames, over HTTP or HTTPS on any port. Set the variable to add anything else, or to * to allow every origin. An explicitly empty value rejects every browser Origin. Requests without an Origin, such as ordinary CLI clients, remain allowed. CORS is a browser access policy, not authentication.

Webhook delivery

Configure destinations with AGENTATION_WEBHOOK_URL or comma-separated AGENTATION_WEBHOOKS. Repeated destinations are sent only once per action. Action responses do not wait for delivery to complete.

Network failures, request timeouts, HTTP 429 and 5xx responses are retried. Other unsuccessful responses stop immediately. Each retry sends the same JSON body and X-Agentation-Delivery-Id header. Receivers should use that ID to avoid processing a delivery twice: a timeout can occur after the receiver accepted it.

Variable	Default	Meaning
AGENTATION_WEBHOOK_MAX_RETRIES	3	Additional attempts after the first; 0 disables retries, maximum 10.
AGENTATION_WEBHOOK_BASE_DELAY_MS	1000	Initial exponential backoff, with up to 25% positive jitter.
AGENTATION_WEBHOOK_MAX_DELAY_MS	30000	Maximum time between attempts, including jitter.
AGENTATION_WEBHOOK_TIMEOUT_MS	10000	Per-request timeout.

Retry-After is respected for retryable HTTP responses. If it exceeds the maximum delay, delivery stops rather than retrying before the requested time. Timing values must be positive integers no larger than 2,147,483,647 milliseconds; invalid values fall back to their defaults.

Delivery is best effort and held in memory. It is not a durable queue and does not promise exactly-once processing. Closing the server cancels requests and pending retries; restarting does not resume them. Request timers are cleared after every attempt and pending timers do not keep the process alive.

In-memory event history

These limits apply when using the memory store. They bound replay history, not the current sessions or annotations. SQLite storage is unchanged by these settings.

Variable	Default	Meaning
AGENTATION_MAX_EVENTS	10000	Maximum retained events; oldest events are removed first.
AGENTATION_EVENT_TTL_MS	3600000	Event lifetime in milliseconds, default one hour.
AGENTATION_CLEANUP_INTERVAL_MS	300000	Background cleanup interval, default five minutes.

All three values must be positive safe integers. The cleanup interval must also fit the timer limit above. Invalid values fall back to their defaults. Reads remove expired events immediately, without waiting for the next cleanup tick. Pruning does not reset event sequence numbers. Closing the store clears its cleanup timer, which does not keep an otherwise idle process running.

Embedding the HTTP server

startHttpServer(port) returns the Node HTTP server. Existing callers can ignore the return value; embedded callers can use server.close() to stop accepting requests and cancel outstanding webhook deliveries.

License

PolyForm Shield 1.0.0