# @jacobmolz/mcpguard

> Security proxy daemon for MCP servers — adds auth, rate limiting, PII detection, and audit logging

Latest version **0.3.12** (published 2026-07-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install @jacobmolz/mcpguard
pnpm add @jacobmolz/mcpguard
yarn add @jacobmolz/mcpguard
bun add @jacobmolz/mcpguard
```

Provides the command `mcp-guard`.

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.3.12 |
| Published | 2026-07-22 |
| First published | 2026-04-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=22 |
| Dependencies | 8 |
| Unpacked size | 394.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Jacob Molz |
| Maintainers | jacobmolz |
| Keywords | mcp, model-context-protocol, security, proxy, pii, audit, rate-limiting, authentication |

## Links

- npm: https://www.npmjs.com/package/@jacobmolz/mcpguard
- Repository: https://github.com/jmolz/m0lz.03
- Homepage: https://github.com/jmolz/m0lz.03#readme
- Issues: https://github.com/jmolz/m0lz.03/issues
- npm.io page: https://npm.io/package/@jacobmolz/mcpguard

## Dependencies (8)

- [zod](https://npm.io/package/zod.md) ^4.4.3
- [jose](https://npm.io/package/jose.md) ^6.2.2
- [koffi](https://npm.io/package/koffi.md) ^3.1.0
- [js-yaml](https://npm.io/package/js-yaml.md) ^5.2.0
- [commander](https://npm.io/package/commander.md) ^15.0.0
- [oauth4webapi](https://npm.io/package/oauth4webapi.md) ^3.8.5
- [@modelcontextprotocol/sdk](https://npm.io/package/@modelcontextprotocol/sdk.md) ^1.29.0
- [better-sqlite3-multiple-ciphers](https://npm.io/package/better-sqlite3-multiple-ciphers.md) ^12.11.1

## Alternatives

- [@clerk/clerk-expo](https://npm.io/package/@clerk/clerk-expo.md) — 133.6K weekly downloads
- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads

## Recent versions

- 0.3.12 (latest) — 2026-07-22
- 0.3.11 — 2026-07-06
- 0.3.10 — 2026-06-30
- 0.3.9 — 2026-06-29
- 0.3.8 — 2026-04-09
- 0.3.7 — 2026-04-09
- 0.3.6 — 2026-04-09
- 0.3.5 — 2026-04-09
- 0.3.4 — 2026-04-08
- 0.3.3 — 2026-04-08
- 0.3.2 — 2026-04-08
- 0.3.1 — 2026-04-08
- 0.3.0 — 2026-04-08
- 0.2.1 — 2026-04-08
- 0.1.0 — 2026-04-08

## README

<p align="center">
  <img src="branch-mark.svg" width="48" height="48" alt="m0lz.03 branch mark — mcp-guard variant">
</p>

<h1 align="center">m0lz.03</h1>

<p align="center">
  Security proxy daemon for MCP servers<br>
  Auth, rate limiting, PII detection, permissions, audit logging<br>
  <a href="https://m0lz.dev/writing/mcp-guard">m0lz.dev/writing/mcp-guard</a>
</p>

---


[![CI](https://github.com/jmolz/m0lz.03/actions/workflows/ci.yml/badge.svg)](https://github.com/jmolz/m0lz.03/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/mcp-guard)](https://www.npmjs.com/package/mcp-guard)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Security proxy daemon for MCP servers — adds authentication, rate limiting, PII detection, permission scoping, and audit logging without modifying upstream servers.

![m0lz.03 Demo](docs/assets/demo.gif)

## What is this?

MCP (Model Context Protocol) servers give AI coding tools access to files, databases, APIs, and more. But they have no built-in authentication, no audit trail, and no way to restrict which tools an agent can call.

m0lz.03 sits between your MCP client (Cursor, Claude Desktop, Claude Code, VS Code) and your MCP servers. It terminates the client connection, inspects every message through a security pipeline, then re-originates the request to the upstream server. Nothing passes through uninspected.

## Key Features

- **Authentication** — OS-level peer credentials, API keys, or OAuth 2.1 with PKCE
- **Rate limiting** — Per-server, per-user, per-tool limits with SQLite persistence
- **Permission scoping** — Allow/deny lists for tools and resources, with capability filtering
- **PII detection** — Regex-based scanning with Luhn validation, bidirectional (request + response)
- **Audit logging** — Every MCP interaction logged to queryable SQLite with optional encryption
- **Role-based policies** — OAuth claims mapped to roles with floor-based policy merge
- **Config composability** — Base configs via `extends` with SHA-256 pinning; personal configs can only restrict
- **Transport support** — stdio, SSE, and Streamable HTTP upstream connections
- **Zero-config start** — Daemon auto-starts on first bridge connection

## Quick Start

```bash
npm install -g @jacobmolz/mcpguard
```

### Option A: Auto-discover existing configs

```bash
mcp-guard init
```

This scans your Claude Desktop, Cursor, VS Code, and Claude Code configs, discovers MCP servers, and generates `mcp-guard.yaml`.

### Option B: Manual config

Create `mcp-guard.yaml`:

```yaml
servers:
  filesystem:
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
```

### Update your MCP client

Point your client at m0lz.03 instead of the upstream server:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-guard",
      "args": ["connect", "--server", "filesystem"]
    }
  }
}
```

The daemon auto-starts on first connection.

## Architecture

![m0lz.03 Architecture](docs/assets/architecture.svg)

- **Daemon** — Long-running process. Manages upstream connections, runs the interceptor pipeline, owns the SQLite database, serves the health dashboard.
- **Bridge** — Thin stdio relay (~50 lines). Zero policy logic. Structurally fail-closed.
- **CLI** — Stateless commands for management and configuration.

### Security Model

m0lz.03 uses **terminate, inspect, re-originate** — it fully owns both the client and upstream connections. The interceptor pipeline is fail-closed: any error blocks the request. The audit tap is structural (wired outside the pipeline) and cannot be bypassed.

Config merge uses **floor-based semantics**: personal configs can restrict but never relax base policies. `allowed_tools` are intersected, `denied_tools` are unioned, rate limits take the stricter value.

## Why This Matters: MCP Servers Have No Security Layer

### Without m0lz.03

```
Agent asks to read /home/user/.env via filesystem MCP server
  → Server returns: AWS_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
  → API key is now in the agent's context window
  → No authentication. No audit trail. No one knows it happened.
```

### With m0lz.03

```
Agent asks to read /home/user/.env via filesystem MCP server
  → m0lz.03 intercepts the response
  → PII detector matches AWS key pattern → BLOCK
  → Audit log records: blocked response, server=filesystem, pii_type=aws_key
  → Agent receives: "Request blocked by security policy"
```

## Scope

m0lz.03 operates at the **MCP protocol layer** — it inspects JSON-RPC messages between client and server. This is a deliberate architectural boundary.

**What m0lz.03 does not address:**

- **LLM prompt injection** — m0lz.03 does not analyze agent intent. Detecting whether an agent was tricked into making a malicious call requires agent-layer defenses.
- **Model jailbreaking or alignment bypasses** — m0lz.03 does not operate at the model layer. LLM safety is a model-layer concern, not a transport security concern.
- **Network-layer attacks** (MITM, DNS rebinding, TLS stripping) — m0lz.03 does not replace network security. Use standard network security controls.
- **Malicious MCP server implementations** — the proxy limits exposure via permissions and PII scanning, but a compromised server requires remediation at the source.

m0lz.03 is the protocol-layer firewall. It complements agent-layer and network-layer defenses — it doesn't replace them.

## Benchmark Results

The benchmark suite is open-source and fully reproducible (`pnpm benchmark`). It tests m0lz.03's deterministic interceptor pipeline — policy enforcement, pattern matching, and access control — against 7,095 programmatically generated attack scenarios across 10 categories and 10,168 legitimate requests. See [Benchmark Methodology](docs/benchmark-methodology.md) for threat model, statistical interpretation, and known limitations.

### Per-Category Detection

| Category | Rate | Status |
|----------|------|--------|
| PII response leak | 100.0% | Pass |
| Auth bypass | 100.0% | Pass |
| Sampling injection | 100.0% | Pass |
| Config override | 100.0% | Pass |
| Permission bypass | 98.9% | Pass |
| Capability probe | 97.4% | Pass |
| Resource traversal | 95.4% | Pass |
| PII evasion | 94.7% | Pass |
| PII request leak | 93.8% | Pass |
| Rate limit evasion | 92.4% | Pass |

### Summary

| Metric | Result | Target | Status |
|--------|--------|--------|--------|
| Detection rate | 97.0% | >95% | Pass |
| False positive rate | 0 in 10,168 requests (<0.03% at 95% CI) | <0.1% | Pass |
| Audit integrity | No raw PII in logs | Pass | Pass |
| p50 latency overhead | 0.17ms (deterministic pipeline, no network hop) | <5ms | Pass |

### Limitations

- Tested against own generated scenarios, not an independent corpus — [methodology explains mitigations](docs/benchmark-methodology.md#self-testing-honesty-about-our-own-test-suite)
- Regex PII detection misses semantic encoding (spelling out digits, splitting across fields)
- Does not address LLM-level prompt injection — complementary tools like those evaluated by [MCPSecBench](https://arxiv.org/abs/2508.13220) operate at the agent layer
- No coverage for network-layer attacks (MITM, DNS rebinding)
- ML-based detection planned but not yet implemented

> Full-suite results from `pnpm benchmark`. Quick mode (`pnpm benchmark:quick`) uses stratified sampling and typically reports ~89-93% detection. See [latest report](benchmarks/results/REPORT.md) for charts.

## CLI Reference

| Command | Description |
|---------|-------------|
| `mcp-guard start` | Start daemon (foreground, or `-d` for background) |
| `mcp-guard stop` | Stop running daemon |
| `mcp-guard connect -s <name>` | Start bridge for a server |
| `mcp-guard init` | Generate config from existing MCP client configs |
| `mcp-guard status` | Show daemon status |
| `mcp-guard health` | Liveness check (exit code 0/1) |
| `mcp-guard validate` | Validate config file |
| `mcp-guard logs` | Query audit logs |
| `mcp-guard auth login` | OAuth 2.1 authentication |
| `mcp-guard auth status` | Show token status |
| `mcp-guard auth logout` | Remove stored tokens |
| `mcp-guard dashboard-token` | Display dashboard auth token |

## Configuration

See [`mcp-guard.example.yaml`](mcp-guard.example.yaml) for a complete example.

Key config sections:
- `servers` — Upstream MCP server definitions (command, args, env, transport, policy)
- `daemon` — Socket path, home directory, log level, dashboard port, encryption
- `auth` — Authentication mode (os, api_key, oauth) and role definitions
- `pii` — PII detection settings, custom types, per-type actions
- `audit` — Logging and retention settings

## Docker

```bash
docker build -f docker/Dockerfile -t mcp-guard .
docker run --rm mcp-guard --help
```

Or with docker-compose:

```bash
docker compose -f docker/docker-compose.yml up
```

## Development

```bash
pnpm install
pnpm dev              # Start in dev mode
pnpm test             # Run tests (412 across 38 files)
pnpm lint             # Lint
pnpm typecheck        # Type check
pnpm build            # Production build
pnpm benchmark:quick  # Quick benchmark suite (~30s)
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## License

MIT

---
_Source: https://npm.io/package/@jacobmolz/mcpguard · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._