Your editor, readable by your AI

From v0.1.118, Notepatra ships notepatra-mcp — a Model Context Protocol server that lets Claude Desktop, Claude Code, OpenAI Codex, the OpenAI Agents SDK, and any spec-compliant MCP client see what you have open, search your workspace, run read-only SQL over your data files, read your Git status and Noter notes, and — only with your explicit per-action approval — edit, save, and create notes. Everything runs over stdio and a local socket. Nothing leaves your machine.

What it is

MCP (the Model Context Protocol) is the open standard AI assistants use to talk to tools. Notepatra's implementation is a small standalone binary, notepatra-mcp, that sits between your AI client and the running editor:

AI client (Claude Desktop, Claude Code, Codex, ...)
        │  stdio · JSON-RPC 2.0 (MCP)
        ▼
  notepatra-mcp  ──local socket──▶  Notepatra (the running editor)

• Transport: a stdio JSON-RPC 2.0 MCP server. It speaks MCP protocol revision 2025-06-18 and also accepts 2025-03-26 and 2024-11-05 from older clients.
• Editor connection: pass --socket and the server talks to the running editor over a dedicated per-user local socket (a Unix domain socket; the editor opens it on launch). Without --socket, the server runs against a built-in mock editor, so you can exercise the protocol without Notepatra running.
• Capabilities: tools (35 of them), resources (your open tabs and Noter notes), and prompts (three ready-made ones).
• Safety: reads never need permission; every write shows an approval card inside the editor window and does nothing until you click Approve. Details below.

In practice: ask your assistant "what do I have open?", "find where the config is parsed", "diff these two tabs", "format this JSON and put it in a new tab" — and it drives the actual editor on your screen.

The tool surface — 35 tools, three tiers

notepatra-mcp exposes 35 tools, grouped in three tiers by what they can touch. Read tools observe. Act tools drive visible, non-destructive editor actions. Write tools change buffer contents or disk — and every one of those is gated behind a human approval card.

Tier 1 — Read (18 tools, no approval needed)

Tier 2 — Act (9 tools, visible and non-destructive)

Tier 3 — Write, with approval (8 tools, human-gated)

The write-approval model

The eight write tools never execute on arrival. Each incoming write request shows a non-modal approval card inside the Notepatra window — it does not steal focus or block your typing — describing what the assistant wants to do, with a preview of the text involved and two buttons: Approve and Deny.

• Nothing happens until you click Approve. The tool call blocks; the assistant just waits.
• 120-second auto-deny. If you don't respond within two minutes, the request is denied automatically and the assistant receives the error approval timed out.
• Deny is a first-class answer. Click Deny and the assistant receives denied by user — as a tool error it can read and react to, not a silent failure.
• One card at a time, in order. Multiple pending writes queue FIFO; you decide each one individually. No batch-approve.
• No headless fallback — by design. If there is no visible editor window to host the card, the write is denied with approval unavailable. There is no auto-approve setting, no environment variable, and no config flag that bypasses the card.

The gate lives in the editor process itself (the C++ bridge), not in the MCP sidecar — so a modified or malicious MCP client still cannot write without a human clicking Approve inside Notepatra. Read and act tools don't prompt: they can't change buffer contents or touch disk.

Setup — pick your client

The server binary is notepatra-mcp. All snippets below pass --socket, which connects it to the running editor; make sure notepatra-mcp is on your PATH (or use its absolute path), and have Notepatra running when the assistant calls a tool.

Get notepatra-mcp

From v0.1.118, every GitHub release ships prebuilt notepatra-mcp binaries — cosign-signed like every other release artifact:

• notepatra-mcp-linux-x64.tar.gz
• notepatra-mcp-linux-arm64.tar.gz
• notepatra-mcp-macos-arm64.tar.gz

Extract, chmod +x notepatra-mcp, and put it somewhere on your PATH:

tar xzf notepatra-mcp-linux-x64.tar.gz
chmod +x notepatra-mcp
sudo mv notepatra-mcp /usr/local/bin/

Or build it from source — the sidecar lives in notepatra-mcp/ in the repo and needs only stable Rust, no other dependencies:

cd notepatra-mcp
cargo build --release   # binary at target/release/notepatra-mcp

Windows is supported from v0.1.119: the sidecar connects to the running editor over a named pipe (\\.\pipe\…), so --socket works there too. Prebuilt Windows binaries aren't in the signed release bundle yet, so on Windows install it with cargo install notepatra-mcp or build from source (above).

Claude Desktop

Add Notepatra to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "notepatra": {
      "command": "notepatra-mcp",
      "args": ["--socket"]
    }
  }
}

Restart Claude Desktop; the Notepatra tools appear in the tools menu.

Claude Code

One command:

claude mcp add notepatra -- notepatra-mcp --socket

Then /mcp inside Claude Code shows the server and its 35 tools.

OpenAI Codex CLI

Add a block to ~/.codex/config.toml:

[mcp_servers.notepatra]
command = "notepatra-mcp"
args = ["--socket"]

OpenAI Agents SDK

Use the SDK's stdio server class (Python shown):

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    params={"command": "notepatra-mcp", "args": ["--socket"]},
) as notepatra:
    agent = Agent(
        name="Editor assistant",
        instructions="Help the user work with what they have open in Notepatra.",
        mcp_servers=[notepatra],
    )
    result = await Runner.run(agent, "What tabs do I have open?")

Any other MCP client

Anything that can launch a stdio MCP server works — Cursor, Windsurf, VS Code, or your own client. Configure it to run the command notepatra-mcp with the argument --socket. The server identifies itself as notepatra-mcp and advertises the tools, resources, and prompts capabilities.

Tip: running notepatra-mcp without --socket starts it against a built-in mock editor — handy for testing a client integration without Notepatra running.

Resources and prompts

Beyond tools, the server exposes two other MCP capabilities:

Resources

• notepatra://tab/N — each open tab, as plain text. resources/list enumerates them with their titles.
• notepatra://note/<basename> — each Noter note, as plain text. If two notes share a basename, the colliding ones are addressed by their URI-encoded full path instead, so every note stays reachable.

Clients that support MCP resources (Claude Desktop's attachment picker, for example) can pull a tab or note straight into the conversation without a tool call.

Prompts

Limitations — the honest list

• The editor must be running. With --socket, tools need a live Notepatra to talk to; if it isn't running, they return the clean error "Notepatra is not running (start the editor first)" rather than hanging.
• Writes need a visible window. The approval card must appear somewhere; with no visible window, writes are denied with approval unavailable. That is deliberate — see the approval model.
• Cloud-only connector surfaces can't reach it. ChatGPT connectors and claude.ai web connectors only speak to servers reachable at a public URL. A desktop editor on your machine is not that, so those surfaces cannot use notepatra-mcp. Use the desktop or CLI clients above instead.
• Windows named-pipe transport (new in v0.1.119). The sidecar now connects to the running editor over a Windows named pipe (\\.\pipe\…), so --socket works on Linux, macOS, and Windows alike. The one remaining gap: prebuilt Windows binaries aren't in the signed release bundle yet, so on Windows you install with cargo install notepatra-mcp or build from source.
• Large reads are capped. read_tab truncates at 5 MB (and says so with a marker in the text); search_project returns at most 200 matches per search.
• Search defaults to literal. find_in_tab and search_project match a literal substring by default; pass {regex: true} for a regular-expression search (an invalid pattern is rejected with a clear error).

FAQ

Is my data sent anywhere?

Not by Notepatra. notepatra-mcp makes no network connections: it talks to your AI client over stdio (pipes between two processes on your machine) and to the editor over a local per-user socket. Nothing leaves the machine through this path. One honest caveat that applies to every MCP server: whatever your assistant reads through these tools becomes part of its conversation, and goes wherever that client sends its conversations — a local model stays local, a cloud model does not. Choose the client and model accordingly.

Can the AI edit my files without me noticing?

No. The only tools that can change a buffer or touch disk are the eight write tools, and each call requires you to click Approve on a card inside the editor within 120 seconds. No response means denied.

Is this the same as Notepatra's built-in AI Assistant?

No — they're complementary. The AI Assistant dock (Ctrl+Shift+A) is Notepatra talking to a model you configure. MCP is the reverse direction: an external assistant you already use (Claude, Codex, ...) talking to Notepatra. Neither requires the other.

Does it work with the Lite build?

Yes. The MCP bridge is part of the editor from v0.1.118 on both editions, and app_info reports which edition is running.

Which tab is index 0?

Tab indices are zero-based, exactly as shown in the tab bar — including the Welcome tab when it's open. Use list_open_tabs first rather than guessing indices.