Gateway

The Gateway (oxvault-gw) is a runtime security proxy. It sits between your AI client and an MCP server and inspects every JSON-RPC message as it flows in both directions — blocking policy violations, alerting on credential leaks and injection, detecting rug pulls, and writing an audit log.

The Gateway is a commercial component. It requires a valid license key to start; there is no built-in trial mode. It is built on top of the open-source scanner detection engine, so its runtime checks and the scanner’s static checks share the same rules.

License

A valid Polar license key is required before the proxy will start. Supply it one of three ways:

• --license <key> flag
• OXVAULT_LICENSE environment variable
• interactive prompt — if no key is set and the process is attached to a terminal, the Gateway reads the key from /dev/tty so it never lands in shell history

Licensing is handled by Polar. Keys are validated and activated per machine; the local cache (~/.oxvault/license-cache.json) keeps the Gateway working offline for up to seven days, and each machine gets a stable ID (~/.oxvault/machine-id) recorded in ~/.oxvault/activation.json. If a key is already active on the maximum number of machines, activation fails with a clear error — free a slot with oxvault-gw deactivate on another machine.

oxvault-gw --license <key> -- python3 server.py
OXVAULT_LICENSE=<key> oxvault-gw -- npx @company/mcp-server
oxvault-gw -- python3 server.py          # prompts for the key on a TTY

Quickstart

1. Create a policy (optional)

oxvault-gw init

This writes the default policy to .oxvault/policy.json. Skip it and the Gateway uses the same defaults in-memory.

2. Wrap your MCP clients

oxvault-gw wrap

wrap discovers your MCP client config files and rewrites every server entry to launch through the Gateway instead of directly. A backup of each file is written as <config>.oxvault-backup, and the command is idempotent — already-wrapped entries are skipped on a second run. Restart your client to apply the change.

Auto-discovered clients (--config auto, the default):

Client	Config path
Claude Code	~/.claude.json
Claude Desktop	~/.claude/claude_desktop_config.json
Cursor	~/.cursor/mcp.json
VS Code	~/.vscode/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json

Wrap a single file instead:

oxvault-gw wrap --config ~/.cursor/mcp.json

Undo everything (restore from the backups):

oxvault-gw unwrap            # or: oxvault-gw unwrap --config <path>

3. Watch the audit log

oxvault-gw log --follow

Proxy modes

stdio proxy (default)

The root command wraps a local MCP server that speaks stdio. Everything after -- is the server launch command:

oxvault-gw -- python3 server.py
oxvault-gw -v -- npx @company/mcp-server
oxvault-gw --scanner-block-severity=high -- node server.js

Flag	Default	Description
-v, --verbose	false	Log all JSON-RPC messages to stderr
--log	~/.oxvault/audit.jsonl	Audit log path
--policy	.oxvault/policy.json	Policy file (falls back to defaults if missing)
--scanner-block-severity	critical	Minimum scanner severity to block: critical, high, warning, off
--no-color	false	Disable colored output
--license	—	Polar license key (overrides OXVAULT_LICENSE)

HTTP proxy

proxy forwards to a remote StreamableHTTP MCP server, applying the same policy and scanner checks in real time:

oxvault-gw proxy --remote https://mcp.example.com/v1 --listen :3000

Flag	Default	Description
--remote	(required)	Remote MCP server URL (http/https only)
--listen	:3000	Local address to listen on
--allow-private	false	Allow proxying to private/loopback addresses (dev only)

Plus all the stdio flags above. By default the proxy refuses to connect to private or loopback addresses (an SSRF guard enforced at connection time); --allow-private lifts that for local development.

How inspection works

Every message is evaluated in a fixed order. The first stage to decide wins:

1. Policy engine — rule-based access control on tool names, arguments, and responses. A block returns a JSON-RPC error to the client. See the Policy guide.
2. Scanner: arguments — runs the scanner’s argument-injection rules (shell, SQL, path traversal, SSRF, …) on tools/call requests.
3. Scanner: responses — runs response rules (AWS keys, GitHub PATs, JWTs, …) on server responses. Responses are never blocked, only alerted.
4. Scanner: description poisoning — runs description rules on every tool in tools/list.
5. Rug-pull detection — records a SHA-256 baseline of the tool set on the first tools/list and alerts on any later change.
6. Audit — every message is written to the audit log.

The --scanner-block-severity threshold controls stages 2–4: critical blocks only critical findings, high blocks high and critical, warning blocks warning and above, and off turns the scanner into alert-only mode. It is independent of the policy engine, and it never blocks responses.

Audit log

Every message produces one JSON object per line in ~/.oxvault/audit.jsonl (override with --log). Fields:

Field	Description
timestamp	RFC-3339 nanosecond UTC time
direction	client_to_server or server_to_client
method	JSON-RPC method (for requests/notifications)
id	JSON-RPC correlation id
tool	Tool name for tools/call requests
action	forwarded, blocked, or alert
detail	Human-readable reason for a block or alert

View it with the built-in renderer:

oxvault-gw log                      # last 50 entries, colorized
oxvault-gw log --filter blocked     # only blocks (also: alert, forwarded)
oxvault-gw log --follow             # live tail
oxvault-gw log --limit 100          # last 100 (0 = all)

All commands

Command	Purpose
oxvault-gw -- <cmd>	stdio proxy for a local MCP server
oxvault-gw proxy	HTTP proxy for a remote MCP server
oxvault-gw wrap	Rewrite client configs to route through the Gateway
oxvault-gw unwrap	Restore client configs from backups
oxvault-gw init	Create the default .oxvault/policy.json
oxvault-gw log	View the audit log
oxvault-gw deactivate	Release this machine’s license activation

Next: the Policy guide covers the policy file format and the built-in rules.