# Rail — AI Agent Guardrails via MCP # https://rail.aiops.services/llms.txt Rail is an MCP server that gives AI agents safe, auditable operating boundaries. It enforces scope declarations, runs behavioral pattern detection, requires human approval for high-risk actions, and records an immutable audit trail. Use Rail when an AI agent needs to touch production files, execute commands, or perform any action where an unconstrained mistake would be costly. ## What Rail Does - Scope governance: agents declare allowed_paths upfront; every action is checked against the manifest before execution - Confidence scoring: validate_action (integrated in check_scope) returns a 0-100 confidence score so orchestrators can gate execution on a threshold - Pattern detection: 30+ behavioural patterns detected (path traversal, privilege escalation, data exfiltration, prompt injection indicators, etc.) - Defer mode: high-risk actions are automatically paused and queued for human approval before the agent proceeds - Immutable audit: every check_scope call, snapshot, and approval is written to D1 and cannot be modified or deleted - Fail-closed safety: if Rail is unreachable, the recommended integration pattern is to treat the action as denied (fail-closed) - Webhook notifications: HMAC-SHA256 signed events for scope violations, approval requests, and session close ## MCP Tools (16) - declare_task Create a scoped task manifest and define allowed_paths - check_scope Verify path/action against scope, constitutional constraints, path traversal protection, and confidence scoring (0-100) with 30+ pattern detection - take_snapshot Save file content to R2 before changes (immutable) - list_snapshots Review all snapshots for a session - restore_snapshot Retrieve stored snapshot for rollback - close_session Close session, flush KV cache, finalize audit record - list_pending_approvals List actions awaiting human approval (defer mode) - approve_action Approve or deny a pending deferred action - register_webhook Register HMAC-SHA256 signed webhook endpoint - list_webhooks List all registered webhook endpoints - capture_route_inventory Capture all Worker routes before deployment and detect changes - list_route_inventories List stored route-inventory history for diff review - get_session_health Real-time session health: context drift, call frequency, path distance, and safety fingerprint - register_baseline Register or update a protected deploy baseline - validate_deploy Compare deployment files against the baseline and block unsafe releases - list_baselines List registered deploy baselines ## Integration MCP endpoint: https://rail.aiops.services/mcp Transport: HTTP (MCP spec 2025-03-26) Auth: X-Rail-Key: Auto-discovery: https://rail.aiops.services/.well-known/mcp.json MCP config: https://rail.aiops.services/mcp-config System prompt: https://rail.aiops.services/system-prompt Full reference: https://rail.aiops.services/llms-full.txt Examples: https://rail.aiops.services/examples ## Tool: capture_route_inventory Capture the current Worker route surface before a deployment or migration. Use it to freeze the route list, compare post-deploy behavior, and block destructive releases when endpoints disappear unexpectedly. Parameters: session_id string required Session token from declare_task worker_name string required Logical Worker identifier (for example rail-aiops) environment string optional Environment label such as production or staging routes array required Normalized route inventory [{method, path}] source_commit string optional Git commit / version being evaluated captured_at string optional ISO-8601 timestamp supplied by caller notes string optional Operator memo for deployment context Returns: inventory_id string Stored inventory identifier route_count integer Number of routes captured in this snapshot checksum string Stable hash of the normalized route list captured_at string Server timestamp used for the inventory Example: { "tool": "capture_route_inventory", "arguments": { "session_id": "sess_deploy_001", "worker_name": "rail-aiops", "environment": "production", "routes": [ { "method": "GET", "path": "/" }, { "method": "GET", "path": "/health" }, { "method": "POST", "path": "/mcp" } ], "source_commit": "2161bc9b", "notes": "Pre-deploy inventory before LP metadata refresh" } } Example response: { "inventory_id": "inv_rail_prod_20260403_001", "route_count": 32, "checksum": "sha256:4f4d7b...", "captured_at": "2026-04-03T10:06:12Z" } --- ## Tool: list_route_inventories List previously captured inventories and highlight route-count or checksum deltas. Use this after deployment to confirm that the public route surface did not shrink. Parameters: worker_name string optional Filter by Worker/service name environment string optional Filter by environment label session_id string optional Filter by deployment session limit integer optional Maximum inventories to return (default 20) Returns: inventories array [{inventory_id, worker_name, environment, route_count, checksum, captured_at, diff_summary}] Example: { "tool": "list_route_inventories", "arguments": { "worker_name": "rail-aiops", "environment": "production", "limit": 5 } } Example response: { "inventories": [ { "inventory_id": "inv_rail_prod_20260403_002", "worker_name": "rail-aiops", "environment": "production", "route_count": 32, "checksum": "sha256:91aa52...", "captured_at": "2026-04-03T10:18:41Z", "diff_summary": { "added": [], "removed": [], "changed": false } } ] } --- ## Tool: get_session_health Inspect the real-time health of an active deployment or editing session. Rail uses this to surface context drift, unusually high tool-call frequency, dangerous path movement, and safety fingerprint mismatches before an agent continues. Parameters: session_id string required Session token from declare_task include_recent_calls boolean optional Include latest tool-call summaries (default true) include_path_stats boolean optional Include path-distance and blast-radius metrics Returns: status string healthy | warning | critical context_drift object {score, detected, reasons[]} call_frequency object {calls_last_5m, burst_detected} path_distance object {max_distance, suspicious_jumps[]} safety_fingerprint object {expected, observed, matched} blast_radius object {read_count, write_count, delete_count, estimated_scope} checked_at string ISO-8601 timestamp Example: { "tool": "get_session_health", "arguments": { "session_id": "sess_deploy_001", "include_recent_calls": true, "include_path_stats": true } } Example response: { "status": "warning", "context_drift": { "score": 0.74, "detected": true, "reasons": ["scope widened from /src/** to /content/**"] }, "call_frequency": { "calls_last_5m": 19, "burst_detected": true }, "path_distance": { "max_distance": 4, "suspicious_jumps": ["/src/app.ts -> /etc/passwd"] }, "safety_fingerprint": { "expected": "fp_prod_abc", "observed": "fp_prod_abc", "matched": true }, "blast_radius": { "read_count": 11, "write_count": 2, "delete_count": 0, "estimated_scope": "service-local" }, "checked_at": "2026-04-03T10:22:03Z" } --- ## Pricing Free tier: 50 calls/month Pro tier: 10,000 calls/month — $29/month Enterprise: Unlimited calls — contact sales ## Stack Cloudflare Workers · Hono · D1 (audit + policies) · KV (session cache) · R2 (immutable snapshots) · Distributed tracing headers ## Health https://rail.aiops.services/health