MCP Integration

Connect Clickly to Claude Code, Cursor, or any MCP-capable agent so annotations flow directly into your agent's context without copy-paste.

Overview

The Model Context Protocol (MCP) is an open standard for exposing structured data and tools to AI agents. The Clickly MCP server runs locally as a stdio server (for your agent) plus a small HTTP bridge (for the browser toolbar) on localhost:4747 by default.

Instead of copying a markdown block and pasting it into Claude, your agent can call tools like clickly_list_annotations at any point during a task and get the latest annotations as structured JSON — element path, computed styles, source file and line, your feedback, and any suggested CSS.

Run the MCP server

No separate “install” step — run it directly:

npx @useclickly/mcp-server server

Or install the CLI globally if you'll use it often:

npm install -g @useclickly/mcp-server
clickly-mcp server

Configure your agent

Add this to your agent's MCP config — Claude Code: ~/.claude/claude_desktop_config.json, Cursor: .cursor/mcp.json:

{
  "mcpServers": {
    "clickly": {
      "command": "npx",
      "args": ["-y", "@useclickly/mcp-server", "server"]
    }
  }
}

Restart your agent after saving. You should see “clickly” listed among its connected MCP servers.

Connect your React app

Pass the server URL to <Clickly /> — this enables MCP and points it at your server as soon as the component mounts:

// In your ToolbarProvider or wherever you render <Clickly />
import { Clickly } from "useclickly";

export function ToolbarProvider() {
  return (
    <Clickly endpoint="http://localhost:4747" />
  );
}

You can also open the toolbar's ⚙ Settings → Manage MCP & Webhooks panel to change the endpoint or toggle MCP off at runtime — a manual change there sticks until endpoint itself changes (e.g. a full page reload with the same prop re-applies it).

With MCP connected, every annotation you create is immediately available to your agent via the MCP tools listed below.

MCP tools

Tool	Description
`clickly_list_sessions`	List all annotation sessions — one per page/URL where the toolbar was opened.
`clickly_list_annotations`	List every annotation in a session — element path, position, React tree, source file/line, feedback, status.
`clickly_list_layout_changes`	List Layout Mode annotations only (placements/rearranges), with optional `kind` and `status` filters.
`clickly_get_annotation`	Fetch a single annotation by ID, including its full thread.
`clickly_acknowledge`	Mark an annotation as seen / in progress.
`clickly_resolve`	Mark an annotation as fixed, optionally with a note describing the change.
`clickly_dismiss`	Mark an annotation as not actionable or a duplicate.
`clickly_reply`	Append a thread message — ask a clarifying question or report back to the developer.

Example agent loop

A typical workflow with MCP looks like this:

Start your dev server and open your app in the browser
Start a Claude Code session: claude
Annotate elements in the browser using the Clickly toolbar
Tell Claude: “Check Clickly annotations and fix all issues”
Claude calls clickly_list_annotations, reads the structured data, locates source files, and applies fixes
Claude calls clickly_resolve on each one as it goes

No copy-paste. No screenshot attachments. No ambiguous descriptions.

Analyze & Fix — one click, no prompt

Once MCP is connected, a wand button appears in the toolbar. Click it and Clickly runs the loop above for you automatically — you never switch to a terminal or type a prompt:

localhost:3000

Clickly’s Dashboard

Claude Code

█

The running clickly-mcp server launches a headless Claude Code run, scoped to your session's pending annotations
Claude reads each one, fixes the referenced source file, and calls clickly_resolve as it goes
Annotation cards flip to Resolved live in the toolbar as it works
The button shows “Claude is working…” then “Done — N fixed”

Autonomy model: auto-apply. Claude edits files directly — there's no per-change approval step. The only safety net is a clean git working tree requirement: a run refuses to start if you have uncommitted changes (or aren't in a git repo at all), so the result is always trivially revertible with git checkout ..

If your project root isn't the directory you launch clickly-mcp server from, point it explicitly:

clickly-mcp server --project-root /path/to/your/project

Port configuration

The default port is 4747. Change it with --port <n> on clickly-mcp server, and update the endpoint prop (or the Settings panel) to match.