Skip to main content

​
tollgate scan

The scan command spawns an MCP server, discovers its available tools, and performs security risk assessment on each tool. It generates recommended security policies based on the analysis. This is a proactive security measure that helps you understand what an MCP server can do before deploying it to production.

​
Usage

tollgate scan <package-or-command> [args...]

​
Options

OptionDescription
-o, --output <path>Output generated config to file
-g, --generate-configGenerate recommended configuration
-a, --appendAppend to existing config file
-n, --server-name <name>Server name for generated config
-t, --timeout <ms>Connection timeout (default: 30000)
-e, --env <key=value...>Environment variables to pass to server
--jsonOutput results as JSON

​
How It Works

  1. Server Spawn: The scanner spawns the MCP server process
  2. Tool Discovery: Calls tools/list to get all available tool definitions
  3. Risk Analysis: Analyzes each tool’s name, description, and parameters for risk indicators
  4. Policy Generation: Recommends appropriate actions (allow/prompt/deny/smart) for each tool

​
Risk Levels

The scanner classifies tools into five risk levels:
LevelDescriptionKeywords
🟢 safeNo risk indicators found-
🟢 readRead-only operationsget, list, fetch, search, view
🟡 writeWrite operationscreate, add, update, insert, upload
🔴 destructivePotentially destructivedelete, remove, drop, truncate, purge
🔴 dangerousArbitrary code/command executionexecute, run, eval, shell, command

​
Examples

​
Basic Scan

tollgate scan @modelcontextprotocol/server-memory
Output: 
🔍 Scanning MCP Server...

╔════════════════════════════════════════════════════════════╗
║ MCP Server Security Scan: ...server-memory                 ║
╠════════════════════════════════════════════════════════════╣
║ Tools Found: 9                                             ║
║                                                            ║
║   🟡 create_entities      Create multiple entities...      ║
║   🟡 create_relations     Create relations between...      ║
║   🔴 delete_entities      Delete entities...               ║
║   🟢 read_graph           Read the knowledge graph         ║
║   🟢 open_nodes           Open specific nodes...           ║
╠════════════════════════════════════════════════════════════╣
║ Risk Assessment:                                           ║
║   🟡 create_entities: write operation                      ║
║   🔴 delete_entities: destructive operation                ║
║   🟢 2 tool(s) are read-only (safe)                        ║
╠════════════════════════════════════════════════════════════╣
║ Recommended Policy:                                        ║
║   allow:  2 tool(s) (read-only)                            ║
║   prompt: 3 tool(s) (require approval)                     ║
║   deny:   3 tool(s) (blocked)                              ║
╚════════════════════════════════════════════════════════════╝

Overall Risk: DESTRUCTIVE

​
Generate Configuration

# Generate and output to stdout
tollgate scan @modelcontextprotocol/server-postgres --generate-config

# Save to file
tollgate scan @modelcontextprotocol/server-postgres -g -o tollgate.yaml

# Append to existing config
tollgate scan @anthropic/mcp-server-fetch -g -o tollgate.yaml --append

​
Scan with Environment Variables

# Pass required environment variables
tollgate scan @modelcontextprotocol/server-postgres \
  -e DATABASE_URL=postgresql://localhost/mydb

​
JSON Output for Scripting

tollgate scan @modelcontextprotocol/server-memory --json | jq '.summary'

{
  "safe": 0,
  "read": 2,
  "write": 4,
  "destructive": 3,
  "dangerous": 0
}

​
Generated Policy Example

When using --generate-config, the scanner produces a complete tollgate.yaml: 
# Tollgate Configuration
# Generated by `tollgate scan`
# Review and customize before use

version: "1"

defaults:
  action: prompt
  timeout: 60000

servers:
  memory:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-memory"]

    tools:
      # Read-only operations (safe)
      "read_graph":
        action: allow
      "open_nodes":
        action: allow

      # Write operations (require approval)
      "create_entities":
        action: prompt
        message: "Agent wants to run create_entities"
      "create_relations":
        action: prompt

      # Dangerous operations (blocked)
      "delete_entities":
        action: deny
        reason: "Destructive operation blocked"
      "delete_relations":
        action: deny

      # Catch-all for unknown tools
      "*":
        action: prompt

​
Smart Analyzer Detection

The scanner automatically detects when smart analyzers can be used:
Tool PatternRecommended Analyzer
SQL, query, databasesql analyzer
file, path, directoryfilesystem analyzer
shell, command, execshell analyzer
http, fetch, urlhttp analyzer
When a smart analyzer is detected, the recommended action becomes smart instead of prompt, allowing for intelligent content-based decisions.

​
Use Cases

​
Pre-Deployment Security Audit

Before adding a new MCP server to your configuration: 
tollgate scan @new-mcp-server --json > audit.json

​
Generate Starter Configuration

Bootstrap a new project with recommended policies: 
tollgate scan @modelcontextprotocol/server-postgres -g -o tollgate.yaml
tollgate scan @anthropic/mcp-server-filesystem -g -o tollgate.yaml -a

​
CI/CD Security Gate

Add to your pipeline to ensure servers meet security requirements: 
#!/bin/bash
result=$(tollgate scan $MCP_PACKAGE --json)
dangerous=$(echo $result | jq '.summary.dangerous')
if [ "$dangerous" -gt 0 ]; then
  echo "❌ Server has dangerous tools"
  exit 1
fi

​
Best Practices

  1. Always scan before deploying - Run scan on new MCP servers before adding to production
  2. Review generated configs - The scanner provides recommendations; always review before use
  3. Update periodically - Re-scan servers after updates to catch new tools
  4. Use JSON output for automation - The JSON format is stable for scripting