Deploying McpVanguard on Railway#

McpVanguard is a real-time security gateway for the Model Context Protocol (MCP). Deploying it on Railway gives you a managed, cloud-native gateway that intercepts and blocks malicious AI agent tool calls before they reach your infrastructure.

One-Click Deployment#

Deploy the full McpVanguard stack in one click:

Prerequisites#

• A Railway Account
• The MCP server command you want to protect (e.g., npx @modelcontextprotocol/server-filesystem /app/data)
• (Optional) receipt_v1 JSONL emission for offline-verifiable runtime evidence with mcp-receipt

Step-by-Step Configuration#

1. Required Variables#

You must set the following variables for McpVanguard to start successfully:

Safe Railway Baseline#

Railway services receive a public URL, so treat the gateway as hosted by default:

• use balanced while validating traffic and safe-zone tuning
• set VANGUARD_API_KEY before exposing the service to real clients
• switch to strict for production-sensitive systems only after auth, safe zones, and expected benign workflows have been validated
• add VANGUARD_ALLOWED_ORIGINS when browser clients are expected; in strict, configured origins are required on incoming browser requests

In strict, McpVanguard refuses to start on Railway's public bind path unless API-key auth or OAuth/JWKS auth is configured. Startup logs also include a hosted posture summary showing profile, bind scope, auth state, origin policy, claim policy, session binding, and Redis/shared-state status.

2. Security & AI Intelligence (Optional)#

Fine-tune the behavior of the security engine and connect your AI brain:

When To Use Local Semantic Mode#

If your deployment handles regulated data, needs low-latency local development, or must stay air-gapped, prefer a local or private OpenAI-compatible backend instead of a public API. The recommended profiles are documented in docs/LOCAL_SEMANTIC_MODE.md.

Operator Warnings#

• Semantic model quality can drift over time after backend upgrades.
• Thresholds tuned on the benchmark corpora can still produce long-tail false positives in production.
• If you change the backend or threshold profile, rerun the adversarial and false-positive corpora before promoting the change.

3. Layer 3: Behavioral Analysis & Entropy Governor (Optional)#

McpVanguard tracks per-session patterns to detect anomalous agent behavior and calculates Shannon Entropy to detect data exfiltration.

4. Horizontal Scaling: Redis (Optional)#

By default, McpVanguard stores behavioral session state in-memory. This works perfectly for single-replica deployments (the default).

If you need multiple replicas for high-availability, add an official Railway Redis service to your project. McpVanguard will automatically detect VANGUARD_REDIS_URL and share session state across all instances.

5. Runtime Receipts (Optional)#

For offline-verifiable runtime evidence, enable McpVanguard's dedicated receipt_v1 JSONL stream. This stream is separate from the human/SIEM audit log and is intended to be exported, signed, and verified by the standalone mcp-receipt tooling.

The receipt stream contains canonical request hashes, normalized-message hashes, policy decisions, profile metadata, rule findings, and runtime context. Raw tool arguments are not embedded in the receipt event.

Verifying Your Deployment#

Once deployed, Railway assigns you a public URL (e.g., https://mcpvanguard-yourproject.up.railway.app).

Verify the service is running:

curl https://your-project.up.railway.app/health
# Expected: {
#   "status": "ok",
#   "version": "2.1.x",
#   "layers": {"l1_rules": "ok", "l2_semantic": "ok", "l3_behavioral": "ok"},
#   "timestamp": 1711022400.0
# }

Connecting Your AI Agent#

To connect an AI agent (Claude Desktop, LangChain, OpenAI Agents, etc.) to your Railway deployment:

{
  "mcpServers": {
    "vanguard-remote": {
      "url": "https://your-project.up.railway.app/sse",
      "headers": {
        "X-Api-Key": "your-vanguard-api-key"
      }
    }
  }
}

Every tool call the agent makes will be intercepted, inspected, and either allowed or blocked by Vanguard before it reaches your MCP server.

Advanced: External Evidence Backend#

McpVanguard can also forward blocked-call evidence to an external evidence backend when VANGUARD_VEX_URL and VANGUARD_VEX_KEY are configured. Treat this as an optional integration path rather than a requirement for the Railway template.

[AI Agent (Vercel / OpenAI)] 
    -> [McpVanguard on Railway] - inspects and enforces MCP tool-call policy
        -> [External evidence backend] - optionally records submitted audit evidence

The repository includes a Railway-focused integration harness for this topology. Treat its results as environment-specific evidence, not a latency or audit-finality guarantee. See the certification harness for the exact scenarios.

To set it up:

1. Deploy or configure your evidence backend separately.
2. Copy its public URL from your Railway dashboard or provider console.
3. Set VANGUARD_VEX_URL on your McpVanguard service to that URL.
4. Set VANGUARD_VEX_KEY to the backend credential expected by that deployment.

The external evidence backend receives submitted blocked-call evidence while Vanguard performs local policy blocking at the edge.

Health Verification#

The instance is pre-configured with a /health endpoint:

GET /health
-> {
  "status": "ok",
  "version": "2.1.2",
  "layers": {"l1_rules": "ok", "l2_semantic": "ok", "l3_behavioral": "ok"},
  "timestamp": 1711022400.0
}

Railway uses this for readiness checks during deployment orchestration.

Support#

• Open an Issue
• Full Documentation
• Provnai Research Initiative
• Runtime receipts