Ultra Guardrails let you define and enforce security policies across your MCP infrastructure. Every tool call passes through the guardrails engine before reaching upstream servers, giving you real-time protection against credential leakage, destructive actions, input manipulation, and more. Guardrails are configured in Ultra Hub and automatically synced to all connected gateways. Built-in guardrails are recommended during configuration, protecting your environment from the most common MCP security threats out of the box.Documentation Index
Fetch the complete documentation index at: https://docs.ultra.security/llms.txt
Use this file to discover all available pages before exploring further.
How Guardrails Work
When an MCP tool call arrives at an Ultra gateway, the guardrails engine evaluates it against all active guardrails in parallel. Each guardrail inspects the request (tool name, parameters, server context) and returns a decision. The strictest decision wins.Enforcement Modes
Every guardrail runs in one of four enforcement modes:| Mode | Behavior |
|---|---|
| Block | Prevents the request from reaching the upstream server. The client receives an error with the guardrail name and reason. |
| Alert | Allows the request but generates a warning-level audit event. Use this to monitor potential issues without disrupting workflows. |
| Monitor | Allows the request and records the event silently. Use this for visibility without notifications. |
| Redact | Allows the request after masking matched content in both the request and response. Matched values are replaced with [REDACTED]. |
Guardrails are fail-closed. If an evaluation error occurs or an evaluator is unavailable, the request is blocked regardless of the configured enforcement mode.
Scoping
Guardrails can be configured at three levels, with higher levels taking precedence:| Scope | Description |
|---|---|
| Organization | Applies to all workspaces and gateways in your org. Org-level settings override everything below. |
| Workspace | Applies to all gateways in a workspace. Overrides gateway-level settings. |
| Gateway | Applies to a single gateway. Most granular scope. |
Built-in Guardrails
Ultra ships with built-in guardrails that are recommended during configuration. These cover the most critical MCP security risks and require no configuration to start protecting your environment. You can view the full list, descriptions, and configuration options for each guardrail in the Guardrails page in Ultra Hub.| Guardrail | Category | Description |
|---|---|---|
| Parameter Validation and Input Sanitization | Input Protection | Validates tool call parameters against type constraints, range limits, and dangerous patterns like path traversal (../), dangerous CLI flags (--exec, --privileged), shell injection, and command chaining. Supports configurable allowed-directory restrictions and per-parameter blocklists. |
| Credential and Secret Protection | Data Protection | Detects and blocks access to credential files (.env, .aws/credentials, .ssh/id_*, and more), secrets in tool parameters (API keys, tokens, private key headers), and cloud metadata endpoints. Automatically redacts matched secret values in audit log entries. |
| In-Line Authorization and Destructive Action Blocking | Access Control | Blocks destructive actions before they reach target systems. Covers destructive tool names (delete_*, drop_*, rm_*), dangerous SQL and shell operations in parameters, code/git write tools, and financial/payment tools. Each category can be independently enabled or disabled. |
| PII and Personal Data Protection | Data Privacy | Detects personally identifiable information (PII) in tool call parameters and resource URIs, including email addresses, US Social Security numbers, phone numbers, credit cards (Luhn-validated), IBANs, cryptocurrency wallet addresses, BIC/SWIFT codes, and IPv4 addresses. Each PII category is independently toggleable, and a per-tool or per-resource bypass list lets you exempt internal tools that legitimately handle PII (such as HR or CRM lookups). |
| Rate Limiting | Infrastructure | Configurable request rate limits per MCP server to prevent resource exhaustion and enforce usage quotas. Define rules with per-server or wildcard limits using fixed time windows. |
PII and Personal Data Protection
The PII guardrail scans request parameters and resource URIs for personal data and emits a violation for each match. When run in Redact mode, matched values are replaced with[REDACTED] in the request payload, the response echo, and the audit trail before reaching the upstream server.
Default configuration. The guardrail is enabled by default in Block mode with the high-precision categories turned on (email, US SSN, phone numbers, credit cards with Luhn validation, IBAN, and crypto addresses). Lower-precision categories that frequently collide with non-PII identifiers are off by default and can be enabled per workspace:
- BIC / SWIFT codes — off by default. Format collides with enum values, error codes, and UUID fragments.
- Public IPv4 addresses — off by default. Many tool calls legitimately reference public IPs.
- Private IPv4 addresses — off by default. Internal network references are rarely sensitive.
bypass_tools list skips PII detection for matching tools or resources. Use exact names (e.g., salesforce_search) or prefixes ending in * (e.g., workday_*, workday://*). Matching is case-insensitive and applies to both request redaction and response scanning. Use this for internal tools that are expected to handle PII so the guardrail does not interfere with their normal operation.
PII categories are detected via regular expressions, with additional validation for high-noise patterns: credit cards are validated against the Luhn check digit, IBANs are restricted to country codes in the SWIFT registry, and BIC codes are validated against ISO 3166-1 alpha-2 country codes. Some structurally similar strings (like long base58 hashes resembling Bitcoin addresses) can still false-positive — start in Alert mode if you are unsure how the guardrail will behave against your traffic.
Guardrail Categories
Guardrails are organized into categories that map to different areas of MCP security:| Category | Description | Built-in Guardrails |
|---|---|---|
| Input Protection | Validates and sanitizes incoming tool call parameters | Parameter Validation and Input Sanitization |
| Data Protection | Prevents credential leakage and secret exposure | Credential and Secret Protection |
| Data Privacy | Detects and protects personally identifiable information | PII and Personal Data Protection |
| Access Control | Enforces authorization and blocks destructive actions | In-Line Authorization and Destructive Action Blocking |
| Output Safety | Filters and validates tool call responses | — |
| Infrastructure | Rate limiting, circuit breaking, and availability protection | Rate Limiting |
Choosing Your Guardrail Configuration
Default Protection
Built-in guardrails are recommended during configuration and run in Block mode. For most organizations, enabling all built-in guardrails provides strong baseline security with no additional setup required. Before adding custom guardrails or changing enforcement modes, consider your team’s workflows.Scoping Flow
When configuring guardrails, work from broad to specific:- Start at the organization level — Set your baseline security posture. The built-in guardrails are recommended here. Most organizations should keep them all enabled in Block mode at the org level.
- Adjust at the workspace level — If certain teams need different policies (for example, a development workspace where destructive actions are acceptable for testing), override specific guardrails at the workspace level.
- Fine-tune at the gateway level — For individual gateways that need special treatment, apply gateway-level overrides. This is the most granular scope and is useful for edge cases.
When to Change Enforcement Modes
| Scenario | Recommended Mode |
|---|---|
| Production environments with sensitive data | Block — Prevent threats from reaching upstream servers |
| New deployment, evaluating guardrail coverage | Alert — See what would be caught without disrupting workflows |
| Development or staging environments | Monitor — Log everything for visibility, allow all requests |
| Handling sensitive data that must not appear in logs | Redact — Mask matched content in requests and responses |
Adding Guardrails Beyond Defaults
Consider enabling additional guardrails if your environment involves:- Custom internal tools — Create custom guardrails (see below) to enforce organization-specific policies on tool names, parameters, or servers
- Multi-tenant environments — Layer workspace-level and gateway-level guardrails to isolate tenants
- Compliance requirements — Check the framework coverage tags on each guardrail to map your coverage against AARM, SAFE, and AUIC-1 frameworks
- Sensitive data workflows — Switch credential protection to Redact mode if you need requests to proceed but want secrets masked
Custom Guardrails
Beyond the built-in guardrails, you can create custom guardrails to enforce organization-specific security policies. Custom guardrails use the same evaluation engine and enforcement modes as built-in guardrails.Creating a Custom Guardrail
- Navigate to Guardrails in the Ultra Hub sidebar
- Click + Create Custom Guardrail in the top-right corner
- Fill in the guardrail details:
- Name — A descriptive name (e.g., “Block /secrets directory access”)
- Description — What the guardrail does and why
Trigger Conditions
Trigger conditions define when the guardrail fires. Each condition has three parts: a field, an operator, and a value. You can add multiple conditions joined with AND logic using + Add condition (AND). Available fields:| Field | Description |
|---|---|
| Tool Name | The name of the MCP tool being called |
| Server Name | The upstream server handling the request |
| Resource URI | The resource being accessed |
| Any Parameter | Matches against all parameter values |
| Parameter… | Matches against a specific named parameter |
| User ID | The authenticated user’s identity ID. Empty string for unauthenticated requests. |
| User Email | The authenticated user’s email address. Empty string for unauthenticated requests. |
| User Name | The authenticated user’s display name. Empty string for unauthenticated requests. |
| Client ID | The MCP client name from the connection handshake (e.g., claude-desktop, cursor). Empty string when unknown. |
| Client Version | The MCP client version from the connection handshake (e.g., 1.2.3). Empty string when unknown. |
Trigger conditions match against values at any depth in the request parameters, not just top-level fields. If a tool call includes nested objects or arrays, the condition will evaluate against values found within them as well.
User and client identity fields are always present in the evaluation context. When the request is unauthenticated or the client identity is unknown, these fields contain an empty string. Keep this in mind when writing regex conditions — patterns that match empty strings (like
.*) will match unauthenticated requests.| Operator | Description |
|---|---|
| equals | Exact match |
| not equals | Does not match exactly |
| contains | Value includes the specified string |
| not contains | Value does not include the specified string |
| starts with | Value begins with the specified string |
| not starts with | Value does not begin with the specified string |
| ends with | Value ends with the specified string |
| not ends with | Value does not end with the specified string |
| matches regex | Value matches a regular expression pattern |
| in list | Value is one of a comma-separated list |
| greater than | Numeric comparison |
| less than | Numeric comparison |
Enforcement Action
Choose the enforcement action for your custom guardrail:- Block — Hard block with denial receipt. The request is stopped and the client receives an error.
- Alert — Notify but allow action. The request proceeds and a warning event is generated.
- Monitor — Log only, no notification. The request proceeds silently.
- Redact — Mask sensitive data in transit. Matched content is replaced with
[REDACTED].
Example: Block Access to Secrets Directory
To create a guardrail that blocks any tool call attempting to access files in a/secrets/ directory:
- Name: Block /secrets directory access
- Description: Prevents any tool from reading or writing files in the /secrets directory
- Trigger Conditions:
- Field: Any Parameter | Operator: contains | Value:
/secrets/
- Field: Any Parameter | Operator: contains | Value:
- Enforcement Action: Block
Example: Alert on Unrecognized Servers
To get notified when tool calls hit a server outside your approved list:- Name: Alert on unapproved servers
- Description: Flags tool calls routed to servers not in the approved list
- Trigger Conditions:
- Field: Server Name | Operator: not equals | Value:
approved-server-1 - Field: Server Name | Operator: not equals | Value:
approved-server-2
- Field: Server Name | Operator: not equals | Value:
- Enforcement Action: Alert
Example: Restrict command execution to internal users
To blockexecute_command tool calls from users outside your organization:
- Name: Block external users from execute_command
- Description: Only users with a @company.com email can run execute_command
- Trigger Conditions:
- Field: Tool Name | Operator: equals | Value:
execute_command - Field: User Email | Operator: not ends with | Value:
@company.com
- Field: Tool Name | Operator: equals | Value:
- Enforcement Action: Block
Dry-run testing
Before enforcing a guardrail in production, you can dry-run it against historical traffic to preview what it would catch. Dry-run evaluates a saved guardrail against stored traces and returns which requests would have triggered, without affecting live traffic. Dry-run works for all guardrail types.Running a dry-run
- Navigate to Guardrails in the Ultra Hub sidebar
- Select a guardrail to open the detail panel
- Click Dry Run to evaluate the guardrail against recent traces
- Traces evaluated — Total number of historical traces tested
- Would trigger — Number of traces that would have been caught
- Events — Details of each trace that would have triggered, including the action that would be taken (block, alert, monitor, or redact) and the matched request context
When to use dry-run
| Scenario | Why dry-run helps |
|---|---|
| Enabling a new guardrail | Preview impact before switching to Block mode |
| Tuning rate-limit thresholds | See how different requests_per_window and window_seconds values affect real traffic |
| Changing enforcement modes | Understand what would change if you move from Monitor to Block |
| Custom guardrail validation | Verify your trigger conditions match the intended requests |
Viewing Enforcement Events
Every guardrail evaluation is recorded as a GUARDRAIL event in the audit log, regardless of outcome. You can view these in the Audit Log page alongside TOOL CALL events.Grouped evaluations
When multiple guardrails evaluate a single request, their results share the sametrace_id and are displayed as a single collapsible row in the audit log. The group row shows:
- A Guardrail [N] badge indicating how many evaluations occurred
- The strongest outcome across all evaluations (deny > redact > alert > monitor > allow)
- The highest severity across all evaluations (critical > error > warning > info)
Audit detail
Clicking a guardrail event (or an individual evaluation inside a group) opens the Audit Detail panel, which shows:- Event type and severity — GUARDRAIL badge with INFO, WARNING, or ERROR severity
- Timestamp — When the evaluation occurred
- Context — The tool/action being evaluated, the MCP server it targeted, the MCP client that made the request, and the outcome (ALLOW, BLOCK, ALERT, MONITOR, REDACT)
- User identity — Name, email, and user ID of the person whose request triggered the evaluation
- Raw details — Full JSON including the guardrail’s enforcement mode, guardrail ID, which guardrail was evaluated (e.g.,
parameter-validation,credential-protection), type (builtin or custom), any matches, request context, and trigger details
Severity mapping
| Outcome | Severity | Description |
|---|---|---|
| Allow | INFO | Guardrail evaluated and found no issues |
| Monitor | INFO | Guardrail matched but is in monitor mode |
| Alert | WARNING | Guardrail matched and generated a notification |
| Redact | WARNING | Guardrail matched and masked sensitive content |
| Block | ERROR | Guardrail matched and prevented the request |
trace_id and are grouped into a single expandable row in the audit log.
Next Steps
Anomaly Detection
LLM-powered security analysis for MCP tool calls
Audit Log
View guardrail enforcement events alongside all MCP activity
RBAC
Control who can configure and view guardrails
Dashboard
Monitor guardrail activity in the web dashboard