agentation

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.

1. 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.

1. 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.

1. 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.

1. 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.