Getting Started with McpVanguard#

Installation#

McpVanguard requires Python 3.11 or later.

Bash

pip install mcp-vanguard

Verify the installation:

Bash

vanguard --version

Configuration#

McpVanguard is configured via environment variables or a .env file in your working directory. There is no YAML config file.

Create a .env file:

Bash

# Required for hosted/SSE mode
VANGUARD_API_KEY=your-secret-key-here

# Optional: enable Layer 2 semantic scoring (requires Ollama or OpenAI)
# VANGUARD_SEMANTIC_ENABLED=true
# VANGUARD_OLLAMA_URL=http://localhost:11434

# Optional: Redis for distributed state
# VANGUARD_REDIS_URL=redis://localhost:6379

Quickstart — Local Sidecar Mode#

Wrap any existing MCP stdio server:

Bash

vanguard start --server "npx @modelcontextprotocol/server-filesystem /path/to/files"

What happens when it runs:

Vanguard starts the upstream MCP server as a subprocess.
All JSON-RPC traffic between the agent and the server passes through the proxy.
Layer 1 (YAML rules) is always active.
Layer 3 (behavioral analysis) is active by default.
Blocked calls are written to audit.log.

Quickstart — Hosted Gateway Mode#

Expose the proxy as an SSE endpoint:

Bash

vanguard sse --server "npx @modelcontextprotocol/server-filesystem /path/to/files" --host 0.0.0.0 --port 8080

Clients connect via SSE. Always set VANGUARD_API_KEY when binding to a public interface.

Verify It's Working#

Bash

vanguard info --rules-dir rules

This prints the loaded rule count and active configuration.