Claude Code
Add WhyVault to Claude Code as a remote MCP server – one command, and Claude Code remembers your decisions across every project.
Requirements
- Claude Code: a current version with support for remote MCP servers over HTTP. Tested with 2.1;
claude updatebrings you up to date,claude --versionshows what you have. - Claude account: whatever you use Claude Code with – a Claude plan or an API account. WhyVault doesn't care which.
- WhyVault: any account, Free included.
- Choose how to sign in: an access key (works everywhere, including servers and containers) or OAuth in the browser (no key to handle).
Set it up
Add WhyVault
With an access key – the quickest way. Create a key in the app under Connect agents; the app then shows you exactly this command to copy:
claude mcp add --transport http --scope user whyvault https://mcp.whyvault.io --header "Authorization: Bearer wv_…"Or sign in in the browser, without a key:
claude mcp add --transport http --scope user whyvault https://mcp.whyvault.ioSign in (only without a key)
Then start Claude Code, type /mcp, pick whyvault and sign in in the browser – or run claude mcp login whyvault.
After approving, the browser shows that you can go back to the terminal. claude mcp list should now list whyvault as connected.
Try it
In any project, ask:
Read my WhyVault and tell me which decisions exist for this project.Claude Code calls vault_overview first, then searches specifically. Every change it makes appears in your WhyVault history under the connection's name.
With --scope user, WhyVault is available in all projects; without it, only in the current folder.
Scopes: where the connection applies
| Scope | Where it's stored | Good for |
|---|---|---|
user | your Claude Code settings | one memory across all projects – the usual case |
local (default) | your settings, for this folder only | trying it out in one project |
project | .mcp.json in the repository | sharing the setup with your team |
With project, never commit an access key. Use OAuth without --header – then everyone signs in with their own account – or reference an environment variable in .mcp.json, such as "Authorization": "Bearer ${WHYVAULT_KEY}".
WhyVault and CLAUDE.md
CLAUDE.md describes this repository: commands, conventions, architecture. WhyVault holds what lives beyond a single repository: why something was decided, what you tried and rejected, what applies to all your projects. Both work together. Add a few lines to your ~/.claude/CLAUDE.md so Claude Code uses the memory without being asked:
## Memory
- WhyVault (MCP server "whyvault") is my long-term memory across projects.
- Before larger changes, search WhyVault for earlier decisions on the topic.
- When we decide something with consequences, record it in the project's room in WhyVault.Troubleshooting
No browser window opens
On a server, in a container or over SSH there is often no browser. Use an access key instead: remove the entry with claude mcp remove whyvault and add it again with --header.
claude mcp list says the server needs authentication
You added WhyVault without a key and haven't signed in yet – or the sign-in expired. Start Claude Code, type /mcp, pick whyvault and sign in again.
The sign-in page can't return to the terminal
During sign-in, Claude Code waits for the browser on your own machine. Keep Claude Code open until the browser says you're done. If the browser runs on a different machine than Claude Code, use an access key.
WhyVault is missing in a project
You added it without --scope user, so it only applies in the folder where you ran the command. Check with claude mcp list inside the project and add it again with --scope user.
Error 401 with an access key
The key was revoked, mistyped or is incomplete. Keys are shown only once – create a new one under Connect agents and copy the command again. The header must read Authorization: Bearer wv_….
Write tools are missing
The key or connection is set to read only. Change it under Connect agents → Permissions, then start a new Claude Code session – it loads the tool list on start.
"Too many changes in a short time"
WhyVault slows down a connection that writes an unusual amount per minute. Ask Claude Code to combine its notes instead of writing many small changes.
FAQ
One vault for all my projects?
Yes. Each project gets its own room in 3_Rooms/, and knowledge that applies everywhere lives in 1_Knowledge/. See the structure.
Can Claude Code only read?
Yes. Tick Read only when you create the key, or change the permissions later.
Does it slow Claude Code down?
No. Claude Code only calls the tools when it needs context, and WhyVault answers with short, targeted results instead of whole folders.
What if I use Claude on the web too?
Connect Claude as a custom connector. Both read and write the same notes.