Skip to main content

​
Natural Language Policies

Tollgate supports defining policies using natural language statements. Write policies in plain English and Tollgate will parse them into structured tool policies.

​
Quick Start

Add a policies array to your configuration: 
version: "1"

policies:
  - "Allow read operations on postgres"
  - "Deny destructive queries on any database"
  - "Prompt for file writes"
  - "Block dangerous shell commands"

servers:
  postgres:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
  filesystem:
    command: npx
    args: ["-y", "@anthropic/filesystem-server"]
  shell:
    command: npx
    args: ["-y", "@anthropic/shell-server"]

​
Syntax

Natural language policies follow this general structure: 
[ACTION] [RISK_LEVEL] [OPERATION_TYPE] on [SERVER]

​
Actions

Start your policy with an action verb:
ActionAliasesMeaning
AllowPermit, Enable, GrantAllow automatically
DenyBlock, Reject, ForbidBlock the operation
PromptAsk, Confirm, Require approvalAsk user for approval

​
Risk Levels

Specify which risk level(s) to target:
LevelAliasesDescription
safe-No-risk operations
readRead-only, Select, QueryRead operations
writeInsert, CreateWrite operations
destructiveUpdate, Delete, ModifyData modification
dangerousDrop, Truncate, AdminHigh-risk operations
You can also use combined terms:
  • mutations - write + destructive + dangerous
  • all / any - all risk levels
  • operations - contextual, infers from analyzer

​
Server Targets

Specify which servers the policy applies to: 
policies:
  # Specific server
  - "Allow read operations on postgres"

  # All servers
  - "Deny dangerous operations on any server"

  # All databases
  - "Prompt for destructive queries on any database"

​
Examples

​
Database Policies

policies:
  # Read-only access
  - "Allow read operations on postgres"

  # Prompt for writes
  - "Prompt for write operations on postgres"

  # Block destructive operations
  - "Deny destructive queries on any database"

  # Block all dangerous operations
  - "Block dangerous operations on any database"

​
Filesystem Policies

policies:
  # Allow reading files
  - "Allow read operations on filesystem"

  # Prompt before writing
  - "Prompt for file writes"

  # Block system directory access
  - "Deny dangerous filesystem operations"

​
Shell Policies

policies:
  # Allow safe commands
  - "Allow safe commands on shell"

  # Prompt for file operations
  - "Prompt for write commands on shell"

  # Block dangerous commands
  - "Deny dangerous shell commands"

​
HTTP/API Policies

policies:
  # Allow GET requests
  - "Allow read requests on http"

  # Prompt for POST/PUT
  - "Prompt for write requests"

  # Block internal network access (SSRF)
  - "Deny dangerous http requests"

​
Combining with YAML Policies

Natural language policies merge with explicit YAML policies. YAML policies take precedence for specific rules: 
version: "1"

policies:
  # Natural language baseline
  - "Allow read operations on postgres"
  - "Prompt for write operations on postgres"
  - "Deny dangerous operations on any server"

servers:
  postgres:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    tools:
      # YAML overrides for specific tools
      "list_tables":
        action: allow  # Always allow this specific tool
      "admin_*":
        action: deny   # Block all admin tools

​
How Parsing Works

Tollgate parses natural language policies into structured rules: 
# This natural language policy:
"Allow read operations on postgres"

# Becomes this structured policy:
servers:
  postgres:
    tools:
      "*":
        action: smart
        analyzer: sql
        risks:
          read: allow

​
Analyzer Inference

The parser automatically infers the appropriate analyzer:
KeywordsInferred Analyzer
database, db, queries, sqlsql
file, filesystem, pathfilesystem
shell, command, bashshell
http, fetch, request, apihttp

​
Partial Policies

When you specify a single risk level, only that level is set in the policy. This allows multiple policies to combine: 
policies:
  - "Allow read operations on postgres"    # sets read: allow
  - "Prompt for write operations on postgres"  # sets write: prompt
  - "Deny destructive operations on postgres"  # sets destructive: deny
  # Result: read=allow, write=prompt, destructive=deny

​
Validation

Tollgate validates policies during configuration loading: 
tollgate validate

# Output:
# ✓ Configuration valid
# ✓ Parsed 4 natural language policies
#   - Allow read operations on postgres
#   - Prompt for write operations on postgres
#   - Deny destructive queries on any database
#   - Block dangerous shell commands

​
Error Messages

Invalid policies produce helpful error messages: 
policies:
  - "read operations on postgres"  # Missing action!

# Error: Could not identify action.
# Start with a verb like "Allow", "Deny", or "Prompt for"
# Suggestions:
#   - Example: "Allow read operations on postgres"
#   - Example: "Deny read operations on postgres"

​
Common Patterns

​
Read-Only Database Access

policies:
  - "Allow read operations on postgres"
  - "Deny mutations on postgres"

​
Safe Shell Environment

policies:
  - "Allow safe commands on shell"
  - "Allow read commands on shell"
  - "Prompt for write commands on shell"
  - "Deny dangerous shell commands"

​
Restrictive Default

policies:
  - "Prompt for all operations on any server"
  - "Deny dangerous operations on any server"

​
Development vs Production

Use environment-specific config files: 
# tollgate.dev.yaml
policies:
  - "Allow all operations on any server"

# tollgate.prod.yaml
policies:
  - "Allow read operations on any server"
  - "Prompt for write operations on any server"
  - "Deny destructive operations on any server"
  - "Deny dangerous operations on any server"

​
Best Practices

Start Restrictive

Begin with deny/prompt policies and selectively allow. Safer than allowing by default.

Be Specific

Target specific servers when possible. "on postgres" is clearer than "on any database".

Layer Policies

Use multiple focused policies rather than one complex one. Easier to understand and maintain.

Document Intent

Natural language policies are self-documenting. Write them clearly for future readers.

​
Limitations

Natural language policies have some limitations:
  1. Tool-level granularity: NL policies apply to * (all tools) by default. Use YAML for tool-specific rules.
  2. Simple patterns only: Complex conditions (regex, multiple fields) require YAML policies.
  3. Server must exist: Policies targeting specific servers require those servers to be defined.
  4. English only: The parser currently only supports English language policies.
For advanced use cases, combine natural language with explicit YAML policies.