Quick Start (CLI)

This page is for CLI installations. If you installed the desktop app, see Quick Start.

Start the gateway

mcpfw serve

The dashboard opens in your browser at http://localhost:8765. The gateway runs in the foreground. Press Ctrl+C to stop it.

To run it as a background service that starts automatically on login:

mcpfw service install
mcpfw service start

On macOS this creates a LaunchAgent, on Linux a systemd user unit. Check the status anytime:

mcpfw service status

Pick your mode

On first launch, the dashboard asks you to choose between Simple Mode (streamlined, focused on servers and secrets) and Advanced Mode (full governance with rulesets, per-tool overrides, and project scoping).

Pick whichever fits. Switch anytime in Settings.

Connect your AI client

Go to the Integrations page in the dashboard. MCPFirewall auto-detects installed AI clients:

Claude Desktop
Claude Code
Cursor
VS Code (Copilot)
Windsurf
Cline

Click Set up on any detected client. MCPFirewall rewrites the client’s MCP configuration to route through the gateway. The original config is backed up as a .bak file.

Restart your AI client after setup. Config changes only take effect after a restart.

Install your first MCP server

Go to the Discover page. Search for a server (try “filesystem” or “github”) and click Connect.

The install flow handles credentials (stored encrypted in the vault), OAuth (if needed), and writes the server config to all connected clients.

The server appears on the MCP Hub page under Protected Servers.

Restart your AI client to pick up the new server. New MCP servers are not visible until the client restarts.

Verify

After restarting your AI client, use a tool. Check the dashboard:

Monitor shows the tool call in the activity feed
MCP Hub shows live server status

Or verify from the terminal:

mcpfw status          # check gateway is running
mcpfw doctor          # run full health check
mcpfw logs <server>   # view a specific server's logs