Projects

A project is a directory on your machine where you work (a git repo, a workspace, a monorepo). Projects let you apply different rulesets to different codebases automatically.

Projects are an Advanced Mode feature. In Simple Mode, governance applies globally.

Auto-detection

When an AI client starts a session in a directory, MCPFirewall detects it as a potential project. A notification appears in the dashboard: “New project detected: /path/to/project”.

Detected projects start as drafts. You can:

• Confirm: add it to your project list and assign a ruleset
• Reject: hide it (it will not be suggested again)

Draft projects appear in a separate section on the MCP Hub page.

Assigning rulesets

Each project can have one or more rulesets assigned. The default ruleset for the project is used when an AI client starts a session in that directory.

This means you can have a strict “Production” ruleset for ~/work/production-app and a permissive “Personal” ruleset for ~/personal/side-project, and the right one applies automatically based on where the AI is working.

How scoping works

When a tool call arrives, the gateway checks the AI client’s working directory against your project list using longest-prefix matching. A project at ~/work matches sessions in ~/work/app-a and ~/work/app-b.

You can also set a project ruleset from the CLI:

mcpfw ruleset apply "production" --dir ~/work/production-app

This creates a .mcpfw/ruleset file in the directory.

Project groups

Organize projects into named groups by dragging them on the MCP Hub page. Groups are collapsible and help manage many projects. An “Uncategorized” section holds ungrouped projects.

Sessions

A session represents an active AI client connection from a project directory. The MCP Hub shows a live indicator next to projects with active sessions, including a count of how many sessions are running.

Sessions are tracked in real time. When an AI client disconnects, the session ends.