Which scope should I register the Baalda MCP server at?

`claude mcp add` uses local scope by default, which writes to `~/.claude.json` and is active only in the project you ran it from. A vault is relevant everywhere, so `--scope user` is usually the right one. `--scope project` writes a `.mcp.json` in the repo root and shares the server with everyone who clones it.

How do I keep my vault token out of a checked-in .mcp.json?

Reference the environment instead of pasting it. Claude Code expands `${VAR}` and `${VAR:-default}` inside `url` and `headers`, so write `Bearer ${BAALDA_MCP_TOKEN}` and have each teammate mint their own token and export it. That is also the correct permission answer, because the agent then carries that person's access rather than a shared one.

What stops the agent overwriting a note a teammate just changed?

`read_note` returns a `revision`. Pass it back as `expectedRevision` and a write against a note that changed in between is refused instead of merged over the top. `edit_note` adds a second guard: its anchors must match exactly once, and an anchor that matches zero times or more than once refuses the whole call with nothing written.

How much of the vault can a token actually see?

Exactly what that user can see. A Baalda MCP token authenticates as one user inside one vault and every call it makes is gated by the same per-folder and per-note permissions a person gets. That is the main thing it has over `--add-dir`, which draws one boundary at a directory and exposes everything under it.

Claude Code's second brain is a folder, not an integration

Q: Can Claude Code edit a vault outside the directory I launched it in?

Yes. Use `--add-dir ` at launch, `/add-dir` mid-session, or `additionalDirectories` under `permissions` in a settings file. Additional directories follow the same permission rules as the original working directory, which means they are readable without prompts, so scope them at a folder you are comfortable exposing whole.

Every other post in this series answers the same question: my agent cannot see my notes, how do I connect it. Claude Code is the one where the honest answer is that you probably do not have to. It runs on your machine, with file tools pointed at your filesystem, and a Baalda vault is a folder of .md files sitting on that same filesystem. There is no gap to bridge. The question worth asking is the narrower one: when is the folder not enough?

Does Claude Code need MCP to read my notes?

No, not if the vault is on the same disk. Claude Code reads and edits files directly, and by default it has access to files in the directory where you launched it. Point it at your vault folder and it works on the notes the way it works on source: grep across them, open one, rewrite a section.

Baalda's file watcher picks up every change on disk and syncs it to the team, so an edit Claude Code makes with its own Edit tool lands in the same place a teammate's keystroke lands. Nothing to install, no token to mint, no server to keep awake.

MCP is the path for the other case: a vault that is not on this machine, an agent that is not running on your laptop, or a permission boundary narrower than everything your Unix user can open.

How do I point Claude Code at a vault outside the project?

The vault usually is not inside the repo you launched Claude Code in, so you have to widen the session. There are three documented ways, and they differ only in how long they last:

--add-dir <path> at launch, for this session.
/add-dir mid-session, when you realise halfway through that the reasoning is in the vault.
additionalDirectories under permissions in a settings file, for every session in that project.

bash

claude --add-dir ~/Baalda/Engineering

Additional directories follow the same permission rules as the original working directory: they become readable without prompts, and editing follows whatever permission mode you are in. If you want to move the session wholesale rather than add a second root, /cd <path> does that and reloads the new directory's CLAUDE.md and settings.

Read that first sentence twice before you point it at a vault. Readable without prompts means the whole folder, including the parts of it you were not thinking about.

What is Baalda, in one paragraph?

Baalda is a team second brain built on plain markdown files on your own disk. Several people edit the same note in real time over a CRDT, permissions are set per folder and per note, and it is open source under Apache-2.0 and self-hostable. It exposes the vault over MCP so an assistant works with the same files a person does, limited by the same permissions. It is free to run locally, with an optional managed Team plan for hosted sync. If the category is new to you, what a team second brain is covers the idea before the plumbing.

When do you actually need the MCP endpoint?

Four cases, and only the first is about capability.

The files are not reachable. A vault on the managed service or on a self-hosted server is not a folder on your laptop. Neither is a vault your teammate owns and shared one folder of. If Claude Code is running in a container, in CI, or on a machine that is not the one holding the notes, the filesystem route is simply not available.

You want a scope tighter than the filesystem. A vault token authenticates as one user inside one vault and is gated by the same per-folder and per-note permissions that user has. --add-dir has no equivalent. It is one boundary, drawn at a directory, and everything under it is readable.

You want the writes to be checkable. read_note returns a revision, and passing it back as expectedRevision makes a write against a note somebody changed in the meantime refuse rather than land. edit_note takes anchored operations, and an anchor matching zero times or more than once refuses the whole call with nothing written. A raw file rewrite has neither guard.

You want search over more than markdown. search_notes is semantic and keyword search across the vault, and it ranks text extracted from documents and spreadsheets alongside the notes, with each hit saying whether it is a note or a file. Ripgrep does not read your PDFs.

If none of those apply, stop here. The folder is the answer and the rest of this post is optional.

How do I connect Claude Code to Baalda over MCP?

1. Mint a vault token. In the Baalda app, open Vault settings → MCP and create one. It is a mcp_ prefixed opaque string, stored server-side only as a sha256 hash, and shown to you exactly once.

2. Register the server. Baalda serves MCP at POST /api/mcp over Streamable HTTP, so the transport is http and the credential is a header:

bash

claude mcp add --transport http baalda http://localhost:3010/api/mcp \
  --header "Authorization: Bearer mcp_your_token_here"

http://localhost:3010/api/mcp is the default local address. On the managed service it is https://api.baalda.com/api/mcp, and on a self-hosted server it is your own URL plus /api/mcp.

3. Pick the right scope. claude mcp add writes to local scope by default, which lives in ~/.claude.json and is active only in the project you ran it from. That is rarely what you want for a vault, because the vault is relevant everywhere. Use --scope user to register it once for all your projects. --scope project writes a .mcp.json in the repo root and shares the server with everyone who clones it, which is the one to be careful with.

4. If you share it, do not paste the token. Claude Code expands ${VAR} and ${VAR:-default} inside url and headers, so a checked-in .mcp.json can reference the environment instead of carrying the secret:

json

{
  "mcpServers": {
    "baalda": {
      "type": "http",
      "url": "${BAALDA_MCP_URL:-http://localhost:3010}/api/mcp",
      "headers": {
        "Authorization": "Bearer ${BAALDA_MCP_TOKEN}"
      }
    }
  }
}

Each teammate then mints their own token and exports it, which is also the correct answer for permissions: the agent gets that person's access, not a shared superuser's.

5. Check it connected. claude mcp list prints a status per server, and a project-scoped one sits at pending approval until somebody trusts the workspace. Inside a session, /mcp shows the same thing and lets you toggle a server off. Baalda's MCP documentation has the endpoint details if a URL is not resolving.

What changes once Claude Code is connected?

The tool list is the vault's own vocabulary rather than a filesystem's: read_note, search_notes, create_note, update_note, append_note, edit_note, move_note, plus folder operations and list_attachments and read_attachment_text for the files around the notes.

What that buys you over cat and a heredoc is mostly failure behaviour. An anchored edit that cannot find its anchor does nothing and says so. A write against a note that moved under you is refused if you passed the revision. A search returns ranked hits with their kind labelled rather than a wall of grep output you then have to read.

And the writes go through the same sync engine as human keystrokes, so a teammate with that note open watches the text appear rather than finding a second copy of it tomorrow. That is the part that makes this a shared memory instead of a private one, and it is the same argument as what an MCP notes server actually gives an AI.

Where is this the wrong setup?

If you are one person with a local vault, adding the MCP server is ceremony. Use --add-dir, keep the token unminted, and spend the ten minutes on something else.

If your team's written work already lives in Notion or Linear, use their hosted MCP servers instead. They authenticate over OAuth, there is nothing for you to run, and they are up whether or not your laptop is. Baalda needs a process somewhere, which is your own machine for a local vault and a hosted or self-hosted instance for anything else. The honest version of that trade is in Baalda compared with Obsidian as well.

And be careful with the filesystem route on a vault that is not only engineering's. --add-dir makes everything under that path readable without a prompt. If the same vault holds hiring notes or a compensation review, the folder is exactly the wrong boundary and the token is what you want, or better, a second vault.

Baalda is also not a code host. It does not index your repository, it has no view on your branches, and it replaces nothing Claude Code already does well. It is the other half: the written record the repository assumes everybody has read.