---
name: agentation
description: Add Agentation visual feedback toolbar to a Next.js project. Handles installation, component setup with MCP endpoint, and server configuration.
---
# Agentation Setup
Set up the Agentation annotation toolbar in this project.
## Steps
1. **Check if already installed**
- Look for `agentation` in package.json dependencies
- If not found, install both packages (use pnpm/yarn/npm based on lockfile):
```bash
pnpm add agentation && pnpm add -D agentation-mcp
```
2. **Check if already configured**
- Search for `<Agentation` or `import { Agentation }` in src/ or app/
- If found, verify it has the `endpoint` prop (see step 4). If missing `endpoint`, fix it.
3. **Detect framework**
- Next.js App Router: has `app/layout.tsx` or `app/layout.js`
- Next.js Pages Router: has `pages/_app.tsx` or `pages/_app.js`
4. **Add the component**
**CRITICAL: Always pass the `endpoint` prop.** Without it, the component cannot connect to the MCP server and all sync silently fails.
For Next.js App Router, add to the root layout:
```tsx
import { Agentation } from "agentation";
// Add inside the body, after children:
{process.env.NODE_ENV === "development" && (
<Agentation endpoint="http://localhost:4747" />
)}
```
For Next.js Pages Router, add to _app:
```tsx
import { Agentation } from "agentation";
// Add after Component:
{process.env.NODE_ENV === "development" && (
<Agentation endpoint="http://localhost:4747" />
)}
```
5. **Verify MCP server configuration**
- Check if `agentation` MCP server is in `.claude.json` or Claude Code settings
- If not configured, add it:
```bash
claude mcp add agentation -- npx agentation-mcp server
```
- Run `npx agentation-mcp doctor` to verify everything is connected
6. **Verify end-to-end**
- Start the dev server
- Open the page in a browser
- Check that `agentation_list_sessions` returns a session for the page
- If no sessions appear, check browser console for fetch errors to `localhost:4747`
## All Component Props
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `endpoint` | string | — | **Required for MCP sync.** MCP server URL (e.g., `http://localhost:4747`) |
| `sessionId` | string | — | Explicit session ID override |
| `onSessionCreated` | callback | — | Fires when session is initialized |
| `webhookUrl` | string | — | Webhook URL for annotation events |
| `copyToClipboard` | boolean | `true` | Whether copy writes to clipboard |
| `className` | string | — | Custom class for toolbar positioning |
| `onAnnotationAdd` | callback | — | Fires when annotation is created |
| `onAnnotationDelete` | callback | — | Fires when annotation is removed |
| `onAnnotationUpdate` | callback | — | Fires when annotation is edited |
| `onAnnotationsClear` | callback | — | Fires when all annotations are cleared |
| `onCopy` | callback | — | Fires when output is copied |
| `onSubmit` | callback | — | Fires when "Send Annotations" is clicked |
## Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| `Cmd/Ctrl+Shift+F` | Toggle feedback mode |
| `L` | Layout mode toggle (v3.0+) |
| `P` | Pause animations |
| `H` | Hide/show markers |
| `C` | Copy feedback |
| `X` | Clear annotations |
| `Esc` | Close/cancel |
## Notes
- `NODE_ENV` check ensures Agentation only loads in development
- Agentation requires React 18+
- MCP server runs on port 4747 by default
- MCP tools: `agentation_list_sessions`, `agentation_get_pending`, `agentation_watch_annotations`, `agentation_resolve`, `agentation_acknowledge`, `agentation_dismiss`, `agentation_reply`, `agentation_get_session`, `agentation_get_all_pending`
- Data persists in SQLite at `~/.agentation/store.db`
- Run `npx agentation-mcp doctor` to verify setup
