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

| Field | Type | Default | Description | | --------- | -------- | ------- | ---------------------------------- | | port | number | 6427 | Port for the local HTTP proxy | | servers | object | — | Map of gate name → server config |

Each server:

| Field | Type | Description | | -------------- | ---------- | -------------------------------------------------- | | url | string | Upstream MCP server URL | | enabled | boolean | Set to false to passthrough without blocking | | token | string | Static Bearer token for upstream auth (optional) | | block | string[] | Patterns to block in tool call arguments (case-insensitive) | | matchMode | string | "substring" (default) or "word" — substring matches anywhere, word requires word boundaries (e.g. "UPDATE" won't match "updated_at" in word mode) | | blockMessage | string | Error message returned when blocked |

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