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 (48 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 — 49 tools, three tiers

notepatra-mcp exposes 49 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 (24 tools, no approval needed)

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

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

What changed in v0.1.127

Retesting v0.1.126 found a sixth credential door, and the interesting part is not the door — it is why there kept being another one.

Why the fix is structural rather than a sixth guard

Three consecutive releases shipped this same shape. v0.1.125 unified two hand-maintained copies of the deny list. v0.1.126 added the check to four verbs. The retest then found a fifth and a sixth.

Every one of those fixes was correct and none of them converged, because what kept going stale was not the list — it was the enumeration. Every new verb had to remember to ask, and the point of a security guard is that it does not depend on remembering.

Buffer text now leaves the editor through exactly one accessor, which refuses before it returns. select_range refuses to stage a selection over a credential file at all, so no future verb can inherit a leak that was already set up for it. And a test lints the bridge source and fails the build on any direct buffer read that bypasses the accessor — so a verb added next year cannot reintroduce the class without turning a test red.

Two smaller corrections

• The truncation marker was lying about the cap. Ask read_tab for max_bytes: 100 and the text still ended [truncated at 5 MB] — a constant left over from before the argument existed. It now reads [truncated: showing 100 of 2688894 characters]. The v0.1.126 notes also claimed read_tab "always reports truncated and total_chars"; that is true of the editor-to-sidecar wire and not of the tool result, which is plain text, so the marker is where those counts have to live.
• select_range advertised tab_id and then rejected it with -32602, so a client generating calls from the published schema failed. One verb out of thirteen slipped the v0.1.126 sweep. A test now walks the entire tool list and asserts every advertised tab_id is genuinely accepted — a schema that lies is worse than a missing feature, because it makes correct clients fail. Separately, list_open_tabs published the field as id while every verb takes tab_id; both names are emitted for one release.

What changed in v0.1.126

v0.1.125 fixed a credential leak in search_project. A retest of that release found the fix covered one read path out of four — and eight other defects alongside it. Everything below is now the shipped behaviour.

Tools that reported success while returning the wrong answer

• format_json invented structure. The MCP path called the editor's JSON auto-fixer, which is right for the JSON panel — a human sees the repair and can undo it — and wrong here. [1,2 came back as [1,2] with isError:false: a truncated config file made syntactically valid and semantically invented. Format-then-write-back would have fabricated data you never had. It validates strictly now and fails with a parse position.
• A search that simply missed reported "No workspace folder is open". Whether a folder is open is not a fact about your query, but the error only fired when the open tabs happened to contain nothing — so the same tabs answered "not found" for one query and "you have no folder open" for another. Zero matches is a successful search now, with the reduced coverage carried in a notice.
• Without --socket, everything was fabricated and nothing said so. Only --help warned, and the consumer is a model that never reads it. Every mock result now carries a [MOCK DATA] block and _meta.mock.

Tabs have a stable id

Every write verb used to address its target by tab_index. That index is positional: close a tab to its left and it silently re-points at a different document, underneath a caller with no way to notice. Out-of-range was the lucky case — you get an error. A shifted-but-still-valid index writes silently, with the approval card the only thing in the way.

list_open_tabs now publishes an id per tab that survives reordering, save-as, and its neighbours closing, and every verb that names a tab accepts tab_id. Asking for an id that is gone tells you it was closed, rather than reporting a bad index you never supplied. tab_index keeps working everywhere it did.

Smaller corrections

• search_project now actually sends the workspace_searched and scope fields v0.1.125 promised — the editor had been sending them all along and the sidecar's own result struct discarded them.
• read_tab takes max_bytes, and a capped read ends with a marker stating how much you got of how much there is, so a multi-megabyte buffer can be paged rather than filling your context in one call.
• find_in_tab accepts title, which read_tab always accepted and find_in_tab rejected as an unexpected argument.
• An invalid pagination cursor on tools/list is rejected instead of ignored — returning the full list is indistinguishable from "your cursor was valid, here is page 2".

The write-approval model

The eleven 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 named-pipe transport arrived in v0.1.119 but did not actually work: it deadlocked on the first verb after the greeting, so no tool call ever completed. It is fixed in v0.1.120 — the sidecar connects to the running editor over a named pipe (\\.\pipe\…) and --socket works there for real. As of v0.1.120 the signed release bundle provides a prebuilt Windows binary (notepatra-mcp-windows-x64.zip, cosign-signed like the others) and a one-click Claude Desktop bundle (notepatra-mcp.mcpb — install it from Claude Desktop's Settings → Extensions), so Windows users no longer need to build from source. cargo install notepatra-mcp remains a fully supported alternative on every platform.

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 49 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 (added v0.1.119, working from v0.1.120). The v0.1.119 implementation deadlocked on every verb, so Windows tool calls never completed; v0.1.120 fixes it. The sidecar connects to the running editor over a Windows named pipe (\\.\pipe\…), so --socket works on Linux, macOS, and Windows alike. Prebuilt Windows binaries (notepatra-mcp-windows-x64.zip) and the one-click notepatra-mcp.mcpb Claude Desktop bundle ship as v0.1.120 release assets; cargo install notepatra-mcp remains a fully supported alternative on every platform.
• Large reads are capped. read_tab truncates at 5 MB (and says so with a marker in the text) and accepts a smaller max_bytes; search_project returns at most 200 matches per search.
• Credential files are refused, and you cannot override it. open_file, read_tab, find_in_tab and both legs of search_project refuse anything matching the credential deny-list — SSH/GPG/AWS key directories, id_rsa anywhere on a path, .env files, *.pem / *.key / *.pfx / *.p12 / *.jks, Terraform state. This constrains the MCP surface, not you: open the file yourself and the editor shows it normally. A legitimate *.pem test fixture will be refused, which is the intended trade — a refused read costs you one click, a leaked key does not.
• The Deny button is less tested than the timeout. Approval-card denial by 120-second timeout is verified repeatedly; denial by clicking Deny is exercised in the automated suite but has had less real-hands testing.
• 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. The notepatra-mcp binary you install 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 — and the shipped binary is not merely configured that way, it is compiled without networking at all. Every CI job runs the released binary and fails the build unless it reports built without remote support. 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.

What is the remote gateway in v0.1.120, and does it weaken any of this?

v0.1.120 adds an opt-in remote gateway, and it is off unless you deliberately build it: the code sits behind a remote Cargo feature that is not in the default feature set, so cargo install notepatra-mcp and every signed release binary contain no gateway and no networking or crypto dependencies at all. If you do build it (cargo build --features remote), serve binds loopback only — 127.0.0.1, never a LAN or public interface — and a client must complete an 8-digit one-time HMAC pairing to receive a 256-bit bearer token, of which only the SHA-256 is stored, mode 0600. Scopes are fail-closed: a client is read-only unless it paired for more, calls above its scope are rejected at dispatch, and tools/list is filtered to the tiers it is allowed. A missing or invalid token never elevates.

The approval gate is unchanged, and there is no remote approval. A remote write request is only forwarded to the editor, which raises the same Approve / Deny card on your screen. Nobody can approve a write from the far end of the connection, and there is no headless bypass. The editor itself never listens on the network — only the opt-in sidecar gateway binds a socket. Until LAN support and TLS land, use an SSH tunnel rather than exposing the port.

Can the AI edit my files without me noticing?

No. The only tools that can change a buffer or touch disk are the eleven 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. Better still, use the id it returns: an index is positional and moves the moment a tab closes, while an id belongs to the document for as long as it is open.

What happened to the mock server?

Running notepatra-mcp without --socket still starts an in-memory demo editor, so any MCP client can exercise the protocol with nothing installed. As of v0.1.127 it says so on the wire: every result carries a [MOCK DATA] block and _meta.mock, and initialize reports serverInfo.mock. Before that, a config file that had lost its --socket served fabricated tabs an assistant could not tell from your real ones.