# AI overview

> Two ways an agent works a vault: directly on the files when it can reach your disk, and over MCP when it cannot.

Source: https://baalda.com/docs/ai-overview
Site: Baalda, https://baalda.com

Because notes are plain files, an AI does not need an integration to work with them. Baalda's job is to make the AI's edits merge with everyone else's rather than overwrite them, and to apply the same permissions to an agent that it applies to a person.

## Two paths

|  | Local agent | MCP endpoint |
|---|---|---|
| Examples | Claude Code, Codex, any CLI tool with disk access | A cloud assistant, a custom connector, an autonomous agent |
| Setup | None. Point it at the vault folder | Create a token, register the endpoint |
| How it edits | Writes the `.md` file. The watcher diffs it into operations | Calls tools that write through the same sync engine |
| What limits it | Your own filesystem permissions | The same per-folder access the token's owner has |
| Needs a server | No. It works on a local-only vault | Yes, and the vault must be synced |

## Why an AI edit merges

Whichever path it takes, the change becomes operations on the same CRDT document a person is typing into. A rewrite of one paragraph while a teammate edits another converges, instead of one write winning. If the note is open you will watch the AI type in real time.

## What an agent may reach

Over MCP, a token is scoped to one person in one vault, and every call is resolved against that person's effective permission. A folder that person cannot see does not appear in a listing, does not appear in search results and cannot be read, written or renamed. The same rules cover files, not only notes.

## Writing safely

- `read_note` returns a `revision`. Passing it back as `expectedRevision` makes the write fail if the note changed in between, rather than merging into something the agent has not read.
- `edit_note` works at exact anchors and refuses the whole call if an anchor is missing or matches more than once, so a partial edit is never written.
- `append_note` takes an idempotency key, so a retried call cannot append the same text twice.
- Every tool carries annotations saying whether it is read-only or destructive, which a client can show before it calls.

- [Set up MCP](/docs/mcp-setup): Create a token, register the endpoint, connect a client.
- [MCP tool reference](/docs/mcp-tools): Every tool, with its parameters and refusals.