CLI Commands

The mcpfw binary is the single entry point for the gateway, shim, service management, and administrative tasks. All commands operate against the local database at ~/.mcpfw/.

mcpfw serve

Start the gateway. This is the default command (running mcpfw with no arguments does the same thing).

mcpfw serve [flags]

Flag	Default	Description
--port	8765	Port to listen on
--bind-addr	127.0.0.1	Bind address (0.0.0.0 on WSL2)
--no-browser	false	Do not open the dashboard in a browser
--no-tray	false	Do not start the tray helper
--version		Print version and exit

mcpfw shim

Stdio bridge between an AI client and the gateway. Not typically run manually. AI client configs are rewritten to use this command.

mcpfw shim --server <id>

Flag	Description
--server	Server ID (or set MCPFW_SERVER_ID)
--version	Print version to stderr and exit

Shim auth (team tier)

mcpfw shim auth set-token --url <gateway-url> --token <token>
mcpfw shim auth get-token
mcpfw shim auth clear-token

mcpfw status

Check if the gateway is running. Returns exit code 0 if healthy, 1 if not.

mcpfw status

mcpfw service

Manage the gateway as a login service.

mcpfw service <subcommand>

Subcommand	Description
install	Register as a login service
uninstall	Remove the service
start	Start the service
stop	Stop the service
restart	Restart the service
status	Show service and gateway status (--json for machine output)
logs	Tail the gateway log (--n 50 to set line count)

mcpfw doctor

Run diagnostic health checks. Returns exit code 0 if all pass, 1 if any warn or fail.

mcpfw doctor [--json]

Checks: gateway connectivity, database integrity, vault key, server registrations, client configs.

mcpfw logs

View logs for a specific server.

mcpfw logs <server-name> [--follow]

The --follow flag polls for new lines every 500ms.

mcpfw ruleset

Manage governance rulesets.

Subcommand	Description
list	List all rulesets
create <name>	Create a new ruleset
apply <name>	Write .mcpfw/ruleset to a directory (--dir to specify)
export <name>	Print ruleset as JSON to stdout
import	Read JSON from stdin and create a ruleset

mcpfw ruleset create "strict"
mcpfw ruleset apply "strict" --dir ~/projects/myapp
mcpfw ruleset export "strict" > strict.json
cat strict.json | mcpfw ruleset import

mcpfw secrets

Vault encryption key management.

Subcommand	Description
export-key	Print the vault key in base64
import-key <base64>	Import a vault key

mcpfw vault

mcpfw vault export-key --out <path>

Export the vault key to a file. The --out flag is required.

mcpfw oauth

mcpfw oauth revoke <server-name>

Delete a stored OAuth token locally. No revocation request is sent to the provider.

mcpfw tui

Start the terminal UI dashboard. Automatically starts the gateway if not running.

mcpfw tui

mcpfw registry

mcpfw registry classify [--force] [--llm]

Classify registry entries by category. --force reclassifies all entries. --llm runs an LLM correction pass.

mcpfw guard

Start an inbound MCP governance proxy. Protects an upstream MCP server with rate limiting, IP filtering, and MCPA compliance.

mcpfw guard --upstream <url> [flags]

Flag	Default	Description
--upstream	required	Upstream MCP server URL
--port	8766	Listen port
--rate	100/min	Rate limit (N/min or N/s)
--burst	20	Rate limit burst capacity
--domain		Domain for automatic HTTPS (Let’s Encrypt)
--cert		TLS certificate file (PEM)
--key		TLS private key file (PEM)
--github-client-id		GitHub OAuth client ID
--github-client-secret		GitHub OAuth client secret
--google-client-id		Google OAuth client ID
--google-client-secret		Google OAuth client secret
--allow		Allow CIDR (repeatable)
--deny		Deny CIDR (repeatable)

TLS modes

Automatic HTTPS: use --domain for Let’s Encrypt (requires ports 80 and 443):

mcpfw guard --upstream http://localhost:3000 --domain mcp.example.com

Bring your own cert: use --cert and --key:

mcpfw guard --upstream http://localhost:3000 --cert cert.pem --key key.pem

Plain HTTP: omit TLS flags (localhost or behind a reverse proxy):

mcpfw guard --upstream http://localhost:3000

Key rotation

mcpfw guard rotate-key

Rotate the MCPA signing key used for receipt chain signatures.