mcp-guard

A simple HTTP proxy that gates MCP servers with block rules.

No SDKs. No dashboards. Just a JSON config and a toggle command.

Client (Claude, Cursor, etc.)
    ↕ http
mcp-guard (localhost proxy)
    ↕ http
Upstream MCP server (supabase, postgres, etc.)

Quick Start

1. Install

npm install -g @alramalho/mcp-guard

Or from source:

git clone https://github.com/alramalho/mcp-guard
cd mcp-guard
pnpm install && pnpm build && npm link --force

2. Create .mcp-guard.json

In your project root (or ~/.mcp-guard.json globally). Config is auto-discovered by walking up from cwd.

{
  "port": 6427,
  "servers": {
    "supabase_production": {
      "url": "https://mcp.supabase.com/mcp?project_ref=xxx&read_only=true",
      "block": ["DELETE", "UPDATE", "DROP", "TRUNCATE", "ALTER", "INSERT"],
      "blockMessage": "Destructive SQL operations are not allowed in production"
    }
  }
}

3. Update your mcp.json

Replace the direct upstream URL with the mcp-guard proxy:

{
  "mcpServers": {
    "supabase_production": {
      "type": "http",
      "url": "http://localhost:6427/supabase_production"
    }
  }
}

4. Toggle on/off

$ mcp-guard
MCP Guard on → http://localhost:6427

$ mcp-guard
MCP Guard off

Debug mode

Run in foreground to see all tool calls and block decisions live:

$ mcp-guard -d

Config

.mcp-guard.json (auto-discovered from cwd up, or ~/.mcp-guard.json, or --config <path>):

Each server:

Authentication

mcp-guard handles OAuth-protected upstream servers (e.g. Supabase) automatically. On first connection, if the upstream requires auth, mcp-guard will open your browser for OAuth authorization. Tokens are cached in ~/.mcp-guard/auth/ and refreshed automatically.

Alternatively, you can provide a static token in the config:

{
  "servers": {
    "my_server": {
      "url": "https://example.com/mcp",
      "token": "your-access-token"
    }
  }
}

How It Works

1. mcp-guard starts a local HTTP server

2. When a client connects to http://localhost:PORT/<gate_name>, it connects to the upstream MCP server

3. It discovers all upstream tools and re-exposes them

4. On each tool call, all argument values are checked against block patterns

5. If any pattern matches → error returned, call never reaches upstream

6. If no match → call is forwarded to upstream as-is

License

MIT