MCP Gatekeeper

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: ``bash 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)