ShieldFive

@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):

   {

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

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

The version is pinned on purpose: the server can read your connection, so pin the release you reviewed and change the number when you choose to upgrade, instead of running whatever was published last.

1. Restart the assistant and ask it to *tidy up my ShieldFive vault*. It calls vault_connect, which opens ShieldFive in your browser.
2. 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@0.7.1 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@0.7.1 status shows which connection is configured and whether ShieldFive still accepts it. npx @shieldfive/mcp@0.7.1 logout removes it from the keychain and from the fallback file below. Revoking it in ShieldFive is what cuts off access everywhere.

Where no system keychain can be used (a Linux machine without a Secret Service, for example), the connection is saved instead to a file only your user account can read: ~/Library/Application Support/shieldfive-mcp/connection on macOS, %APPDATA%\shieldfive-mcp\connection on Windows, $XDG_CONFIG_HOME/shieldfive-mcp/connection (default ~/.config) on Linux, or $SHIELDFIVE_MCP_CONFIG_DIR/connection. The server says when it does this. The file is not encrypted, since any key for it would sit on the same disk; it is protected by file permissions (0600) like an SSH key. Without it, every restart would need a new connection, and ShieldFive caps how many can be live at once. A later successful keychain save deletes the file.

For CI, 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: /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.
• You approve destructive changes yourself, where your client can ask. For the tools marked destructive (vault_trash, vault_move_in, move_local, trash_local), a confirmed call first shows you the approved plan through MCP elicitation, in your client's own prompt, and goes ahead only if you accept. Declining changes nothing. A client without elicitation keeps the preview-and-token flow above.
• Listing is separate from reading contents. vault_list_files, vault_search_files and vault_storage_stats return names and metadata only. vault_read_file is the only tool that returns file contents, and vault_find_duplicates the only other one that decrypts them (it returns hashes). Start the server with --no-contents (or SHIELDFIVE_MCP_CONTENTS=off) and those two are not registered at all; a connection without the "read" permission is refused them too.

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 (or the 0600 fallback file the server writes when there is no 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@0.7.1 ~/Documents ~/Downloads

In claude_desktop_config.json:

{

"mcpServers": { "shield