📚 Nexus guide: guardrails

What are guardrails?

Guardrails are security policies that control how AI assistants interact with tools and data. Guardrails provide nuanced rules that make AI systems safer and more predictable.

‍

Why guardrails matter

When AI assistants use tools, they need different constraints than human users:

• Content limits: An AI shouldn’t read 10GB files that would overwhelm its context
• Semantic filtering: Block prompts trying to access sensitive data patterns
• Behavioral rules: Prevent actions that make sense for humans but not for AI
• Dynamic policies: Adjust permissions based on the conversation context

‍

Types of guardrails

‍

How to add safety constraints to tool operations 

1. Identify the MCP server and tool. First, you need to know:

• The MCP server ID (the server providing the tool)
• The specific tool/operation name you want to constrain

2. List available guardrail templates. This shows you all the constraint templates available for that specific tool, with descriptions of what each does:

Use: manage-guardrail with action "list-templates"
- Specify the mcpServerId
- Specify the operationName (tool name)

3. Add a guardrail, once you know which template to use:

Use: manage-guardrail with action "add"
- mcpServerId: The server ID
- operationName: The tool name
- templateId: The constraint template ID
- value: The constraint value (string, number, boolean, or array)
- schemaPath (optional): JSONPath to specify where in the data to apply the constraint
- actionParams (optional): Additional template-specific parameters

4. To manage existing guardrails: 

• List guardrails: See all constraints on a specific tool or server
• Remove guardrails: Remove constraints by their ID

‍

Templates to enforce data validation rules

Guardrail templates provide pre-configured validation rules that you can apply to tool parameters and responses. Here are the common types:

Value constraints:

• min/max values: Enforce numeric ranges (e.g., budget must be ≤ $10,000)
• min/max length: Control string/array sizes (e.g., descriptions must be ≤ 500 chars)
• enum/allowed values: Whitelist specific values (e.g., status must be "draft", "active", or "paused")
• blocked values: Blacklist certain values

Pattern validation:

• regex patterns: Match specific formats (e.g., email addresses, phone numbers)
• data type validation: Ensure correct types (string, number, boolean, etc.)

Structural validation:

• required fields: Ensure certain parameters are always provided
• schema path targeting: Apply rules to nested data structures using JSONPath

‍

Scope guardrails to specific servers or tools

Guardrails use a hierarchical scoping system that lets you target constraints at different levels of specificity.

1. Server-level scope allows you to apply guardrails to an entire MCP server. It affects all tools within that server:

manage-guardrail → list or add
- mcpServerId: "your-server-id"
- operationName: (omit this parameter)

Tip: When you omit operationName, the guardrail applies globally to all operations from that server.

2. Tool-level scope (most common) allows you to apply guardrails to a specific tool/operation within a server. This targets just one tool, giving you fine-grained control:

manage-guardrail → list or add
- mcpServerId: "your-server-id"
- operationName: "specific_tool_name"

3. Parameter-level scope allows you apply guardrails more precisely. Within a tool, you can target specific parameters or parts of a data structure using schemaPath. The JSONPath you put in schemaPath lets you drill down to the exact field you want to constrain:

manage-guardrail → add
- mcpServerId: "your-server-id"
- operationName: "specific_tool_name"
- schemaPath: "$.parameter.nested.field"
- templateId: "validation_template"
- value: constraint_value

‍

List existing guardrails

1. To list all guardrails for a server:

manage-guardrail → list
- mcpServerId: "your-server-id"
- operationName: (omit this to see everything on the server)

2. To list guardrails for a specific tool:

manage-guardrail → list
- mcpServerId: "your-server-id"
- operationName: "specific_tool_name"

The list will show you:

• Constraint ID (you'll need this to remove it)
• Template type being used
• The constraint value
• Schema path (if targeting specific parameters)
• When it was added

‍

Remove guardrails

manage-guardrail → remove
- constraintId: "the-constraint-id-from-list"

‍

Toolkit data hooks

1. Pre-populate tool parameters automatically (Hook_Parameter)

Automatically set parameter values so the AI doesn't need to ask for them.

Use case: Always use a specific account ID, region, or configuration value.

manage-profile-data → update
- category: "Hook_Parameter"
- mcpServer: "your-server-id"
- tool: "tool_name"
- key: "parameter_name"
- value: "auto_filled_value"

2. Filter which tools are visible to the AI (Hook_Filter)

Hide tools from the AI to reduce noise or prevent access to certain operations.

Use case: Only show read operations, hide dangerous delete functions.

manage-profile-data → update
- category: "Hook_Filter"
- mcpServer: "your-server-id"
- value: ["tool1", "tool2", "tool3"]  ← Only these tools are visible

3. Create aliases or rename tools (Hook_ Alias)

Give tools friendlier or more descriptive names.

Use case: Rename technical tool names to business-friendly terms.

manage-profile-data → update
- category: "Hook_Alias"
- mcpServer: "your-server-id"
- key: "original_tool_name"
- value: "new_display_name"

4. Clone tools with different configurations (Hook_Clone)

Duplicate a tool with a new name, allowing different parameter presets.

Use case: Create "production" and "staging" versions of the same tool.

Single clone:
manage-profile-data → update
- category: "Hook_Clone"
- mcpServer: "your-server-id"
- key: "original_tool_name"
- value: "cloned_tool_name"

Multiple Clones:
manage-profile-data → update
- category: "Hook_Clone"
- mcpServer: "your-server-id"
- key: "original_tool_name"
- value: ["clone1_name", "clone2_name", "clone3_name"]

5. Override or add to tool descriptions (Hook_CustomDescription)

Change how tools are described to the AI for better context.

Use case: Add business context, warnings, or usage guidelines.

manage-profile-data → update
- category: "Hook_CustomDescription"
- mcpServer: "your-server-id"
- key: "tool_name"
- value: "Your custom description here"

‍

Managing hooks 

1. Read existing hooks:

manage-profile-data → read
- category: "Hook_Parameter" (or any other hook type)
- mcpServer: "your-server-id" (optional)

2. Describe hook structure and examples:

manage-profile-data → describe
- category: "Hook_Parameter" (or any other hook type)

3. Delete hooks:

manage-profile-data → delete
- category: "Hook_Parameter"
- mcpServer: "your-server-id"
- key: "specific_parameter" (optional - omit to delete all)