---
title: Agents and MCP
description: Let AI coding agents read and edit Octarine notes through the CLI or its built-in MCP server.
---

The Octarine CLI is designed to be driven by AI agents such as Claude Code, Codex, or Cursor as well as by people. Agents can call the CLI from a shell, or connect to it as a Model Context Protocol (MCP) server. Both run the same commands, so behavior is identical either way.

Everything runs locally against your Markdown files. The desktop app does not need to be open.

## `agent-guide`

Print a short guide that tells an agent how to find notes, read them before editing, make small revision-checked edits, and recover from conflicts.

```bash
octarine agent-guide
```

Paste the output into your agent's instructions, such as a project `CLAUDE.md` or `AGENTS.md`, or ask the agent to run the command itself before working with your notes:

```bash
octarine agent-guide >> AGENTS.md
```

## `help --json`

Describe commands in machine-readable form: every argument with its type, default, and allowed values, plus the global options, response envelopes, and [error codes](/cli/automation-and-maintenance#errors).

```bash
octarine help --json
octarine help note edit --json
```

```text
{"schemaVersion":1,"ok":true,"data":{"name":"octarine","version":"0.1.0","commands":[{"command":"note edit","about":"Replace exact text in a note (one match unless --all)","arguments":[{"name":"path","positional":true,"required":true,"schema":{"type":"string"}},{"name":"find","flag":"--find","required":true,"schema":{"type":"string","description":"Exact text to find"}},…]}],"globalOptions":[…],"output":{…},"errors":[…]},"meta":{"truncated":false}}
```

Without `--json`, `octarine help <command>` prints the same help as `octarine <command> --help`.

## `octarine mcp`

Serve the CLI as MCP tools over standard input and output.

```text
octarine mcp [--workspace <name, uuid, or path>] [--all-tools]
```

### Connect An MCP Client

Add Octarine to Claude Code:

```bash
claude mcp add octarine -- octarine mcp --workspace "Work Notes"
```

For clients configured with JSON, such as Claude Desktop or Cursor, add a server entry:

```json
{
  "mcpServers": {
    "octarine": {
      "command": "octarine",
      "args": ["mcp", "--workspace", "Work Notes"]
    }
  }
}
```

If the client cannot find `octarine`, use the full path printed by `which octarine` (or `where octarine` on Windows).

`--workspace` fixes the workspace for the server. Without it, the server uses the [default workspace](/cli/getting-started#select-a-workspace). Every tool also accepts an optional `workspace` argument to target a different workspace for one call.

### Available Tools

Tool names follow the command path, with spaces and hyphens replaced by underscores: `note replace-section` becomes `note_replace_section`. Each tool's input schema matches the command's arguments, and each result is the command's JSON response.

By default, the server exposes a curated set of everyday tools:

| Area | Tools |
| --- | --- |
| Workspaces | `workspace_list`, `workspace_show`, `workspace_info`, `capabilities` |
| Reading | `note_list`, `note_read`, `note_context`, `note_info`, `note_outline`, `note_properties`, `search` |
| Editing | `note_create`, `note_edit`, `note_replace_section`, `note_insert`, `note_patch`, `note_append`, `note_prepend`, `note_update` |
| Organizing | `note_move`, `note_rename`, `note_duplicate`, `note_trash`, `folder_list`, `folder_create`, `folder_move` |
| Links | `link_list`, `link_backlinks`, `link_unresolved`, `link_orphans`, `link_deadends`, `link_mentions` |
| Tasks, tags, and properties | `note_task_list`, `note_task_set`, `task_list`, `tag_list`, `property_list`, `property_get`, `property_set`, `property_unset` |
| Inbox | `inbox_capture`, `inbox_list` |

Add `--all-tools` to expose every other command as well, including folder rename, duplicate, and trash, `link_replace`, views, note types, themes, property definitions, metadata, folder configuration, the rest of the Inbox commands, `schema`, `export`, and `doctor`.

`update`, `completion`, `config`, `workspace use`, `help`, `agent-guide`, and `mcp` are never exposed as tools.

Read-only tools, such as `note_read` and `search`, are marked as read-only. Tools that trash, delete, unset, or replace content, such as `note_trash` and `note_update`, are marked as destructive, so clients that ask before risky actions can prompt you.

## Recommended Agent Workflow

The CLI is built so agents can edit notes precisely without overwriting your changes:

1. **Find notes** with `search` or `note list --sort modified --limit 20`. Follow `meta.nextCursor` with `--cursor` to page through long searches.
2. **Read before editing** with `note context`. It returns the content, its `revision`, the outline with line numbers, properties, links, and backlinks in one call.
3. **Edit as little as possible** with [`note edit`](/cli/notes#note-edit), [`note replace-section`](/cli/notes#note-replace-section), [`note insert`](/cli/notes#note-insert), or [`note patch`](/cli/notes#note-patch), always passing `--revision`. Use `note update` only to rewrite a whole note.
4. **Chain edits** using the `revision` each edit returns.
5. **Handle conflicts.** On `REVISION_CONFLICT`, the note changed since it was read. Re-read it, re-apply the change, and retry with `error.currentRevision`. On `AMBIGUOUS_MATCH`, include more surrounding text.

To link notes, write workspace-relative paths without `.md`, such as `[[Projects/Launch]]` or `[[Projects/Launch#Goals|goals]]`. Moving or renaming a note with the CLI updates links to it automatically.

Set JSON output once so the agent does not need `--json` on every call:

```bash
octarine config set format json
```

#### Quick Answers

### Can AI agents use Octarine without the desktop app running?

Yes. The CLI and its MCP server work directly on the Markdown workspace. They are safe to run while the desktop app is open because writes are atomic and take a workspace lock.

### Does the Octarine MCP server send my notes anywhere?

No. The server only talks to the MCP client that started it, over standard input and output. What that client does with the results depends on the client and the AI provider it uses.

### How do I expose every CLI command over MCP?

Start the server with `octarine mcp --all-tools`.

### How does an agent avoid overwriting my edits?

It passes the `revision` from its last read to every edit. If you changed the note in the meantime, the edit fails with `REVISION_CONFLICT` instead of overwriting your work.