ShakerScan MCP Server

A Model Context Protocol (MCP) server for the Shaker Scan control plane. It lets AI assistants like Claude and Cursor trigger scans, inspect findings, and plug security checks into agent workflows without leaving the IDE.

Features

Tools

| Tool | Description | | ----------------------- | ------------------------------------------------------------------ | | scan_target | Trigger a DAST scan against any URL | | get_scan_status | Check scan progress and completion | | get_findings | Retrieve vulnerability findings with severity, CVSS, OWASP mapping | | verify_finding | Retest a stored finding and persist a verification artifact | | evaluate_policy | Return allow, block, or needs_approval for a scan | | get_evidence | Fetch a stored verification or policy artifact | | issue_approval_token | Mint a short-lived signed approval token | | verify_approval_token | Validate a signed approval token | | request_remediation | Create a persisted remediation artifact with fix steps and PR draft | | get_remediation_job | Fetch a stored remediation artifact | | get_usage | Read current scan, verify, policy, and API usage | | list_scans | List recent scans, filter by target | | compare_scans | Compare two scans to find new/resolved issues | | get_scan_history | View historical security posture for a domain | | list_targets | List configured DAST monitoring targets |

Resources

• OWASP Top 10 (2021) - Reference guide for web security risks
• Severity Guide - How vulnerabilities are classified
• Scan Types Guide - Understanding different scan modes and phases

Prompts

• quick_security_check - Fast scan with summarized results
• comprehensive_audit - Full security audit with all phases
• fix_vulnerability - Remediation guidance for specific vuln types
• security_comparison - Analyze security trends over time

Installation

For End Users (via npx)

No installation required. The default configuration path is npx -y shakerscan-mcp.

For Development

cd scanner-mcp
npm install
npm run build

Getting Your API Key

1. Log in to shakerscan.com
2. Go to Control Plane Settings > API Keys
3. Click New API Key
4. Copy the key (starts with sk_live_)

API keys are available for all authenticated users.

Configuration

Environment Variables

# Required - your API key from shakerscan.com
export SCANNER_API_KEY="sk_live_your_key_here"

# Optional - override API URL (defaults to shakerscan.com for sk_live_ keys)
# export SCANNER_API_URL="https://shakerscan.com"

Claude Code Configuration

Add to ~/.claude.json:

{
  "mcpServers": {
    "shakerscan": {
      "command": "npx",
      "args": ["-y", "shakerscan-mcp"],
      "env": {
        "SCANNER_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Cursor Configuration

Add to Cursor's MCP settings (Settings → MCP):

{
  "mcpServers": {
    "shakerscan": {
      "command": "npx",
      "args": ["-y", "shakerscan-mcp"],
      "env": {
        "SCANNER_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Alternative: Global Install

npm install -g shakerscan-mcp

Then use "command": "shakerscan-mcp" instead of npx.

How It Hooks Into Agent Workflows

Shaker plugs into agentic workflows in two layers:

1. MCP provides executable tools.
2. A skill or workflow prompt tells the agent when to use those tools and how to make a gate decision.

Recommended pattern:

• Claude Code / Cursor: configure MCP with shakerscan-mcp
• Codex-style agents: pair MCP or direct HTTP with the repo skill at skills/shakerscan-agent-gate/
• CI pipelines: call the same API routes directly

Recommended control-plane flow:

• scan_target
• get_scan_status
• get_findings
• verify_finding on critical and high findings that support deterministic retesting
• evaluate_policy for the deploy decision pass a policy_pack such as preview-fast, release-strict, or a tenant custom pack when the workflow should not rely on the workspace default
• get_evidence to attach the artifact to CI, a PR, or an audit log
• issue_approval_token when an allow decision needs a downstream proof object
• request_remediation when you need a durable fix plan, patch suggestion, and PR draft for blocked findings

Concrete assets in this repo:

• scanner-mcp/examples/github-actions-preview-gate.yml
• skills/shakerscan-agent-gate/SKILL.md
• skills/shakerscan-agent-gate/references/workflows.md

Usage Examples

Quick Security Check

You: "Scan https://example.com for security issues"

Claude: [Uses scan_target tool]
        [Uses get_scan_status to wait]
        [Uses get_findings to retrieve results]

        "The scan completed with a grade of B (82/100).
         Found 3 medium severity issues:
         1. Missing Content-Security-Policy header
         2. HSTS max-age is below recommended value
         3. Cookie missing SameSite attribute

         Recommendations: ..."

Comprehensive Audit

You: "Run a full security audit on my staging server https://staging.myapp.com"

Claude: [Uses scan_target with all phases enabled]
        [Monitors progress with get_scan_status]
        [Retrieves and analyzes findings]

        "Comprehensive audit complete. Grade: C (71/100)

         Critical Issues:
         - SQL injection in /api/search endpoint

         High Issues:
         - XSS vulnerability in comment form
         - Missing rate limiting on login

         Remediation roadmap: ..."

Track Security Over Time

You: "How has our security improved since last month?"

Claude: [Uses get_scan_history for domain]
        [Uses compare_scans on oldest vs newest]

        "Security has improved! Score increased from 65 to 82.

         Resolved:
         - SQL injection (critical)
         - 2 XSS vulnerabilities (high)

         New issues:
         - 1 medium severity header misconfiguration

         Trend: Improving"

Fix a Vulnerability

You: "Help me fix the XSS vulnerability in our React app"

Claude: [Uses fix_vulnerability prompt]

        "XSS (Cross-Site Scripting) allows attackers to inject
         malicious scripts. Here's how to fix it:

         Vulnerable pattern:
         ```jsx
         <div dangerouslySetInnerHTML={{__html: userInput}} />
         ```

         Secure pattern:
         ```jsx
         import DOMPurify from 'dompurify';
         <div dangerouslySetInnerHTML={{__html: DOMPurify.sanitize(userInput)}} />
         ```

         Additional hardening: ..."

Vulnerability Categories

| Category | Flag | Checks Included | | ----------------------- | ----------------- | ---------------------------------------------------------------------------------------------- | | Authentication & Access | vuln_auth | CSRF, IDOR, Default Credentials, Rate Limiting, 2FA Bypass, Password Reset, Session Management | | Injection | vuln_injection | Path Traversal, Deserialization | | Web Application | vuln_web | File Upload, Open Redirect, Host Header, Business Logic, API Security | | Client-Side Exposure | exposure_client | JS Dependencies, JS Secrets | | Infrastructure Exposure | exposure_infra | CI/CD Exposure, Cloud Buckets, Backups, Package Files | | Threat Intelligence | threat_intel | IP Reputation, Breach Check, Vendor Risk, Typosquatting |

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Test with MCP Inspector
npm run inspect

Architecture

┌─────────────────────────────────────┐
│   Claude Code / Cursor / IDE        │
└──────────────────┬──────────────────┘
                   │ JSON-RPC (stdio)
┌──────────────────▼──────────────────┐
│      ShakerScan MCP Server          │
│  ┌─────────┐ ┌─────────┐ ┌───────┐  │
│  │  Tools  │ │Resources│ │Prompts│  │
│  └────┬────┘ └─────────┘ └───────┘  │
└───────┼─────────────────────────────┘
        │ HTTPS + API Key (sk_live_*)
┌───────▼─────────────────────────────┐
│   ShakerScan Web App v1 API          │
│   /api/v1/scan, /api/v1/scans,       │
│   /api/v1/findings                   │
└───────┬─────────────────────────────┘
        │
┌───────▼─────────────────────────────┐
│   AWS Scanner Infrastructure         │
│   Lambda/ECS + S3                    │
└───────┬─────────────────────────────┘
        │
┌───────▼─────────────────────────────┐
│   Supabase (PostgreSQL)              │
│   Scans, Findings, API Keys          │
└─────────────────────────────────────┘

License

MIT