Manage Secrets

MCPFirewall includes a local vault that encrypts all credentials with AES-256-GCM. Each secret has its own encryption nonce and a key derived from the master key using HKDF. Nothing is stored in plaintext.

Add a secret

On the Vault page, select a vault (or use the Default vault) and click Add Secret. Enter a name and the secret value. The value is encrypted immediately and never written to disk in plaintext.

You can also create secrets during the MCP install flow. When a server needs an API key, the install modal prompts for it and saves it to the vault automatically.

Use secrets in server configs

Secrets are referenced using the prefix:

$MCPFW_SECRET:secret_name

The gateway resolves these references at runtime, injecting the decrypted value into the server’s environment. Your config files never contain raw credentials.

Named vaults

Organize secrets into named vaults (like “Work”, “Personal”, “Testing”). All vaults use the same master encryption key. Vaults are purely organizational. Create them from the left panel on the Vault page, and move secrets between vaults as needed.

OAuth tokens

Some MCP servers use OAuth for authentication. MCPFirewall handles the full flow:

1. You click Authorize (during install or from the server card)
2. A browser window opens for the provider’s login
3. The token is stored encrypted in the vault
4. The gateway injects the token into requests automatically
5. Token refresh happens in the background when tokens expire

The Vault page shows each OAuth token with an expiry indicator: green (valid), yellow (expiring soon), red (expired). Click Re-authorize on an expired token to start a new flow.

Migrate plaintext credentials

If you had MCP servers configured before installing MCPFirewall, their API keys might be sitting as plaintext environment variables in config files. MCPFirewall can detect and migrate these.

On the MCP Hub page, servers with plaintext credentials show a migration prompt. Click Migrate to:

1. Store each credential in the vault
2. Rewrite the config file to use $MCPFW_SECRET: references
3. Back up the original config

Migration is safe to retry. If the vault write fails, the config file is not modified.

Back up your vault key

The master key lives at ~/.mcpfw/vault.key. If you lose this file, your secrets cannot be decrypted.

Export a backup from Settings (click Export Key) or from the CLI:

mcpfw vault export-key --out ~/vault-key-backup.txt

Store this somewhere safe and separate from your machine.

Transfer to another machine

To move your vault:

1. Export the key: mcpfw secrets export-key > key.txt
2. Copy ~/.mcpfw/mcpfw.db and key.txt to the new machine
3. Import the key: mcpfw secrets import-key $(cat key.txt)

Both the database and the key are needed. The database holds the encrypted secrets, the key decrypts them.