Agents

Mindle exposes an MCP (Model Context Protocol) server so an agent can read your open files, see your annotations, and join the conversation.

What it is

Mindle runs a local Unix-socket MCP server while the app is open. The bundled mindle-mcp binary is a thin stdio shim that any MCP-aware client (Claude Code, Claude Desktop, Cursor, custom) can spawn to talk to Mindle.

Socket path: ~/Library/Caches/local.fnp.mindle/mcp.sock
Helper: /Applications/Mindle.app/Contents/MacOS/mindle-mcp
The socket only exists while Mindle is running. No network. No telemetry. No keys.

Install

Claude Code

claude mcp add mindle /Applications/Mindle.app/Contents/MacOS/mindle-mcp

Restart Claude Code so it handshakes the new server.

Claude Desktop

Add this entry to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mindle": {
      "command": "/Applications/Mindle.app/Contents/MacOS/mindle-mcp"
    }
  }
}

Restart Claude Desktop.

Other MCP clients

Point the client at /Applications/Mindle.app/Contents/MacOS/mindle-mcp as an stdio MCP server. No arguments needed. The tool descriptions carry enough protocol guidance that vanilla agents run the collaboration loop without a custom skill.

Tools

Tool	Direction	What it does
`list_open_files`	read	Every file open in any Mindle window.
`get_annotations(path)`	read	Annotations and threads on a file.
`get_collaborators(path)`	read	Identity registry for a document.
`open_file(path, focus_app?)`	write	Open a file in Mindle (or activate an existing tab). Defaults to opening silently in the background.
`create_annotation(path, text, prefix, suffix, note)`	write	Open an agent-authored annotation on a passage.
`comment_on_annotation(path, id, text)`	write	Append a message to an annotation thread.
`react_to_annotation(path, id, kind, message_id?)`	write	Toggle a 👍 / ❤️ / 😄 reaction on an annotation or thread message.
`clear_annotation(path, id, summary)`	write	Mark an annotation done with a summary.
`resolve_annotation(path, id, author?)`	write	Move an annotation to resolved.
`assign_annotation(path, id, assignee)`	write	Hand an annotation to a named collaborator.
`wait_for_annotation_event(timeout_seconds, since_event_id)`	read	Long-poll for the next user event (created / replied / deleted).

The server is read-only as far as the file system is concerned. File I/O stays in the agent's own tools — Mindle exposes only the annotation channel.

The collaboration loop

The intended pattern, with both Claude Code and Claude Desktop:

Open the file in Mindle.
Ask the agent: "watch my Mindle annotations and answer them".
The agent calls wait_for_annotation_event in a loop.
You annotate (⌘⇧N for a note, type, Return).
The agent wakes within a second, reads the surrounding context via get_annotations, and either replies in the thread (comment_on_annotation) or edits the file with its own tools and clears the annotation (clear_annotation).

Agents can also originate annotations of their own with create_annotation — for example, to leave questions on a paper after a read-through.

Identity

Annotations and replies carry an author identifier. Human authors use the display name you set on first launch. Agent authors are recorded as agent, with an additional agent tag derived from the MCP client's clientInfo.name at handshake (for example, claude-code or cursor). The tag renders as a small monospace chip on every annotation, reply, and reaction the agent makes, so multiple agents working on the same document can be told apart.

Older mindle-mcp helpers that didn't send a tag still work — the chip is just omitted, and the annotation appears as a generic agent.

Privacy

The socket only exists while Mindle is running.
No outbound network connections from Mindle's MCP server.
Annotations remain in the file's sidecar; nothing is uploaded.
The agent's own tools may make network calls — that's outside Mindle's scope.

← Back to Mindle