How to set up Keyfold's MCP server in Claude Code

With Keyfold open and unlocked, one command connects it to Claude Code: claude mcp add --scope user keyfold -- keyfold mcp. From then on, Claude can list your projects and key names, run your tests with the right keys injected, write a .env file you asked for, and save a key it just created. Every request appears in the Keyfold window first, and nothing happens until you click (or until you've allowed that project and environment for an hour).

This post is the setup, step by step: the command and its options, what the first approval looks like, the permission rules I'd use in Claude Code, and what to tell Claude so it uses the tools well. If you want the reasons behind this design first, how to let Claude Code use an API key without seeing it covers them.

What do you need before you start?

Three things:

1. Keyfold on your Mac, open and unlocked. The Mac app is on the download page, and the Windows app is coming through the Microsoft Store. The MCP server talks to the running app over a private local socket, so it can't do anything while the app is closed or locked.
2. The keyfold command. From version 1.0.1 it's inside the Mac app, at /Applications/Keyfold.app/Contents/MacOS/keyfold. To put it on your PATH, open Settings › General › Command line and MCP in Keyfold and click Install. That links /usr/local/bin/keyfold to it, and macOS may ask for an administrator password if that folder isn't writable. It's also open source, so you can build it from github.com/codewithkolin/keyfold with cargo build --release -p keyfold-cli.
3. Claude Code.

Check that your terminal finds the command:

$ keyfold --help
Keyfold: offline secrets vault, command line
 
Usage: keyfold <COMMAND>
 
Commands:
  projects        List projects and environments
  names           List secret names in an environment (never values)
  env             Write an environment to a .env file (or print with --stdout)
  run             Run a command with the environment's secrets injected as variables
  create-project  Create a project (default environments: development, production)
  import          Import a .env file into an environment (creates project and environment if missing)
  mcp             Start the MCP server on stdin/stdout (for Cursor, Claude Code, etc.)
  help            Print this message or the help of the given subcommand(s)
 
Options:
  -h, --help     Print help
  -V, --version  Print version

If you get command not found, click Install in that setting, or use the full path, /Applications/Keyfold.app/Contents/MacOS/keyfold, wherever this post says keyfold.

You also need a project with keys in it. If your keys are still in a .env file, the import command moves them into a project and environment, creating both if they don't exist yet. Keyfold asks you to approve the import, then you can delete the plain file:

$ keyfold import -p acme-api -e development -f .env

Step 1: Add the server to Claude Code

$ claude mcp add --scope user keyfold -- keyfold mcp

Everything after -- is the command Claude Code starts: keyfold mcp, which speaks MCP over standard input and output. The --scope flag decides where the setting lives. Claude Code's MCP docs list three scopes:

I'd pick user, because one vault serves all your projects. project is fine too: Keyfold's entry holds no key, only the command to start the server, so committing .mcp.json doesn't leak anything. Your teammates still need Keyfold and their own keys. That's a real difference from servers whose setup puts an API key in the config. GitGuardian's State of Secrets Sprawl 2026 found 24,008 unique secrets in MCP configuration files on public GitHub.

To check that Claude Code can start the server, run claude mcp get keyfold, or type /mcp inside a session: Keyfold should show as connected, with 7 tools.

Step 2: Make a first request

Start Claude Code in a project and ask something that only needs names:

Which projects do I have in Keyfold?

Claude calls keyfold_projects. Claude Code may ask you to allow the tool call first. Then the Keyfold window comes to the front with its approval sheet, titled "An AI agent is asking Keyfold". It says keyfold-mcp, with its process id, wants to "list your project and environment names", and adds "Names only. No secret values leave Keyfold for this request." Click Allow once. (A list of projects isn't tied to one project, so this request has no "Allow for 1 hour" button.)

Claude gets back a short text with this shape, straight from the server's code:

acme-api
  - development (4 secrets)
  - production (2 secrets)

That's all it can learn this way: names and counts.

Step 3: Run something that needs keys

Now ask for real work:

Run the tests for acme-api with the development keys from Keyfold.

Claude calls keyfold_run with the project, the environment and a command such as npm test. Two things happen before the tests start:

1. Claude Code asks you to allow the tool call, unless you've allowed this tool. Its prompt shows the call, including the command. This is the first place you see what will run.
2. Keyfold asks you to hand over the keys. The sheet says keyfold-mcp wants to "read every secret in acme-api / development". Under that it says "It will run this command with them:" and shows npm test. Then it warns: "This hands every value in acme-api / development to that process. The MCP server writes them to a file or into a command; the AI model does not receive them, but anything the command prints will reach it."

Keyfold's sheet names the client, the project, the environment and the command, so you read the command a second time before any key leaves the vault.

When you click Allow once, the MCP server, a process on your Mac, starts the command through sh -c with every key in that environment set as an environment variable. Claude gets back the exit code and the command's output, cut off at 20 KB.

▶ Open the approval sheet in the live demoOpens the live demo, with made-up keys

Because the command runs in a shell with the keys set, a command like echo $STRIPE_KEY would print the key into the conversation. No Keyfold tool returns a secret value; a command you let run can still print one. That's the reason to read the command before you allow it.

Step 4: Choose what Claude Code may call without asking

Claude Code's permission rules can name MCP tools as mcp__<server>__<tool>. Here is what I put in ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__keyfold__keyfold_projects",
      "mcp__keyfold__keyfold_secret_names"
    ],
    "ask": [
      "mcp__keyfold__keyfold_run",
      "mcp__keyfold__keyfold_write_env"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

• Allow the two tools that only return names. Keyfold still asks you in its own window, so allowing them in Claude Code only removes a duplicate prompt.
• Ask for keyfold_run and keyfold_write_env, the two that hand values to a process. An ask rule makes Claude Code prompt every time, even if you once clicked an option that stops asking. Keyfold's sheet shows the command or the file path too, but under a one-hour grant Keyfold doesn't ask again. This prompt still does.
• Deny reads of .env files. If you approve keyfold_write_env, the file it writes is a plain-text file on disk, and these rules stop Claude from reading it back. They cover Claude's file tools and common commands like cat, not every way a program can open a file, so turn on Claude Code's sandboxing as well.

The other three tools (keyfold_store, keyfold_create_project, keyfold_import_env) write into your vault. Leave them on Claude Code's default behaviour; Keyfold asks before each one anyway.

Step 5: Tell Claude how to use it

The server introduces itself when Claude Code connects. Its instructions say: "Use keyfold_projects to discover names, keyfold_write_env or keyfold_run to use secrets without reading them, and keyfold_store to save new ones. Every call is approved by the user inside the Keyfold app; if a call is denied or Keyfold is locked, tell the user and stop."

What it can't know is your project's names and rules. Put those in the project's CLAUDE.md:

## Secrets
- Keys for this repo are in Keyfold: project `acme-api`, environments `development` and `production`.
- To run tests or scripts that need keys, use the `keyfold_run` tool with the `development` environment. Never use `production` unless I ask.
- Never read `.env` files, run `printenv` or `env`, or print the value of a key.
- If you create an API key, save it with `keyfold_store` and don't repeat its value afterwards.

One thing about keyfold_store: it saves a value that Claude already has, such as a key it just generated or one you pasted into the chat. The value is in the conversation by then. Storing it keeps it out of your files from then on; it doesn't remove it from the chat. For a .env file that's already on disk, keyfold_import_env is better: the MCP server reads the file itself, so the values never pass through the model.

What if something doesn't work?

Claude relays Keyfold's answers, so the message usually tells you what to do:

If /mcp shows the server as failed, Claude Code couldn't start keyfold mcp. The usual cause is that keyfold isn't on the PATH Claude Code sees. Remove the server and add it again with the full path:

$ claude mcp remove keyfold
$ claude mcp add --scope user keyfold -- /Applications/Keyfold.app/Contents/MacOS/keyfold mcp

The security page explains how the vault and this agent connection are built, and the features section shows what else Keyfold does with the same keys, such as quick paste and .env export.

FAQ

Can Claude see my API keys through this server?

No tool returns a value: Claude gets names, counts, confirmations, exit codes and command output. A command you let run can still print a key, which is why the command is worth reading before you allow it.

Do I need to approve every request?

Yes, in Keyfold, unless you chose "Allow for 1 hour" for that project and environment. In Claude Code, the permission rules from step 4 decide which tool calls also ask there.

Does this work in more than one project?

Yes. With --scope user, the server is available in every project you open in Claude Code. Each request names the Keyfold project and environment it wants.

Can I share the setup with my team?

Use --scope project, which writes a .mcp.json you can commit. It contains only the command to start the server, no key. Each teammate needs Keyfold with their own keys; Keyfold has no shared vaults or sync yet.

Is the MCP server open source?

Yes. The CLI and MCP server are AGPL-licensed at github.com/codewithkolin/keyfold, along with the encryption and vault format. The desktop app's interface is not open source.