MCP Server

Why AI agents need security scanning

AI agents install packages, clone repos, and fetch files autonomously. Without scanning, they can't distinguish legitimate packages from typosquatted ones with malicious postinstall hooks.

AI Agent                    Sigil MCP Server
   │                              │
   ├─── sigil_scan_package ──────▶│
   │    ("npm", "express")        ├── download to quarantine
   │                              ├── 6-phase scan
   │                              ├── verdict: LOW RISK | score: 0
   │◀── { verdict, score } ──────┤
   │                              │
   ├─── sigil_approve ───────────▶│
   │    (quarantine_id)           ├── release from quarantine
   │◀── { status: "approved" } ──┤
   │                              │
   ├─── (proceeds to install) ───▶│
   │                              │

Sigil sits between the agent and the filesystem. Every package download, repo clone, and file scan is quarantined and analyzed across six phases before the agent can proceed. The agent gets a structured verdict it can reason about — not a binary pass/fail.

Quick setup

1. Install the Sigil CLI

# curl (Linux / macOS)
curl -sSL https://sigilsec.ai/install.sh | sh

# Homebrew
brew install nomark/tap/sigil

# Manual — download from GitHub Releases
# https://github.com/NOMARJ/sigil/releases

2. Build the MCP server

cd plugins/mcp-server
npm install
npm run build

3. Configure your client

Claude Code

Add the Sigil MCP server to your Claude Desktop configuration file.

{
  "mcpServers": {
    "sigil": {
      "command": "node",
      "args": ["/path/to/plugins/mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

Per-Project configuration

Place a .mcp.json file in the project root to enable Sigil for that project only.

{
  "mcpServers": {
    "sigil": {
      "command": "node",
      "args": ["./plugins/mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

Cursor

Open Settings > MCP Servers and add a new server with the command node and args pointing to dist/index.js.

Windsurf

Open Settings > MCP and add the Sigil server with the same command and args.

Available tools

The MCP server exposes six tools and one read-only resource. Each tool returns structured JSON that the AI agent can reason about.

// Example response
{
  "verdict": "MEDIUM",
  "score": 12,
  "findings_count": 3,
  "findings": [
    {
      "phase": "code_patterns",
      "severity": "high",
      "file": "src/utils/exec.js",
      "line": 14,
      "message": "Dynamic eval() with user-controlled input"
    },
    {
      "phase": "network_exfil",
      "severity": "medium",
      "file": "src/api/client.js",
      "line": 42,
      "message": "Outbound HTTP request to non-allowlisted domain"
    },
    {
      "phase": "obfuscation",
      "severity": "medium",
      "file": "lib/decode.js",
      "line": 8,
      "message": "Base64-encoded string decoded and executed"
    }
  ]
}

// Example call
{
  "name": "sigil_scan_package",
  "arguments": {
    "manager": "npm",
    "package_name": "express",
    "version": "4.18.2"
  }
}

// Example call
{
  "name": "sigil_clone",
  "arguments": {
    "url": "https://github.com/user/repo",
    "branch": "main"
  }
}

// Example response
{
  "count": 3,
  "items": [
    {
      "id": "q_abc123",
      "source": "npm:lodash@4.17.21",
      "status": "scanned",
      "score": 0,
      "verdict": "LOW RISK"
    },
    {
      "id": "q_def456",
      "source": "github.com/user/repo",
      "status": "scanned",
      "score": 12,
      "verdict": "MEDIUM"
    },
    {
      "id": "q_ghi789",
      "source": "pip:requests@2.31.0",
      "status": "pending",
      "score": null,
      "verdict": null
    }
  ]
}

// Example call
{
  "name": "sigil_approve",
  "arguments": {
    "quarantine_id": "q_abc123"
  }
}

// Example call
{
  "name": "sigil_reject",
  "arguments": {
    "quarantine_id": "q_def456"
  }
}

// Access via MCP resource protocol
sigil://docs/phases

// Returns structured phase documentation:
// - Phase name, weight, and description
// - File types and patterns each phase analyzes
// - Scoring methodology per phase

Example workflows

Common patterns for how an AI agent uses Sigil tools in conversation.

Agent calls: sigil_scan_package("npm", "left-pad", "1.0.0")
       ↓
Sigil returns: { verdict: "LOW RISK", score: 0 }
       ↓
Agent calls: sigil_approve("q_abc123")
       ↓
Agent: "left-pad@1.0.0 — no known malicious patterns
        detected (score 0). Installing now."

Agent calls: sigil_scan(".", phases: "all", severity: "medium")
       ↓
Sigil returns: { verdict: "LOW RISK", score: 4, findings_count: 2 }
       ↓
Agent: "Found 2 low-severity findings. No install hooks
or obfuscation detected. Review the flagged network
calls in src/api/client.js before proceeding."

Agent calls: sigil_clone("https://github.com/user/repo")
       ↓
Sigil returns: { verdict: "LOW RISK", score: 0, quarantine_id: "q_xyz" }
       ↓
Agent calls: sigil_approve("q_xyz")
       ↓
Agent: "Repo cloned and scanned. No findings.
Released from quarantine to ./repo."

Agent calls: sigil_quarantine()
       ↓
Sigil returns: { count: 3, items: [...] }
       ↓
Agent iterates:
  q_abc123 → score: 0  → sigil_approve("q_abc123")
  q_def456 → score: 47 → sigil_reject("q_def456")
  q_ghi789 → score: 3  → sigil_approve("q_ghi789")
       ↓
Agent: "Quarantine cleared. Approved 2, rejected 1
(high-risk item with score 47)."

Building agents with Sigil as a guardrail

Three patterns for integrating Sigil into autonomous agent workflows.

Agent system prompt:
"Before installing any package, always call
sigil_scan_package first. Only proceed with
installation if the verdict is LOW RISK.
For MEDIUM RISK or above, report findings to
the user and wait for explicit approval."

CI agent workflow:
1. sigil_scan(".", severity: "medium")
2. If score > threshold → block merge, post findings
3. If score ≤ threshold → approve, post summary
4. Attach full scan JSON as CI artifact

Manager agent loop:
1. sigil_quarantine() → list all items
2. For each item:
   - score = 0   → sigil_approve(id)
   - score > 0   → notify user, await decision
   - age > 7d    → sigil_reject(id), log cleanup
3. Sleep, repeat

Environment variables

Configure MCP server behavior through environment variables in your client config.

{
  "mcpServers": {
    "sigil": {
      "command": "node",
      "args": ["/path/to/plugins/mcp-server/dist/index.js"],
      "env": {
        "SIGIL_BINARY": "/usr/local/bin/sigil"
      }
    }
  }
}

Troubleshooting

# Check that sigil is installed and accessible
sigil --version

# If using a custom path, set SIGIL_BINARY
export SIGIL_BINARY=/usr/local/bin/sigil

# Verify the MCP server build exists
ls plugins/mcp-server/dist/index.js

Security considerations

• •All scans run locally — no source code is transmitted to external servers
• •Quarantine directory is isolated from your workspace until you explicitly approve
• •The MCP server does not require a network connection for local scans
• •Pro/Team API keys enable optional cloud threat intelligence enrichment

FAQ

What AI agents work with the Sigil MCP server?

Any agent that supports the Model Context Protocol — Claude Code, Cursor, Windsurf, and custom agents built with the MCP SDK.

Does the MCP server require a network connection?

No. All scans run locally on your machine. Network access is only needed for downloading packages via sigil_scan_package and optional cloud threat intelligence with Pro or Team plans.

What happens if a scan returns HIGH RISK?

The item stays in quarantine. The agent receives the verdict with findings and risk score. It should report the results to the user and wait for explicit approval before proceeding with installation.

Can the MCP server auto-approve LOW RISK packages?

Yes. Configure your agent system prompt to call sigil_approve automatically when the verdict is LOW RISK. See the agent workflow patterns section above for examples.