Security

MCPBolt is designed around a simple security model: it edits files on your disk and nothing else. No account, no cloud, no telemetry. This page explains what that means in practice and what you need to think about when using it.

Write safety

Atomic writes

MCPBolt writes config files atomically. It prepares the new file content in memory, writes it to a temporary file, then renames the temporary file over the original. On POSIX systems, rename is atomic at the filesystem level — there is no window during which the file is partially written. If the process is killed mid-write, the original file remains intact.

Merge, never overwrite

MCPBolt reads the full existing config file before writing. It inserts or updates only the target server key and leaves all other keys exactly as they were. Your existing MCP servers, your other settings (for tools like Zed where MCP lives inside settings.json), and any comments (in TOML/YAML files) are preserved.

Backups

Before modifying any config file, MCPBolt writes a timestamped backup alongside it. The backup file is named with a .bak suffix:

~/.claude.json.bak

MCPBolt keeps the last three backups per file. When a fourth backup is created, the oldest is deleted. This rotation happens automatically — you don't need to manage backup files manually.

To restore a backup, copy it over the current config file:

cp ~/.claude.json.bak ~/.claude.json

Local-only operation

MCPBolt makes no outbound network requests except for health checks — and those go directly to your MCP servers (which you configured). There is no MCPBolt backend, no analytics endpoint, no crash reporting service. Nothing about your config, your server names, or your machine is transmitted anywhere.

You can verify this by running MCPBolt with a network monitoring tool (e.g. Little Snitch, lsof, or Wireshark) — the only outbound connections you'll see are your health checks.

Open source

MCPBolt is MIT licensed. The full source code is on GitHub:

https://github.com/vishmathpati/mcpbolt

Trust by inspection: read the code, build it from source, or verify the published npm package against the source. There are no binary blobs.

Secrets and environment variables

MCP server configs can include an env field (for stdio servers) or an auth header (for remote servers). MCPBolt writes whatever you provide into the config file as plaintext. This is the same behavior as any other tool that manages these files — the files themselves are your security boundary.

What MCPBolt does with secrets

• It writes the value you provide into the config file. That's it.
• It does not copy secrets off-disk, log them, or transmit them.
• It does not read values from your clipboard automatically.
• It does not store secrets in any MCPBolt-owned database or keychain.

How to handle secrets safely

The config files MCPBolt writes live on your home directory. They are readable by your user account and — if you share your machine or a project repo — potentially by others. Follow these practices:

• Use environment variable references. Instead of putting a literal secret in the config, reference an environment variable: "env": { "SUPABASE_TOKEN": "$SUPABASE_TOKEN" }. Set the actual value in your ~/.zshrc or ~/.bashrc (not in the config file).
• Don't commit project-scoped configs containing secrets. Add .mcp.json, .cursor/mcp.json, and similar project-scoped files to your .gitignore if they contain env values with real tokens.
• Use a secret manager for production. Tools like 1Password CLI, Vault, or macOS Keychain can inject secrets at runtime without storing them in plaintext files.

Reporting a vulnerability

If you find a security issue in MCPBolt, please report it via GitHub's private vulnerability reporting rather than opening a public issue:

Report a vulnerability