Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jasonkneen/openclicky/llms.txt

Use this file to discover all available pages before exploring further.

OpenClicky’s bridge exposes an MCP-compatible tool layer on top of the raw HTTP endpoints. Agent runtimes that already speak MCP — Cursor extensions, Claude Desktop, custom agent loops — can interact with OpenClicky through a single consistent tool-call shape instead of hitting individual REST paths. The bridge supports three call styles: a single-tool endpoint, a batch endpoint for coordinated multi-step sequences, and a JSON-RPC 2.0 envelope for strict MCP protocol compatibility.
All MCP endpoints require the bridge token via x-openclicky-token or Authorization: Bearer <token>, except /health. Coordinates are macOS/AppKit global screen space with the origin at the bottom-left of the combined display rectangle.

​
GET /mcp/tools — list tool descriptors

Returns the full list of MCP-style tool descriptors in inputSchema-annotated format. Use this for runtime discovery or for registering OpenClicky tools in an agent’s tool registry. 
curl -s http://127.0.0.1:32123/mcp/tools \
  -H 'x-openclicky-token: YOUR_TOKEN'
Response (200) 
{
  "ok": true,
  "tools": [
    {
      "name": "openclicky_point",
      "description": "Point OpenClicky's native cursor at a macOS screen coordinate with a short caption.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "x": {"type": "number"},
          "y": {"type": "number"},
          "caption": {"type": "string"},
          "durationMs": {"type": "number"},
          "accentHex": {"type": "string"},
          "mode": {"type": "string", "enum": ["primary", "secondary"]}
        },
        "required": ["x", "y"]
      }
    }
  ]
}

​
POST /mcp/call — single tool call

Invokes one tool by name. The body shape is {"tool": "...", "arguments": {...}}. The arguments object is passed directly to the underlying command handler — the same fields accepted by the corresponding REST endpoint apply here. 
curl -s -X POST http://127.0.0.1:32123/mcp/call \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{"tool":"openclicky_point","arguments":{"x":640,"y":520,"caption":"This one"}}'
​
tool
string
required
The tool name to invoke. See Supported tool names below.
​
arguments
object
required
Tool-specific arguments object. The fields mirror those of the corresponding REST endpoint.
Response (200) 
{"ok": true}
/tools/call is accepted as an alias for /mcp/call.

​
POST /mcp/calls — batch tool calls

Executes an ordered list of tool calls sequentially. All calls in the batch run to completion before the response is returned. Use this to choreograph multi-step overlay sequences — for example, clearing stale markers, placing a new pointer, and speaking a caption in a single atomic HTTP request. Each call object in the array may include an optional delayMs field (0–10 000 ms) to introduce a pause before that call executes. This is useful for pacing animated tours. 
curl -s -X POST http://127.0.0.1:32123/mcp/calls \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{
    "calls": [
      {"tool": "clear", "arguments": {}},
      {"tool": "openclicky_point", "arguments": {"x":640,"y":520,"caption":"Start here"}},
      {"tool": "speak", "arguments": {"text":"Start with this button."}}
    ]
  }'
​
calls
array
required
Ordered array of call objects. Each object must include tool (or name) and arguments (or args). An optional delayMs field introduces a pause before the call executes (0–10 000 ms).
Response When all calls succeed the status is 200. When one or more calls fail the status is 207 Multi-Status. Each result in the results array carries index, tool, ok, statusCode, and body. 
{
  "ok": true,
  "results": [
    {"index": 0, "tool": "clear", "ok": true, "statusCode": 200, "body": {"ok": true}},
    {"index": 1, "tool": "openclicky_point", "ok": true, "statusCode": 200, "body": {"ok": true}},
    {"index": 2, "tool": "speak", "ok": true, "statusCode": 200, "body": {"ok": true}}
  ]
}
/tools/calls is accepted as an alias for /mcp/calls.

​
POST /mcp — JSON-RPC 2.0

Accepts a JSON-RPC 2.0 envelope for strict MCP protocol compatibility. Useful when integrating with runtimes that generate standard MCP wire traffic. Supported methods
MethodDescription
initializeReturns protocol version 2024-11-05, server info, and capabilities.
notifications/initializedAcknowledgement; returns an empty result.
tools/listReturns the full tool descriptor list.
tools/callInvokes a single tool by name.
initialize 
curl -s -X POST http://127.0.0.1:32123/mcp \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {"tools": {"listChanged": false}},
    "serverInfo": {"name": "OpenClicky External Control Bridge", "version": "1.0.0"}
  }
}
tools/list 
curl -s -X POST http://127.0.0.1:32123/mcp \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
tools/call 
curl -s -X POST http://127.0.0.1:32123/mcp \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "openclicky_point",
      "arguments": {"x":640,"y":520,"caption":"This one"}
    }
  }'

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{"type": "text", "text": "ok"}],
    "isError": false
  }
}
When a tool name is missing or unknown, the response carries a JSON-RPC error object with code -32602.

​
Supported tool names

openclicky_point and openclicky_point_many are the preferred names for new integrations. The show_cursor / show_cursors names are compatibility aliases and behave identically.

​
openclicky_point

The standard single-target pointing tool. Triggers OpenClicky’s native primary cursor choreography by default. 
curl -s -X POST http://127.0.0.1:32123/mcp/call \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{"tool":"openclicky_point","arguments":{"x":1180,"y":760,"caption":"Use this menu","durationMs":5000}}'
Arguments: x (required), y (required), caption, durationMs, travelMs, accentHex, mode ("primary" | "secondary")

​
openclicky_point_many

Places several temporary secondary markers simultaneously. 
curl -s -X POST http://127.0.0.1:32123/mcp/call \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{
    "tool": "openclicky_point_many",
    "arguments": {
      "durationMs": 4500,
      "cursors": [
        {"x":640,"y":520,"caption":"Option A","accentHex":"#60A5FA"},
        {"x":900,"y":520,"caption":"Option B","accentHex":"#34D399"}
      ]
    }
  }'
Arguments: cursors (required array), durationMs

​
show_cursor / openclicky_show_cursor

Compatibility aliases for openclicky_point. Accepts the same arguments. 
curl -s -X POST http://127.0.0.1:32123/mcp/call \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{"tool":"show_cursor","arguments":{"x":640,"y":520,"caption":"Click here"}}'

​
show_cursors / openclicky_show_cursors

Compatibility aliases for openclicky_point_many. Accepts the same arguments. 
curl -s -X POST http://127.0.0.1:32123/mcp/call \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{
    "tool": "show_cursors",
    "arguments": {
      "cursors": [
        {"x":640,"y":980,"caption":"Menu","accentHex":"#60A5FA"},
        {"x":820,"y":820,"caption":"Editor","accentHex":"#34D399"}
      ],
      "durationMs": 4500
    }
  }'

​
show_caption

Shows a floating text caption. x and y are optional; if omitted the caption appears near the current mouse position. 
curl -s -X POST http://127.0.0.1:32123/mcp/call \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{"tool":"show_caption","arguments":{"x":900,"y":700,"text":"This is the setting you want","durationMs":5000}}'
Arguments: text (required), x, y, durationMs, accentHex

​
screenshot

Captures local screenshots with display frame metadata for locating UI in AppKit coordinate space. 
curl -s -X POST http://127.0.0.1:32123/mcp/call \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{"tool":"screenshot","arguments":{"focused":false}}'
Arguments: focused (boolean, default false)

​
speak

Speaks a short instruction through OpenClicky’s TTS. 
curl -s -X POST http://127.0.0.1:32123/mcp/call \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{"tool":"speak","arguments":{"text":"Click the button in the top right."}}'
Arguments: text (required), interrupt (boolean, default false)

​
clear

Clears all bridge-created cursors and captions. Takes no arguments. 
curl -s -X POST http://127.0.0.1:32123/mcp/call \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{"tool":"clear","arguments":{}}'

​
Use case: screen tours with the batch endpoint

The batch endpoint is the natural fit for screen tours. A tour scene typically needs to clear stale overlays, place fresh markers, and optionally narrate — three operations that should feel instantaneous to the user. Bundling them in a single /mcp/calls request removes round-trip latency and keeps the visual result coherent. The openclicky-screen-tour skill uses this pattern: it posts a batch of clear → openclicky_point_many → speak, then follows with a series of individual openclicky_point calls (each with a short delayMs) to walk through each item using the native primary cursor choreography. Minimal scene transition 
curl -s -X POST http://127.0.0.1:32123/mcp/calls \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{
    "calls": [
      {"tool": "clear", "arguments": {}},
      {
        "tool": "openclicky_point_many",
        "arguments": {
          "durationMs": 6500,
          "cursors": [
            {"x":640,"y":980,"caption":"Menu bar","accentHex":"#60A5FA"},
            {"x":820,"y":820,"caption":"Editor","accentHex":"#34D399"},
            {"x":380,"y":755,"caption":"Sidebar","accentHex":"#F59E0B"},
            {"x":960,"y":675,"caption":"Logs","accentHex":"#FF7A9A"}
          ]
        }
      },
      {
        "tool": "speak",
        "arguments": {"text":"Here are the four main areas of the interface.","interrupt":true}
      }
    ]
  }'
Stepping through items with the primary cursor After placing the overview markers, visit each item with the primary cursor choreography. Use delayMs to pace the steps: 
curl -s -X POST http://127.0.0.1:32123/mcp/calls \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{
    "calls": [
      {"tool": "openclicky_point", "arguments": {"x":640,"y":980,"caption":"Menu bar","durationMs":1800}},
      {"tool": "openclicky_point", "arguments": {"x":820,"y":820,"caption":"Editor","durationMs":1800}, "delayMs": 1400},
      {"tool": "openclicky_point", "arguments": {"x":380,"y":755,"caption":"Sidebar","durationMs":1800}, "delayMs": 1400},
      {"tool": "openclicky_point", "arguments": {"x":960,"y":675,"caption":"Logs","durationMs":1800}, "delayMs": 1400}
    ]
  }'
Keep captions to 1–3 words and use distinct accentHex colors per marker so viewers can track which label belongs to which point in a recording.
Full tour — overview then step-through in one request 
curl -s -X POST http://127.0.0.1:32123/mcp/calls \
  -H 'Content-Type: application/json' \
  -H 'x-openclicky-token: YOUR_TOKEN' \
  -d '{
    "calls": [
      {"tool": "clear", "arguments": {}},
      {
        "tool": "speak",
        "arguments": {"text":"Let me walk you through the layout.","interrupt":true}
      },
      {
        "tool": "openclicky_point_many",
        "arguments": {
          "durationMs": 5000,
          "cursors": [
            {"x":640,"y":980,"caption":"Menu bar","accentHex":"#60A5FA"},
            {"x":820,"y":820,"caption":"Editor","accentHex":"#34D399"}
          ]
        },
        "delayMs": 400
      },
      {"tool": "openclicky_point", "arguments": {"x":640,"y":980,"caption":"Menu bar","durationMs":2000}, "delayMs": 1200},
      {"tool": "openclicky_point", "arguments": {"x":820,"y":820,"caption":"Editor","durationMs":2000}, "delayMs": 1600},
      {"tool": "clear", "arguments": {}, "delayMs": 2200}
    ]
  }'
Batch calls run sequentially and block until all calls complete. Keep total estimated duration under 30 seconds to avoid client-side timeouts. For very long tours, split the sequence into multiple /mcp/calls requests.

Build docs developers (and LLMs) love

Get started for freeTalk to us