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 alongside your dev server and exposes a set of tools your agent can call to read, list, and clear annotations in real time.

Instead of copying a markdown block and pasting it into Claude, your agent can call clickly_get_annotations at any point during a task and receive the latest annotations as structured JSON.

Install the MCP server

Run the install command once to register Clickly with your MCP client config (e.g., claude_desktop_config.json):

npx @useclickly/mcp-server install

Or run the server manually if you prefer to manage config yourself:

npx @useclickly/mcp-server start --port 3741

Claude desktop config

If you're using Claude Desktop, add the following to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent path on Windows/Linux:

{
  "mcpServers": {
    "clickly": {
      "command": "npx",
      "args": ["@useclickly/mcp-server", "start"],
      "env": {
        "CLICKLY_PORT": "3741"
      }
    }
  }
}

Restart Claude Desktop after saving. You should see “Clickly” listed under connected MCP servers in Settings → Developer.

Connect your React app

Pass the mcp prop to <Clickly /> to enable the local WebSocket bridge between your browser and the MCP server:

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

export function ToolbarProvider() {
  return (
    <Clickly
      mcp={{
        enabled: true,
        port: 3741,
      }}
    />
  );
}

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

MCP tools

Tool	Description
`clickly_get_annotations`	Returns all current annotations as a JSON array. Each item includes element, selector, source, component tree, and feedback.
`clickly_list_annotations`	Returns a compact summary of annotation count and a brief description of each — useful for a quick status check before reading full detail.
`clickly_get_annotation`	Returns a single annotation by ID. Useful after listing to drill into one issue.
`clickly_clear_annotations`	Clears all annotations from the current session. The agent can call this after addressing all issues in a pass.
`clickly_get_status`	Returns server status, connected page URL, and annotation count. Useful as a health check at the start of an agent loop.

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_get_annotations, reads the structured data, locates source files, and applies fixes
Claude calls clickly_clear_annotations when done

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

Port configuration

The default port is 3741. Change it by passing CLICKLY_PORT as an environment variable to the MCP server, and setting port in the mcp prop to match. Ensure the port is not blocked by a firewall or used by another process.