Acres is our first recommendation when you want an AI agent to work with your notes and their visual arrangement. Cards are Markdown files, boards are readable JSON, and the bundled MCP server lets an agent search, create notes, connect ideas and propose a board layout.
We make Acres. Our preference follows a particular workflow: a personal knowledge base on Mac or Windows, with files you keep and agent work you can inspect. If your notes already live in Obsidian, Heptabase or Joplin, those tools also have useful ways to connect an agent. Moving a working library just to acquire an MCP connection is rarely the first step.
Files, MCP and the built-in assistant do different jobs
An agent with file access can read Markdown. MCP adds an app’s own tools, such as searching its index or creating a connection between notes. The built-in assistant is a third route: a conversation inside Acres, using a provider key or a local model you choose.
The Model Context Protocol supplies a shared way for clients to call tools and read resources. It doesn’t decide the quality of the model’s reasoning or keep a cloud client from sending retrieved text to a remote provider.
| Access route | Useful for | What to check |
|---|---|---|
| Acres MCP | Searching notes and building visual boards with an external client | Intended vault, enabled tools and client approvals |
| Direct files | Reading or processing your Markdown with an editor, script or agent | File permissions, backups and review of edits |
| Built-in assistant | Working beside the current board | Chosen model, chat or agent mode, proposals and undo |
| Source-checkout CLI | Developer automation | Requires a source checkout; it isn’t a command installed by the desktop download |
For the usual desktop installation, MCP is the practical route to board editing. Avoid copying a developer command from a source repository and expecting the download to install it.
Connect an agent from Settings
Open the vault you intend to use, then go to Settings → Agents and select the client. Acres supplies entries for Claude Code, Cursor, OpenCode, Codex and Claude Desktop, merging the server configuration into an existing client setup.
Check the resulting vault path. Some clients use global configuration, so a connection can still point to a different vault after you switch projects. Refresh or reopen the client if it hasn’t picked up the tools. If automatic setup fails, use the manual setup information shown by Acres.
For the first request, keep the task small:
Use Acres to list the boards in this vault. Find notes about my reading project, and return their titles with a short explanation of why they are relevant. Don’t change anything.
Verify that it found the right material before granting a larger editing task. The MCP workflow guide continues this example through a draft note, a proposed layout and review.
What the agent can do
The bundled server exposes 29 tools. Read tools include search, read_card, list_boards, read_board, describe_board and neighbors. Editing tools can create or append to cards, tag notes, connect them, add sections and create mind maps.
For an existing board, ask the agent to inspect it first. describe_board gives it a readable account of the arrangement. Board organization follows a separate planning flow: plan_board_layout produces a proposal and ASCII preview; apply_board_layout applies the approved plan. That lets you assess the grouping before changing the workspace.
Mind maps, stickies and floating labels are visual elements. Put durable conclusions in Markdown cards if you need to retrieve and reuse them later.
Review is part of the workflow
When Acres is open, file watching and merge handling let external edits appear in the app. That helps when an agent works while you type; a genuine conflict can preserve an external copy for review instead of silently discarding it.
Use Activity to see agent sessions and changes. Supported changes have a guarded revert, which can refuse to overwrite later work. The built-in assistant also uses board undo, and note rewrite proposals show a diff.
Keep the distinction between review, revert and backup. An Activity entry doesn’t guarantee a one-click inverse for every operation. Raw file edits may have less useful attribution than tool-based edits, and undoing a board arrangement doesn’t necessarily remove every note file created along the way. A backup is still the right recovery path for a larger mistake.
Where the alternatives fit
| App | Why it belongs on the shortlist | Practical distinction |
|---|---|---|
| 1. Acres | Local Markdown, bundled MCP and visual board tools | Newer Mac/Windows app; no mobile or real-time team editing |
| 2. Obsidian | An existing Markdown vault and a broad automation ecosystem | Official CLI needs the app running; MCP integrations vary |
| 3. Heptabase | Connected research with an official remote MCP service | Account authorization and remote data handling |
| 4. Joplin | Open-source notebooks with individually enabled MCP tools | Local database; MCP runs through its Web Clipper service |
Obsidian’s official CLI supports reading, searching and writing; direct Markdown access also works independently of that CLI. Heptabase’s MCP documentation includes scoped read/write access and keyword or semantic search. Joplin’s MCP guide explains per-tool controls. These are real alternatives, not products that lack agent access.
Acres’ strongest case is the combination: an agent can work on the notes and the canvas through tools supplied with the app. To try that combination, download Acres and start with one board.
For an external client’s first task, follow the MCP workflow. For the built-in assistant with a model running on your computer, use the local AI setup guide; the two connections serve different purposes.