MCP Gatekeeper

A policy-enforced MCP server with approval workflows, risk classification, and audit logging.

Built for the Manufact (mcp-use) Hackathon at Y Combinator, Feb 2026.

What It Does

MCP Gatekeeper wraps "dangerous" tools (file read/write/delete, shell exec) with a policy engine that classifies every action by risk level and enforces approval workflows:

Tool	Risk Level	Behavior
read_file	SAFE	Executes immediately
write_file	SENSITIVE	Requires approval before execution
delete_file	DANGEROUS	Blocked by default, can be approved
run_shell	DANGEROUS	Always blocked, never approvable

All file operations are sandboxed to ./sandbox/ with path traversal protection.

Key Features

• Policy engine with configurable risk levels (edit policy.json)
• Approval queue - pending actions with approve/deny workflow
• Audit log - every action and decision is recorded
• Sandbox - filesystem operations restricted to ./sandbox/
• HTML Dashboard - embedded MCP App UI with risk badges
• 12 MCP tools exposed for full workflow control

Quick Start

# Install dependencies
pip install fastmcp mcp-use

# Run the server
python server.py

Git Safety (Recommended)

This repo includes a .gitignore and an optional pre-commit hook to prevent accidentally committing node_modules/, __pycache__/, .env*, and *.log.

./scripts/setup-githooks.sh

How to Test

Option 1: mcp-use Inspector (Recommended)

Go to the Manufact Inspector and connect with:

• Transport: stdio
• Command: python
• Args: server.py
• Working directory: path to this project

Or use the local inspector:

pip install fastmcp
fastmcp dev server.py

Option 2: Automated Demo Script (mcp-use)

pip install mcp-use
python test_demo.py

This runs through the full workflow automatically using mcp-use's MCPClient.

Option 3: Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gatekeeper": {
      "command": "python",
      "args": ["/full/path/to/server.py"]
    }
  }
}

Demo Script (step by step)

Run these tool calls in order in the Inspector to see the full flow:

1. get_policy()
   → See risk levels for all tools

2. read_file(path="test.txt")
   → SAFE: auto-executes (file not found, that's OK)

3. write_file(path="hello.txt", content="Hello Hackathon!")
   → SENSITIVE: returns APPROVAL_REQUIRED + action_id

4. list_pending()
   → Shows the pending write action

5. approve(action_id="<id from step 3>")
   → Executes the write, file is created

6. read_file(path="hello.txt")
   → SAFE: reads "Hello Hackathon!"

7. delete_file(path="hello.txt")
   → DANGEROUS: returns APPROVAL_REQUIRED + action_id

8. deny(action_id="<id from step 7>")
   → Denies the delete, file is preserved

9. run_shell(command="ls -la")
   → DANGEROUS: BLOCKED permanently

10. read_file(path="../../etc/passwd")
    → BLOCKED: path traversal detected

11. audit_log()
    → Full history of all actions and decisions

12. get_dashboard()
    → Formatted overview of everything

13. get_dashboard_ui()
    → HTML widget with risk badges, pending queue, audit table

Tools Reference

Tool	Description
read_file(path)	Read a file from sandbox
write_file(path, content)	Write a file (needs approval)
delete_file(path)	Delete a file (needs approval)
run_shell(command)	Shell exec (always blocked)
list_pending()	Show pending approval queue
approve(action_id)	Approve and execute a pending action
deny(action_id)	Deny a pending action
audit_log(limit=25)	View decision history
get_policy()	View current policy config
get_dashboard()	Text dashboard overview
get_dashboard_ui()	HTML dashboard (MCP App UI)

Project Structure

mcp-quick/
├── server.py          # MCP server (FastMCP) - all tools + policy engine
├── policy.json        # Configurable policy rules
├── mcp_config.json    # mcp-use client configuration
├── test_demo.py       # Automated demo using mcp-use MCPClient
├── requirements.txt   # Python dependencies
├── README.md          # This file
└── sandbox/           # Sandboxed filesystem (all ops happen here)

Customizing Policy

Edit policy.json to change behavior:

{
  "write_file": {
    "risk_level": "SAFE",
    "default_action": "allow",
    "allow_approval": false
  }
}

• risk_level: SAFE | SENSITIVE | DANGEROUS
• default_action: allow | require_approval | block
• allow_approval: true | false (can users approve blocked actions?)

Tech Stack

• Server: FastMCP (official MCP Python SDK)
• Client/Testing: mcp-use (Manufact SDK)
• Transport: stdio (local, no network)
• State: In-memory (dicts/lists)
• UI: Self-contained HTML (MCP App compatible)