@shieldfive/mcp

A Model Context Protocol server that lets Claude, ChatGPT, Cursor or a local model work with two things:

• your ShieldFive vault, end-to-end encrypted: move files off your computer into it — each one encrypted here, uploaded, read back and matched byte for byte before its original is moved to a local trash folder, never deleted — and find duplicates, see what takes the space, rename, move and move to the Bin. It works on the folders you grant, decrypts on your machine, and every change can be undone;
• folders on your own disk: the same tidying jobs, with no network access at all.

ShieldFive's servers never see a file name or a byte of content in the clear, and that holds with this server running too. Decryption happens inside this process, on your computer. What the assistant then does with what it reads is a separate question, answered under Security model.

Connect your vault in 60 seconds

Requires Node 20 or newer.

1. Add the server to your assistant. For Claude Desktop, add this to claude_desktop_config.json (Cursor uses the same block in ~/.cursor/mcp.json):

   config.json

   Copy

   {
     "mcpServers": {
       "shieldfive": { "command": "npx", "args": ["-y", "@shieldfive/mcp"] }
     }
   }
   

   For Claude Code: claude mcp add shieldfive -- npx -y @shieldfive/mcp

2. Restart the assistant and ask it to tidy up my ShieldFive vault. It calls vault_connect, which opens ShieldFive in your browser.

3. In that tab, choose the folders, Read only or Read and organize, and an expiry (1 hour to 90 days), then click Authorize.

That is the whole setup: the connection is delivered straight to the server running on your computer — over 127.0.0.1, never through ShieldFive — and stored in your system keychain. Nothing is copied by hand.

To connect before you start a conversation, run npx -y @shieldfive/mcp login: same browser page, same result. login --paste takes a connection string you copied from Settings → AI assistants instead, for a machine with no browser.

npx @shieldfive/mcp status shows which connection is configured and whether ShieldFive still accepts it. npx @shieldfive/mcp logout removes it from the keychain. Revoking it in ShieldFive is what cuts off access everywhere.

For CI or a machine without a keychain, set SHIELDFIVE_GRANT to the connection string instead. Anything that can read the server's environment can then read the connection, so prefer the keychain wherever there is one. Setting SHIELDFIVE_GRANT=none keeps one client local-only on a machine whose keychain holds a connection for another.

How the browser hand-off is kept honest

• The page never accepts a callback URL, only a port number, and builds http://127.0.0.1:<port>/callback itself. A crafted link cannot send your connection anywhere but your own machine.
• The listener accepts exactly one delivery: a POST to /callback, Host exactly the loopback address (so a rebound DNS name is refused), no Origin but ShieldFive's, and a 256-bit state compared in constant time. Then it closes.
• The connection string travels in a form body, never in a URL, so it does not land in browser history.
• The listener exists only while a connection is being authorized, and for at most 10 minutes.

Security model

In plain terms:

• The connection string holds two things. A token the server checks on every request, and a secret that never leaves your machine. ShieldFive stores only a hash of the token and has never seen the secret.
• The secret opens only the folders you chose. When you create a connection, your browser wraps those folders' keys under a key derived from the secret. It wraps nothing else: not your vault root key, not your password, not your post-quantum secret key. Subfolders open through the vault's normal folder-key chain. A folder you did not choose cannot be opened with anything this server holds.
• ShieldFive enforces scope, expiry and revocation on every request. The checks in this process only produce clearer errors; the server is the boundary. Revoking a connection makes its next request fail. Nothing is cached that would outlive a revocation.
• Decryption happens here, in memory. No plaintext, key or ciphertext is written to disk. The vault modules do not import the filesystem, and a test asserts that.
• Nothing is deleted. vault_trash moves items into a folder in your Bin that belongs to the connection. There is no permanent-delete tool, and the API a connection can reach has no delete route. Every rename, move and trash appears in Settings → AI assistants → Activity with an Undo button.
• Every change is previewed first. Mutating tools report a plan, and the confirmed call must carry that plan's token and is refused if the items changed in between.

What this does not protect:

• Your AI provider sees what the assistant reads. File names, and the contents of files the assistant opens, go to the assistant, and for a cloud assistant that means to its provider, like the rest of your conversation. The only way to avoid that is a local model.
• Revoking cannot un-read. Anything the assistant has already read stays read. Nothing else survives it: file contents are streamed through ShieldFive on each request, so there is no download link to outlive a revocation.
• A connection is built from what the server shows your browser when you create it. Every later extension is checked against your own keys, so a compromised server cannot widen a connection afterwards. At the moment of creation, though, a compromised server could mislabel which folder you picked.
• A copied connection string is a live key to the folders it covers until it expires or you revoke it. Keep it in the keychain.
• Files can contain instructions aimed at the assistant. This server marks every name and file content as data, fences file contents in a block the file cannot close, caps vault_trash at 50 items per call, requires a preview for every change, and keeps every change undoable. A model can still be talked into a reversible mistake inside the folders you granted.

The full design, including the threat model and the reasoning behind each decision, is in docs/mcp-grants-design.md.

Vault tools

vault_connect is always available. The rest are registered once a connection exists — connecting mid-conversation announces them with notifications/tools/list_changed. Everything below names things by id; paths are for people.

Limits a user may meet:

• Post-quantum files uploaded from a phone or the CLI show as readable: false until you next open ShieldFive on the web, which adds the key the connection needs. Files uploaded in the web app are ready straight away.
• The first listing of a large vault takes a while. Each name costs about 70 ms of Argon2id, spread over your CPU cores (about 20 seconds for 2,000 names on 8 cores). Names are cached in memory for the rest of the session.
• Items at the very top of a whole-vault connection can be read and moved into a folder, but not renamed in place, and nothing can be moved to the top. Their names are sealed under your vault root key, which a connection never holds.
• Uploads need a connection that may add files ("Read, organize and add files" when you authorize it) and an upload allowance, which you choose then. Each file is at most 512 MB. Uploads and moves read local files, so the server needs roots as well as a connection.
• Moving files in frees no space by itself. vault_move_in puts each verified original in .shieldfive-mcp-trash, with a manifest naming its vault copy; the space comes back when you empty that directory.

Local files

Every path after the package name is a root. The local tools can read and write inside those directories and nowhere else, and make no network request.

npx @shieldfive/mcp ~/Documents ~/Downloads

In claude_desktop_config.json: