Once a note library is large enough that you no longer remember which Thread—or even which week—contains a particular line, AI is most useful as a tool operator. It can search, retrieve, and reorganize through explicit operations instead of merely generating more text.

The macOS version of OrbNote includes an MCP service. Claude Code, Codex, and other clients that support stdio MCP can start this local process and call the tools you have authorized.

Three parties participate in the connection

Understand the boundary before copying the configuration:

  1. The OrbNote store holds local notes and optionally syncs them through your private iCloud database.
  2. The OrbNoteMCP process reads the shared App Group store and returns JSON-RPC results over stdin/stdout. Its sandbox declares the App Group but no network entitlement.
  3. The external AI client receives those results and decides whether and how to send them to a local or remote model.

The lack of a network entitlement prevents OrbNoteMCP from opening its own network connection. It does not guarantee that Claude, Codex, or another client will keep returned data on the device. Review the model, logging, and retention settings of the client you use.

OrbNote currently ships the MCP server with the macOS app only. iOS, iPadOS, and watchOS cannot act as the server.

Step 1: Allow only the Threads you need

Open OrbNote Settings → MCP Access:

  1. Confirm that the global switch is on. It starts enabled in the current implementation.
  2. Under Allowed Threads, enable each Thread required for the task.
  3. Do not broadly allow journals, finance, or credential-related Threads for convenience.

The per-Thread mcpAccessEnabled value starts false. The global switch controls whether MCP is available; the Thread switch controls which records may be read or changed. Except for orbnote_status, tools require both gates.

Password-protected Threads add another content gate. MCP may return limited Thread metadata but not message or article bodies. This check is based on whether the Thread has a password; it does not inherit a temporary unlock state from the main app.

Step 2: Copy the configuration generated by the app

The settings screen generates a configuration for the current installation path. An App Store installation usually looks like this:

{
  "mcpServers": {
    "orbnote": {
      "type": "stdio",
      "command": "/Applications/OrbNote.app/Contents/Library/OrbNoteMCP",
      "args": [],
      "env": {}
    }
  }
}

Copy this value from OrbNote instead of typing the path yourself. Xcode builds and apps installed in another folder will not necessarily live under /Applications.

Add the entry to your client's MCP configuration. Client commands and file locations change more frequently than OrbNote's data model, so the MCP service guide maintains the client-specific instructions in one place.

Step 3: Verify with read-only calls

Start with:

orbnote_status

The response reports whether MCP is enabled, the store path, basic group/Thread/message counts, the number of accessible Threads, and the tool list. Then call orbnote_list_threads and confirm that it returns only the Threads you just allowed.

An accessible count of zero usually means the connection is healthy but no Thread permission has been enabled yet.

Three workflows worth using

1. Search for a phrase when you do not remember the location

Ask something specific:

Search OrbNote for “first launch explains too many concepts” and tell me whether each result matched a message, attachment, or transcript.

The client calls orbnote_search, which searches Threads, messages, long-form articles, and attachments. Results include match reasons for OCR, transcription, descriptions, and metadata. Use orbnote_get_thread or orbnote_get_article only after finding a likely result, rather than retrieving an entire library up front.

2. Write an external result back to a Thread

For example:

Add this to “Work Log”: Completed the first-launch settings test. Include https://example.com/report.

orbnote_add_note accepts text and an optional URL. Messages created through MCP receive source = "mcp", which preserves their provenance in the app. A write fails if the target Thread is not allowed; it does not bypass the permission.

3. Validate before reorganizing

Do not let a vague instruction jump directly to a structural change. Use this sequence:

  1. Call orbnote_get_reorg_snapshot for groups, Threads, and a limited set of recent message IDs.
  2. Ask the client to present a concrete operation list.
  3. Run orbnote_validate_reorg_plan, which checks the plan without changing data.
  4. Review it, then call orbnote_apply_reorg_plan.
  5. Keep the returned plan_id for orbnote_rollback_reorg_plan if needed.

Plans can create or rename groups and Threads, move Threads, and move messages. Rollback is not unlimited undo: later changes may make a created object ineligible for rollback. Review remains necessary.

Troubleshooting

Symptom Likely cause What to do
OrbNoteMCP cannot be found The app is not at the configured path Copy the configuration again from Settings
orbnote_status reports disabled The global MCP switch is off Enable MCP Access in OrbNote
The client connects but lists no Threads No per-Thread access is enabled Allow only the Threads required for the task
A Thread appears without its content The Thread is password-protected This is the expected content gate
A write returns an access error The target is closed or the ID is stale List accessible Threads and confirm the target ID
A reorganization plan fails References are stale or an operation is invalid Fetch a new snapshot and validate again

Least privilege matters more than “AI integration”

MCP turns natural-language intent into inspectable tool calls. It does not make an external AI client trustworthy, nor does it choose which information should be exposed.

A careful routine is straightforward: allow only the Threads needed for the current task, begin with read-only calls, inspect write targets, validate structural changes, and revoke permissions that are no longer needed.