MCP server for Agentation - visual feedback for AI coding agents
npm install agentation-mcpMCP (Model Context Protocol) server for Agentation - visual feedback for AI coding agents.
This 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.
``bash`
npm install agentation-mcpor
pnpm add agentation-mcp
Run the interactive setup wizard:
`bash`
agentation-mcp init
This will configure Claude Code to use the Agentation MCP server.
`bash`
agentation-mcp server
This starts both:
- HTTP server (port 4747) - receives annotations from the browser toolbar
- MCP server (stdio) - exposes tools for Claude Code
`bash`
agentation-mcp doctor
`bash`
agentation-mcp init # Interactive setup wizard
agentation-mcp server [options] # Start the annotation server
agentation-mcp doctor # Check your setup
agentation-mcp help # Show help
`bash`
--port
--mcp-only # Skip HTTP server, only run MCP on stdio
--http-url
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 |
The HTTP server provides a REST API for the browser toolbar:
- Create a new session
- GET /sessions - List all sessions
- GET /sessions/:id - Get session with annotations$3
- 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$3
- GET /sessions/:id/events - Session event stream
- GET /events - Global event stream (optionally filter with ?domain=...)$3
- GET /health - Health check
- GET /status - Server statusHands-Free Mode
Use
agentation_watch_annotations in a loop for automatic feedback processing -- the agent 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 with summary
4. Agent calls agentation_watch_annotations again (loop)Example CLAUDE.md instructions:
`markdown
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:
`bash
Single webhook
export AGENTATION_WEBHOOK_URL=https://your-server.com/webhookMultiple 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 events | 7 |Programmatic Usage
`typescript
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:`bash
AGENTATION_STORE=memory agentation-mcp server
``PolyForm Shield 1.0.0