Skip to main content

Proxy Mode

Proxy mode is the primary way to use Helmet for monitoring and securing MCP (Model Context Protocol) communications. When running in proxy mode, Helmet acts as an intermediary between MCP clients and servers, providing visibility, logging, and policy enforcement.

Overview​

The Helmet proxy intercepts all communication between your AI applications and MCP servers, enabling:

  • Complete visibility into all requests and responses
  • Real-time logging of tool calls and interactions
  • Policy enforcement to block unauthorized or dangerous operations
  • Performance metrics to understand usage patterns
  • Security scanning of data flowing through the system

Running the Proxy​

Basic Usage​

To run Helmet in proxy mode, simply prefix your MCP server command with helmet:

helmet <your-mcp-server-command> [args...]

For example:

helmet node my-mcp-server.js
helmet python mcp_server.py
helmet docker run -i my-mcp-server

Docker Integration​

When using Docker containers, Helmet automatically handles environment variable injection:

helmet docker run -i -e API_KEY=xxx my-mcp-server

The proxy intelligently manages environment variables, filtering out Helmet-specific variables while preserving those needed by your MCP server.

Configuration Options​

You can configure the proxy behavior using flags or environment variables:

# Using flags
helmet --log-level=DEBUG --metrics-interval=30s node server.js

# Using environment variables
HELMET_LOG_LEVEL=DEBUG helmet node server.js

Available options:

  • --log-level: Set to INFO or DEBUG for different verbosity levels
  • --metrics-interval: How often to log performance metrics
  • --log-file: Path to save detailed protocol logs
  • --api-url: Custom API endpoint (defaults to https://api.helmet.sh)

Authentication Required: HELMET_SESSION_TOKEN​

Important: To enable Helmet's monitoring, logging, policy enforcement, and metrics features, you must set the HELMET_SESSION_TOKEN environment variable:

export HELMET_SESSION_TOKEN="your-session-token-here"
helmet node server.js

Without this token:

  • ✅ Your MCP server will still start and function normally
  • ❌ No logs will be sent to the Helmet dashboard
  • ❌ Policies will not be enforced
  • ❌ Monitoring and metrics will be disabled
  • ❌ You won't see any data in the Helmet web interface

To obtain your session token:

  1. Log into the Helmet dashboard
  2. Navigate to your account settings
  3. Generate or copy your API token
  4. Set it as the HELMET_SESSION_TOKEN environment variable

For production deployments, we recommend storing the token securely:

# Add to your shell profile (.bashrc, .zshrc, etc.)
export HELMET_SESSION_TOKEN="your-session-token-here"

# Or use a secrets management system
helmet node server.js

How It Works​

When you run a command through Helmet proxy:

  1. Process Interception: Helmet spawns your MCP server as a subprocess
  2. Communication Monitoring: All stdin/stdout communication is intercepted
  3. Protocol Analysis: MCP protocol messages are parsed and analyzed
  4. Policy Evaluation: Each tool call is checked against configured policies
  5. Logging and Metrics: All interactions are logged and sent to the Helmet dashboard
  6. Pass-through: Approved messages are forwarded between client and server

Features​

Automatic Session Tracking​

Each proxy session is assigned a unique ID and tracked with:

  • Session start/end times
  • Client information (when available)
  • Machine metadata
  • Complete interaction logs

Policy Enforcement​

If policies are configured, the proxy will:

  • Evaluate each tool call against defined rules
  • Block prohibited operations with appropriate error responses
  • Log policy violations for audit trails

Smart Environment Handling​

The proxy intelligently manages environment variables:

  • Filters out system and shell-specific variables
  • Preserves application-specific configuration
  • Prevents sensitive Helmet tokens from leaking to subprocesses

CLI Commands​

proxy​

helmet proxy [flags] <upstream-command> [upstream-args...]

Explicitly run in proxy mode (this is also the default behavior).

init​

helmet init

Initialize Helmet configuration and login. (Coming soon)

agent​

helmet agent

Run Helmet in agent mode for server management. (Coming soon)

Best Practices​

Development Environment​

Use DEBUG logging during development to see detailed protocol information:

HELMET_LOG_LEVEL=DEBUG helmet node dev-server.js

Production Environment​

  • Use INFO level logging to reduce noise
  • Configure appropriate metrics intervals
  • Ensure session tokens are properly secured
  • Set up log rotation for protocol logs

Security Considerations​

  • Never commit session tokens to version control
  • Use environment variables for sensitive configuration
  • Regularly review logged interactions for anomalies
  • Configure policies before deploying to production

Monitoring and Logs​

All proxy sessions are visible in the Helmet dashboard where you can:

  • View real-time logs of MCP interactions
  • Monitor tool usage patterns
  • Investigate policy violations
  • Export logs for compliance

Troubleshooting​

Proxy Not Starting​

  • Verify the upstream command is correct
  • Check that the MCP server binary is in your PATH
  • Ensure you have proper permissions

No Logs Appearing​

  • Confirm your session token is valid
  • Check network connectivity to the Helmet API
  • Verify the API URL is correct

Environment Variables Not Passed​

  • Check if the variable matches injection patterns
  • Use --pass-env flag for custom prefixes
  • Verify variables are exported in your shell

Next Steps​