---

name: agentation description: Add Agentation visual feedback toolbar to a Next.js project

Agentation Setup

Set up the toolbar and, when requested, connect it to the user's coding agent. A visible toolbar and a healthy MCP server do not prove that browser feedback reaches the agent. Verify that final step before calling setup complete.

Steps

1. Inspect the project

   • Read the project's instructions and detect its package manager.
   • Look for agentation and an existing <Agentation> mount before installing.
   • If already mounted, inspect its endpoint and current MCP setup. Do not exit just because the component exists, and do not add a duplicate mount.
   • Install agentation if missing, using the existing lockfile's package manager.

2. Choose the connection mode from the request

   • For MCP or live agent feedback, use the same HTTP server URL as the agent. The default local server is http://localhost:4747; preserve an existing custom port or proxy URL. Never assume the browser and agent use the same machine when the project is remote.
   • For manual copy/paste only, omit endpoint and explain that feedback remains in this browser. Do not silently enable a server connection.
   • If the intended mode is unclear, ask one brief question while inspecting the existing project. Keep working on independent setup checks.

3. Add or update the component

   For a Next.js App Router project, render in the root layout's body after children. For Pages Router, render after Component in pages/_app. Preserve any existing callbacks and options.

   import { Agentation } from "agentation";
   
   // Use the actual server URL selected above for MCP sync:
   {process.env.NODE_ENV === "development" && (
     <Agentation endpoint="http://localhost:4747" />
   )}
   

   The package provides its own client boundary. Keep the application's root layout server-rendered unless the project has another reason to change it.

4. Configure the agent when MCP was requested

   • Use the project's existing MCP client and configuration conventions.
   • The launch command must include the server subcommand: npx -y agentation-mcp server.
   • For supported agents, npx add-mcp "npx -y agentation-mcp server" is one setup option. For Claude Code, use claude mcp add agentation -- npx -y agentation-mcp server or the init wizard.
   • Apply the same custom port to the server command and component endpoint.
   • Restart or reconnect the agent when its configuration requires it. Do not create a second HTTP server on a port already owned by the working server.

5. Verify the complete connection

   • Run npx agentation-mcp doctor for service diagnostics. For a custom URL, use doctor --http-url <url> when supported by the installed version.
   • Open the app and create one clearly identified test annotation through the toolbar. Read it with agentation_get_all_pending or session-scoped tools.
   • Check the exact test comment and page, not just a nonzero count or health response. Leave unrelated annotations alone.
   • If annotations are empty, check the component endpoint, browser network failures/CORS, and whether the agent and browser point to the same server.
   • If browser or MCP tools are unavailable, say exactly which part remains unverified and give the user this final check. Do not claim live sync works.

Notes

• The development guard prevents the toolbar from appearing in production.
• Agentation requires React 18 or newer.
• Installing the toolbar does not install, configure or connect an MCP server.
• Manual copy mode is supported and does not need a running server.