Brain MCP setup
With the Brain add-on Claude keeps and searches your own notes and documents. Brain needs no API key and no account elsewhere, so there is almost nothing to set up.
What you need
- Nothing from another service.
- About one minute.
- A seat on MCP Hosted, or MCP Self-hosted, with the Brain add-on.
Where to find it
Keep a history
There is nothing to look up. The one choice is whether Brain keeps a history of every change. With history on, a wrong edit by Claude is one step back, not lost text. We advise to turn it on.
Paste it in AddoCore
- In My Account, open MCP Hosted and pick your seat. On MCP Self-hosted, open your license.
- Go to Tools and choose Set up on the Brain card.
- Choose Save login details, then Test connection. A green result means it works.
Brain is the only add-on that may make changes from the start, because notes Claude cannot write to are of little use. You can still set the seat to read-only. We store your login details encrypted.
About the Brain add-on · Connect Claude to Brain: how it works · All setup guides
Running it yourself
Only for MCP Self-hosted when you set things in the .env file instead of in My Account. With the steps above you do not need this.
Show the technical setup
A Brain MCP setup gives Claude a markdown knowledge base on your own server: a vault folder it can search, read, write and reorganise. You need the Brain entitlement and almost no configuration, because the vault folder already exists in your download. Turn on versioning, so that no write is an unrecoverable overwrite.
What do you need for a Brain MCP setup?
You need a running mcp-core installation and the Brain add-on on the same license. Nothing external: no API key, no third-party account. Not installed yet? Follow the mcp-core install guide first.
- An active license with the
tool:brainentitlement, from the Brain MCP server add-on. - Disk space next to your
docker-compose.ymlfor thevault/folder. - A seat in My Account → MCP Self-hosted with the Brain tool ticked.
Added Brain to an existing license? No new download and no reinstall. The add-on is added to your license, and you get an email with the env vars it needs.
Where does the vault of a Brain MCP setup live?
The vault is the vault/ folder in the directory you unzipped. The docker-compose.yml mounts it into the container as /vault, and VAULT_PATH points the tool at that container path.
VAULT_PATH=/vaultKeep /vault. It is the path inside the container, not a path on your host. To start with existing notes, copy your .md files into the host’s vault/ folder; subfolders are fine. Back up that folder like any other data directory; it holds everything your Brain MCP setup stores.
Which env vars does the Brain MCP setup use?
Brain uses one required variable and a few optional ones. The .env in your download has VAULT_PATH= and the optional lines commented out.
| Variable | Required | Default | Purpose |
|---|---|---|---|
VAULT_PATH | Yes | /vault | Vault location inside the container |
VERSIONING_ENABLED | No | false | true keeps a git history of every change |
INDEX_MAX_AGE_DAYS | No | 7 | Age after which a folder’s search index is rebuilt on next access |
GIT_AUTHOR_NAME | No | MCP Core | Author name on versioning commits |
GIT_AUTHOR_EMAIL | No | mcp-core@localhost | Author email on versioning commits |
Why should a Brain MCP setup use versioning?
With VERSIONING_ENABLED=true, every write, append, move and delete becomes a git commit in the vault. A wrong edit by Claude is then one step back in history, not lost content.
VERSIONING_ENABLED=trueVersioning is off by default on purpose: some teams don’t want a content history on their server. When you turn it on, mcp-core runs git init in the vault by itself the first time; you don’t run any git command. Claude reads the history with brain_history, for one file or the whole vault. Without versioning, that tool returns an empty result.
Which tools does Claude get in read-only and read-write mode?
Brain is the only add-on that defaults to read-write, because a knowledge base Claude can’t write to has little use. You can still set a seat to read-only for Brain when you add it in My Account → MCP Self-hosted → Seats. How the license and the mode interact is explained in entitlements vs. tool modes.
| Mode | Tools Claude sees |
|---|---|
| read-only | brain_read, brain_list, brain_search, brain_history |
| read-write (default) | All of the above, plus brain_write, brain_append, brain_move, brain_delete, brain_reindex, brain_describe_folder |
A few rules apply in every mode. Paths outside the vault are refused. A top-level logs folder can be read but not changed, and the .git folder is never reachable. brain_delete only runs when Claude passes the confirmation DELETE. brain_search checks the index of summaries and headings first and falls back to a full-text scan.
How do you restart and test the Brain MCP setup?
Run the update script from your install folder after changing .env:
./mcp-update.shJust bought the add-on? Pull in the new entitlement right away:
docker exec mcp-core npm run refresh-licenseIn Claude, call mcp_status: it lists the license state, your seat and each tool with its mode. Then ask Claude to “list the vault” and to write a test note. With versioning on, brain_history shows the commit for that note. Which client uses which token is covered in MCP seats.
Which errors come up during a Brain MCP setup?
These messages come from the Brain tool itself.
- “Path outside vault is not allowed”: Claude passed a path like
../. Ask for a path inside the vault. - “The ‘logs’ directory is read-only and cannot be modified”: write somewhere else.
- “The ‘.git’ directory cannot be accessed through brain tools”: expected; the history is only reachable through
brain_history. - “Deletion cancelled: confirm must be exactly “DELETE””: Claude has to confirm a delete explicitly.
- Search finds nothing you know exists: files were changed outside Claude. Ask Claude to run
brain_reindex. - Write tools missing: the seat was added with Brain set to read-only. Add a seat with read-write.
Your Brain MCP setup works when brain_list shows your folders and a test note appears in the host’s vault/ folder. For the other add-ons, see the MCP setup guides.
Ready to try it?