# Set up Brain Dump for your user

You are an AI agent. Your user wants you connected to Brain Dump, their company brain, so you can search their notes
and save thoughts for them. Do every step below in order, without asking the user to do anything you can do
yourself. The human page is https://getbraindump.app/agents.

- MCP server: `https://getbraindump.app/mcp` (remote, Streamable HTTP, sign-in with OAuth)
- Tools: `search`, `fetch`, `search_knowledge`, `get_entity_context`, `dump_thought`, `import_notes`, `add_action`,
  `list_actions`, `update_action`, `delete_action`, `list_open_actions`, `resolve_todo`

There is no key to copy. The user signs in to Brain Dump once in their browser and picks what you may reach (read only
or read and write, and which spaces). Remote MCP needs a paid plan.

## 1. Add the MCP server to your own client

Work out which client you are running in, and do only that one.

### Claude Code

```sh
claude mcp add --transport http --scope user braindump https://getbraindump.app/mcp
```

`--scope user` makes it available in every project. Then tell the user, in these words: "Type `/mcp`, pick
**braindump**, choose **Authenticate**, and approve Brain Dump in the browser window that opens." A new session may be
needed before the tools appear.

### Codex

```sh
codex mcp add braindump --url https://getbraindump.app/mcp
codex mcp login braindump
```

The second command opens the Brain Dump approval page in the browser. Tell the user to approve it. Check with
`codex mcp list`.

### Cursor

Merge this into `~/.cursor/mcp.json` (all projects). Keep any servers already there.

```json
{
  "mcpServers": {
    "braindump": {
      "url": "https://getbraindump.app/mcp"
    }
  }
}
```

Then tell the user: "Open Cursor Settings → MCP, find **braindump**, click **Needs login** (or **Connect**), and approve
Brain Dump in the browser."

### Claude (desktop, web or mobile app) and ChatGPT

You cannot change these apps yourself. Give the user these steps:

- Claude: **Customize → Connectors → Add custom connector**. URL `https://getbraindump.app/mcp`, then **Add** and
  **Connect**, and approve Brain Dump. On Team and Enterprise plans an owner adds it first under **Organization
  settings → Connectors**; members then click **Connect** on it.
- ChatGPT: **Settings → Apps & Connectors → Advanced settings**, turn on **Developer Mode** (once). Back in **Apps &
  Connectors**, click **Create**: name `Brain Dump`, URL `https://getbraindump.app/mcp`, authentication **OAuth**,
  then approve Brain Dump when asked and click **Create**. In a chat, pick it from **+ → More**. ChatGPT uses the
  `search` and `fetch` tools for deep research.

### Any other MCP client

Use the URL `https://getbraindump.app/mcp`. If the client supports OAuth for remote servers, that is all; it finds
the sign-in page by itself. If it does not, see "Clients without sign-in" at the end.

## 2. Install the skills

Two skills teach you to use Brain Dump well: `braindump` (search, save, open actions) and `braindump-import` (bulk
import of a markdown folder or Obsidian vault). Download both into your client's skills folder:

| Client | Skills folder |
|---|---|
| Claude Code | `~/.claude/skills` |
| Cursor | `~/.cursor/skills` |
| Codex | `~/.agents/skills` |

```sh
SKILLS=~/.claude/skills   # or ~/.cursor/skills, or ~/.agents/skills
for s in braindump braindump-import; do
  curl -fsSL --create-dirs -o "$SKILLS/$s/SKILL.md" "https://getbraindump.app/agent-kit/skills/$s/SKILL.md"
done
```

Clients without skills: read https://getbraindump.app/agent-kit/skills/braindump/SKILL.md and follow it.

## 3. Verify

Once the user has approved, call `search_knowledge` with `{"query": "meeting"}` (or any word their notes are likely
to contain).

- Results, or an empty list: you are connected. Tell the user, and say whether you can save (read and write) or only
  read.
- The client says it needs authentication, or the call is refused as unauthorized: the user has not approved yet, or
  removed the connection. Ask them to sign in again (step 1).
- A tool error that says "read_write" is needed: the user approved read only. They can sign in again and pick read
  and write.
- 429: wait the `Retry-After` seconds and try once more.

Then tell the user what you can do now: answer questions from their notes, save decisions and to-dos, list and close
open actions, and import a notes folder. Each sign-in shows up in Brain Dump under Settings → Remote MCP, where the
user can remove it at any time.

## Clients without sign-in

Only if the client cannot do OAuth: ask the user to create a key in https://getbraindump.app/settings → **Remote
MCP**. You cannot create one, and you must never invent one. The key starts with `bd_mcp_` and is shown once.

- Never print it back, repeat it in chat, write it into a repository, or put it anywhere but the client config.
- Best: the user sets it in their own terminal, so it never passes through you: `read -rs BRAINDUMP_KEY && export BRAINDUMP_KEY`
  (typed hidden, kept out of shell history). On macOS they can keep it in the Keychain with
  `security add-generic-password -a "$USER" -s braindump -w` and add
  `export BRAINDUMP_KEY="$(security find-generic-password -a "$USER" -s braindump -w)"` to the shell profile.

Then, instead of step 1:

```sh
claude mcp add --transport http --scope user braindump https://getbraindump.app/mcp --header "Authorization: Bearer ${BRAINDUMP_KEY:?set BRAINDUMP_KEY first}"
```

```sh
codex mcp add braindump --url https://getbraindump.app/mcp --bearer-token-env-var BRAINDUMP_KEY
```

```json
{
  "mcpServers": {
    "braindump": {
      "url": "https://getbraindump.app/mcp",
      "headers": { "Authorization": "Bearer ${env:BRAINDUMP_KEY}" }
    }
  }
}
```

Other clients: send the header `Authorization: Bearer <the key>` with every request.
