Cursor as a second brain: the notes that explain your repo

Cursor knows your repository better than most of the people who wrote it. It can trace a call through six files, name every caller of a function, and rewrite a module without being told where the tests live. What it cannot tell you is why any of it is that way. The reason you took Postgres over DynamoDB, the incident that produced the retry logic, the customer commitment behind the strange feature flag: none of that is in the code. It is in the team's notes, and the notes are somewhere Cursor cannot see.

Can Cursor read and write my team's notes?

Yes. Cursor is an MCP client and Baalda runs a Model Context Protocol server over your vault. Add Baalda to Cursor's mcp.json with a vault token and the agent can search, read, create and edit the same .md files your teammates have open in the Baalda desktop app.

Cursor supports three MCP transports: local stdio servers it starts itself, and remote SSE or Streamable HTTP servers it reaches over a URL. Baalda is the third kind. It serves MCP at POST /api/mcp over Streamable HTTP, so the config is a URL and an auth header rather than a command to run.

Why does Cursor keep relitigating decisions your team already made?

Because a repository is an answer with the question deleted. The code says what happens. It does not say what else was considered, what broke last time, or who has to be told before it changes.

Cursor has several ways to carry context, and all of them are aimed at instructions rather than history. Rules live in .cursor/rules as .mdc files, and Cursor also reads a plain AGENTS.md in the project root. Both are excellent for "always format imports this way". Neither is where you put a decision log, because a decision log grows every week, most of it is not about code, and half the people who need to write into it do not open the editor at all.

So the reasoning ends up in a vault, a wiki or a chat thread, and the agent with write access to your codebase has read access to none of it. Connecting Cursor to the vault closes that gap without turning your notes into a rules file.

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 file, 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.

How do I connect Cursor to Baalda over MCP?

1. Mint a vault token. In the Baalda desktop app, open Vault settings → MCP and create a token. It is scoped to one user and one vault and carries exactly that user's permissions.

2. Put the token in your shell environment, not in the config file. Cursor's envFile option only applies to stdio servers, so for a remote server the token has to come from the environment Cursor was launched in:

export BAALDA_MCP_TOKEN=mcp_your_token_here

3. Add Baalda to `mcp.json`. Use .cursor/mcp.json in a project root to scope it to one repo, or ~/.cursor/mcp.json to have it everywhere. Cursor resolves ${env:NAME} inside url and headers, among other fields:

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

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.

4. Turn it on and check. Open Customize in the sidebar, find the server, and make sure it is toggled on. If nothing appears, open the Output panel and select MCP Logs, which is where Cursor prints connection and auth failures. Baalda's MCP documentation has the endpoint details if a URL is not resolving.

Cursor asks for approval before it runs an MCP tool by default, and shows you the arguments before you accept. That default is worth keeping for the first week, because the first thing you learn is which of your notes the agent reaches for unprompted.

What can Cursor do once it can reach the vault?

The interesting jobs are the ones that were previously a tab switch and a copy-paste.

• Answer from the record instead of from the diff. search_notes is semantic and keyword search across the vault, and it covers text extracted from files as well as notes, so a PDF spec or an .xlsx of pricing tiers is searchable alongside the markdown. Each hit says whether it is a note or a file.
• Write the decision down while it is still fresh. When a refactor settles an argument, the agent can append the outcome to the decision log rather than leaving it in a chat scrollback nobody will search.
• Edit precisely rather than rewriting. edit_note takes anchored operations (replace, insert before, insert after, delete). An anchor that matches zero times or more than once refuses the whole call with nothing written, so a bad match fails loudly instead of quietly mangling a page.
• Refuse a stale write. read_note returns a revision. Pass it back as expectedRevision and a write against a note that somebody changed in between is refused rather than merged over the top.
• Land the change where people are already looking. The agent's writes flow through the same sync engine as human keystrokes, so a teammate with that note open watches the text appear instead of finding a conflicting copy tomorrow.

That last one is the difference between an agent that files things and an agent that quietly builds a second copy of your knowledge. More on why the shared file matters in what an MCP notes server actually gives an AI.

Should I just open the vault folder in Cursor instead?

If the vault is on the same machine, you can, and for a solo developer that is the better answer. Add the vault folder to the Cursor workspace, and the agent edits the .md files directly on disk. Baalda's file watcher picks up every change and syncs it to the team. There is nothing to configure and no token to mint.

Two things push you back toward MCP.

The first is Cursor's Cloud Agents, which do not run on your disk. Team admins distribute shared MCP servers from the Cursor dashboard under Plugins & MCPs, and those servers are available to Cloud Agents. A folder on your laptop is not. For that path the vault has to be reachable from outside your machine, which means the managed plan or a self-hosted server rather than localhost.

The second is scope. A folder in the workspace is all-or-nothing: everything in it is readable, and it competes for the agent's attention with your source. A token is bound to one user in one vault and every call it makes is gated by the same per-file permissions that user has. If the vault holds HR notes as well as engineering ones, that difference is the whole ballgame.

Where is Baalda the wrong choice here?

Worth being straight about this.

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

If you are one person and your notes are already an Obsidian vault on the same disk, stay there and add the folder to your workspace. Baalda starts earning its place at the point where more than one human needs to edit the same note at the same time, which is the specific thing a file-sync vault does not do.

And Baalda is not a code host. It does not index your repository, it has no opinion about your branches, and it will not replace anything Cursor already does well. It is the other half: the written record the repository assumes you have read.