Data Directory

MCPFirewall stores all its data in ~/.mcpfw/. This directory is created automatically on first run.

Files

File	Description
mcpfw.db	SQLite database. Configuration, servers, rulesets, audit log, secrets (encrypted), OAuth tokens (encrypted).
vault.key	Vault master encryption key. If lost, secrets cannot be decrypted. Back this up.
mcpfw.log	Gateway log. Rotates at 10 MB, keeps 2 backups.
gateway.sock	Unix domain socket for shim-to-gateway communication. Owner-only permissions (0600).
bypass.log	Events logged during bypass mode (when the gateway is unreachable and the shim falls back to direct connection).
guard-signing.pem	ECDSA signing key for MCPA receipts (created by mcpfw guard).

Directories

Directory	Description
logs/	Per-server rotating log files, named by server ID.
certs/	Let’s Encrypt certificate cache (created by mcpfw guard --domain).
integrations/	Auto-saved client integration descriptors.
cache/logos/	Cached server favicons from the registry.

Project-scoped files

The .mcpfw/ruleset file can be created in any project directory to bind that directory to a specific ruleset. This file is created by mcpfw ruleset apply.

Permissions

The data directory and sensitive files are created with restrictive permissions:

• Directory: 0700 (owner only)
• vault.key: 0600 (owner read/write only)
• gateway.sock: 0600 (owner read/write only)

On Linux, the Unix socket prefers $XDG_RUNTIME_DIR/mcpfw/gateway.sock when available. This directory is automatically cleaned up on logout.

Backup

To back up MCPFirewall, copy:

1. ~/.mcpfw/mcpfw.db (the database with all configuration and encrypted secrets)
2. ~/.mcpfw/vault.key (the encryption key)

Both are needed. The database without the key has only encrypted blobs. The key without the database has nothing to decrypt.