QUICK START GUIDE

Get MCPShield up and running in under 5 minutes

INSTALLATION

Option 1: From npm (Recommended)

MCPShield is now available on npm. Install globally to use the CLI:

# Install CLI globally
npm install -g @kellyclaude/mcpshield

# Verify installation
mcp-shield --version

Option 2: From Source

Build from source for development or testing:

# Clone the repository
git clone https://github.com/kellyclaudeai/mcpshield.git
cd mcpshield

# Install dependencies
npm install

# Build the project
npm run build

# Link CLI globally
npm link packages/cli

# Verify installation
mcp-shield --version

BASIC USAGE

Step 1: Initialize MCPShield

Navigate to your project directory and initialize MCPShield:

cd ~/my-mcp-project
mcp-shield init

This creates two files:

• mcp.lock.json - Lockfile tracking all verified servers
• policy.yaml - Security policy configuration

Step 2: Add an MCP Server

Add a server from the MCP Registry:

mcp-shield add io.github.modelcontextprotocol/filesystem

MCPShield will:

1. Fetch metadata from the MCP Registry
2. Verify namespace ownership (GitHub)
3. Download and verify artifacts (npm packages)
4. Run comprehensive security scan
5. Show results and prompt for approval
6. Add to mcp.lock.json if approved

mcp-shield add io.github.user/server-name --yes

Step 3: Verify Servers

Re-verify all servers in your lockfile:

mcp-shield verify

This command:

• Downloads artifacts from cache or registry
• Verifies SHA-512 digests match lockfile
• Reports any drift detected

Step 4: Run Security Scan

Scan all servers for security issues:

mcp-shield scan

The scanner checks for:

• Typosquatting attacks
• Suspicious code patterns (eval, exec)
• Malicious network calls
• Dangerous dependencies
• Install script exploits

EXAMPLE WORKFLOW

# Initialize in your project
cd ~/my-ai-app
mcp-shield init

# Add trusted servers
mcp-shield add io.github.modelcontextprotocol/filesystem
mcp-shield add io.github.modelcontextprotocol/brave-search

# Verify everything is secure
mcp-shield verify
mcp-shield scan

# Check lockfile
cat mcp.lock.json

UNDERSTANDING THE LOCKFILE

The mcp.lock.json file tracks all verified servers:

{
  "version": "1.0.0",
  "generatedAt": "2026-02-05T15:30:00.000Z",
  "servers": {
    "io.github.modelcontextprotocol/filesystem": {
      "namespace": "io.github.modelcontextprotocol/filesystem",
      "version": "1.0.0",
      "verified": true,
      "verificationMethod": "github",
      "verifiedOwner": "modelcontextprotocol",
      "fetchedAt": "2026-02-05T15:30:00.000Z",
      "artifacts": [
        {
          "type": "npm",
          "url": "https://registry.npmjs.org/...",
          "digest": "sha512-abc123...",
          "size": 45678
        }
      ]
    }
  }
}

SECURITY SCAN OUTPUT

When you run mcp-shield scan, you'll see:

📊 Security Scan Results:

io.github.modelcontextprotocol/filesystem
  Risk Score: 15/100 (clean)
  Verdict: ✅ CLEAN

  ✓ No typosquats detected
  ✓ No suspicious code patterns
  ✓ Dependencies verified
  ℹ️ 12 dependencies scanned

io.github.suspicious/package
  Risk Score: 75/100 (suspicious)
  Verdict: ⚠️ WARNING

  ⚠️ eval() detected in src/core.js:45
  ⚠️ Network call to unverified endpoint
  ⚠️ Install script present

Summary:
  Total servers: 2
  Clean: 1
  Warnings: 1
  Dangerous: 0

POLICY CONFIGURATION

The policy.yaml file lets you define security policies:

version: 1.0.0

policies:
  # Block packages above this risk score
  maxRiskScore: 50

  # Require namespace verification
  requireVerification: true

  # Block known malicious patterns
  blockPatterns:
    - eval
    - exec
    - child_process

  # Allowed registries
  allowedRegistries:
    - registry.npmjs.org
    - pypi.org

  # Auto-approve verified publishers
  trustedPublishers:
    - modelcontextprotocol

NEXT STEPS

• Read the full documentation
• Try the interactive demo
• Explore example configurations
• Join the community on GitHub Discussions
• Report issues on GitHub Issues

COMMON ISSUES

Command not found: mcp-shield

Make sure you've installed the package globally:

npm install -g @kellyclaude/mcpshield

If installing from source, link the CLI:

cd /path/to/mcpshield
npm link packages/cli

Cannot fetch server metadata

Ensure the server exists in the MCP Registry:

curl https://registry.modelcontextprotocol.io/servers/io.github.user/server-name

Verification failed

The server may not have a valid GitHub repository. Check the namespace format and repository ownership.

NEED HELP?

If you run into issues:

• Check the documentation
• Search existing issues
• Ask on GitHub Discussions
• Open a new issue