License Activation Guide¶

This guide walks you through activating your Pro or Enterprise license for Code Scalpel.

Quick Start¶

Already have your license file? Follow these 3 steps:

1. Create the license directory:

   mkdir -p .code-scalpel/license
   

2. Place your license file:

   cp ~/Downloads/code_scalpel_license_*.jwt .code-scalpel/license/license.jwt
   

3. Verify activation:

   python -c "from code_scalpel.licensing.jwt_validator import get_current_tier; print(f'Active tier: {get_current_tier()}')"
   

Step-by-Step Activation¶

Step 1: Obtain Your License¶

If you don't have a license yet:

Step 2: Choose Installation Location¶

Code Scalpel searches for licenses in multiple locations (priority order):

Choose based on your setup:

mkdir -p ~/.config/code-scalpel
cp ~/Downloads/code_scalpel_license_*.jwt ~/.config/code-scalpel/license.jwt

mkdir -p .code-scalpel/license
cp /shared/licenses/team-license.jwt .code-scalpel/license/license.jwt
# Add to .gitignore
echo ".code-scalpel/license/" >> .gitignore

export CODE_SCALPEL_LICENSE_PATH=/secrets/license.jwt

Step 3: Install the License¶

Choose your installation method:

# Navigate to your project
cd /path/to/your/project

# Create license directory
mkdir -p .code-scalpel/license

# Copy license file (adjust source path as needed)
cp ~/Downloads/code_scalpel_license_pro_*.jwt .code-scalpel/license/license.jwt

# Verify file exists
ls -lh .code-scalpel/license/license.jwt

# Create config directory
mkdir -p ~/.config/code-scalpel

# Copy license file
cp ~/Downloads/code_scalpel_license_*.jwt ~/.config/code-scalpel/license.jwt

# Verify file exists
ls -lh ~/.config/code-scalpel/license.jwt

# Set environment variable (add to ~/.bashrc or ~/.zshrc for persistence)
export CODE_SCALPEL_LICENSE_PATH="$HOME/Downloads/code_scalpel_license_pro_20260209.jwt"

# Verify variable is set
echo $CODE_SCALPEL_LICENSE_PATH

docker run -v /path/to/license.jwt:/app/.code-scalpel/license/license.jwt \
  codescalpel/code-scalpel:latest

docker run -e CODE_SCALPEL_LICENSE_PATH=/secrets/license.jwt \
  -v /path/to/license.jwt:/secrets/license.jwt \
  codescalpel/code-scalpel:latest

Step 4: Verify License Activation¶

Check that your license is active:

from code_scalpel.licensing.jwt_validator import get_current_tier, JWTLicenseValidator

# Check tier
tier = get_current_tier()
print(f"Active tier: {tier}")

# Get detailed license info
validator = JWTLicenseValidator()
license_data = validator.validate()

if license_data.is_valid:
    print(f"✅ License valid!")
    print(f"   Tier: {license_data.tier}")
    print(f"   Organization: {license_data.organization}")
    print(f"   Expires: {license_data.expiration.strftime('%Y-%m-%d')}")
    print(f"   Days remaining: {license_data.days_until_expiration}")
else:
    print(f"❌ License invalid: {license_data.error_message}")

python -c "from code_scalpel.licensing.jwt_validator import get_current_tier; print(f'Active tier: {get_current_tier()}')"

uvx codescalpel mcp

INFO: License detected: Pro tier (expires 2026-12-31)
INFO: MCP server started with Pro tier capabilities

Expected Output:

• Community: Active tier: community
• Pro: Active tier: pro
• Enterprise: Active tier: enterprise

Using Your License with MCP Clients¶

Once your license is activated, it automatically works with all MCP clients. The license is detected when the Code Scalpel MCP server starts.

Claude Desktop¶

Your activated license works seamlessly with Claude Desktop:

1. Ensure license is installed (follow Step 3 above)

2. Configure Claude Desktop (if not already done):

{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "/Users/yourname/.config/code-scalpel/license.jwt"
      }
    }
  }
}

{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "C:\\Users\\YourName\\.config\\code-scalpel\\license.jwt"
      }
    }
  }
}

{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "/home/yourname/.config/code-scalpel/license.jwt"
      }
    }
  }
}

{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"]
    }
  }
}

3. Restart Claude Desktop

4. Verify tier in Claude:

Ask Claude: "What Code Scalpel tools are available?" and look for Pro/Enterprise-only tools like:

• get_call_graph with unlimited depth (Enterprise)
• cross_file_security_scan with high module limits (Pro/Enterprise)
• get_graph_neighborhood with advanced resolution (Pro)

Claude CLI (Terminal Interface)¶

Claude CLI is a command-line interface to Claude that runs directly in your terminal. Your license works automatically when Claude CLI starts the Code Scalpel MCP server.

1. Install Claude CLI (if not already installed):

# Using pip
pip install claude-cli

# Or using Homebrew (macOS/Linux)
brew install anthropics/claude/claude-cli

2. Configure MCP servers for Claude CLI:

Edit: ~/.config/claude/config.json (create if it doesn't exist)

{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "/home/yourname/.config/code-scalpel/license.jwt"
      }
    }
  }
}

Alternative: Project-specific configuration:

Create .claude/config.json in your project directory:

{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "./.code-scalpel/license/license.jwt"
      }
    }
  }
}

{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"]
    }
  }
}

3. Start Claude CLI with MCP servers:

# Start Claude CLI (automatically loads MCP servers)
claude

# Or start with specific project
cd /path/to/your/project
claude

4. Verify tier in Claude CLI:

You: What Code Scalpel tier am I using?

Claude: Let me check... [calls get_capabilities tool]
You're using Code Scalpel Pro tier (expires 2026-12-31).

5. Test Pro/Enterprise features:

You: Use get_call_graph to analyze this project with depth=20

Claude: [Successfully creates call graph with depth=20]

You: Use cross_file_security_scan on this entire codebase

Claude: [Scans all files for cross-module vulnerabilities]

Common CLI-specific scenarios:

# Place license in user config directory
mkdir -p ~/.config/code-scalpel
cp ~/Downloads/code_scalpel_license_*.jwt ~/.config/code-scalpel/license.jwt

# Configure Claude CLI
cat > ~/.config/claude/config.json << 'EOF'
{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"]
    }
  }
}
EOF

# Start Claude from any project
cd /any/project
claude

# Place license in project
cd /path/to/project
mkdir -p .code-scalpel/license
cp ~/Downloads/team-license.jwt .code-scalpel/license/license.jwt

# Configure project-specific Claude settings
mkdir -p .claude
cat > .claude/config.json << 'EOF'
{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"]
    }
  }
}
EOF

# Start Claude (uses project license)
claude

# Export license path for current session
export CODE_SCALPEL_LICENSE_PATH="$HOME/licenses/my-pro-license.jwt"

# Start Claude CLI
claude

# Or inline
CODE_SCALPEL_LICENSE_PATH="~/licenses/pro.jwt" claude

CLI-specific troubleshooting:

Issue: "License works in Claude Desktop but not in Claude CLI"

Cause: Different config files (claude_desktop_config.json vs config.json)

Solution: Configure both:

# Claude Desktop config
cp ~/Library/Application\ Support/Claude/claude_desktop_config.json ~/Desktop/backup.json

# Claude CLI config
mkdir -p ~/.config/claude
cat > ~/.config/claude/config.json << 'EOF'
{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "/Users/yourname/.config/code-scalpel/license.jwt"
      }
    }
  }
}
EOF

Issue: "License detected when running Python directly but not via Claude CLI"

Cause: Claude CLI may start MCP server with different working directory

Solution: Use absolute path for license:

{
  "mcpServers": {
    "code-scalpel": {
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "/home/yourname/.config/code-scalpel/license.jwt"
      }
    }
  }
}

Viewing MCP server logs in Claude CLI:

# Start Claude CLI with debug logging
claude --verbose

# Or set environment variable
export CLAUDE_DEBUG=1
claude

Look for:

[MCP] Starting server: code-scalpel
[MCP] code-scalpel: License detected: Pro tier (expires 2026-12-31)
[MCP] code-scalpel: Server ready with 23 tools

GitHub Copilot (VS Code)¶

Your license works automatically when Copilot uses Code Scalpel as an MCP server:

1. Install the MCP extension (if not already done):

code --install-extension modelcontextprotocol.mcp

2. Configure workspace settings (.vscode/settings.json):

{
  "mcp.servers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "${workspaceFolder}/.code-scalpel/license/license.jwt"
      }
    }
  }
}

Alternative: User settings (for all workspaces):

Press Ctrl+Shift+P → "Preferences: Open User Settings (JSON)" and add:

{
  "mcp.servers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "/full/path/to/license.jwt"
      }
    }
  }
}

3. Reload VS Code window

Cline (VS Code Extension)¶

Cline can use your activated Code Scalpel license via MCP:

1. Open Cline settings in VS Code

2. Add MCP server configuration:

{
  "cline.mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "${workspaceFolder}/.code-scalpel/license/license.jwt"
      }
    }
  }
}

3. Restart Cline or reload VS Code

Continue.dev (VS Code Extension)¶

Configure Code Scalpel as an MCP server in Continue:

1. Open Continue settings: ~/.continue/config.json

2. Add to mcpServers section:

{
  "mcpServers": [
    {
      "name": "code-scalpel",
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "/home/yourname/.config/code-scalpel/license.jwt"
      }
    }
  ]
}

3. Restart Continue extension

Zed Editor¶

Zed has native MCP support. Configure Code Scalpel in your Zed settings:

1. Open Zed settings: ~/.config/zed/settings.json

2. Add MCP server:

{
  "context_servers": {
    "code-scalpel": {
      "command": {
        "path": "python",
        "args": ["codescalpel", "mcp"]
      },
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "/home/yourname/.config/code-scalpel/license.jwt"
      }
    }
  }
}

3. Restart Zed

Windsurf Editor¶

Windsurf can integrate Code Scalpel via MCP:

1. Open Windsurf settings

2. Configure MCP server:

{
  "mcp": {
    "servers": {
      "code-scalpel": {
        "command": "uvx",
        "args": ["codescalpel", "mcp"],
        "env": {
          "CODE_SCALPEL_LICENSE_PATH": "/Users/yourname/.config/code-scalpel/license.jwt"
        }
      }
    }
  }
}

3. Restart Windsurf

Cody (Sourcegraph)¶

Cody can use Code Scalpel as an MCP context provider:

1. Configure in VS Code settings (.vscode/settings.json):

{
  "cody.experimental.mcp.servers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "${workspaceFolder}/.code-scalpel/license/license.jwt"
      }
    }
  }
}

2. Enable MCP in Cody settings

3. Reload VS Code

Custom MCP Clients¶

For any MCP client that supports server configuration:

{
  "command": "uvx",
  "args": ["codescalpel", "mcp"],
  "env": {
    "CODE_SCALPEL_LICENSE_PATH": "/path/to/license.jwt"
  }
}

Key points:

• Command: uvx codescalpel mcp
• Environment: Optional CODE_SCALPEL_LICENSE_PATH (required if license not in standard location)
• Working Directory: Set to your project root for best results
• Transport: Default is stdio (standard input/output)

Verifying License in MCP Clients¶

To confirm your license is active in any MCP client:

1. Ask the AI assistant:

What Code Scalpel tier am I using?

2. Request tier-specific features:

3. Check MCP server logs:

Most MCP clients show server logs. Look for:

INFO: Code Scalpel MCP Server v1.4.0
INFO: License detected: Pro tier (expires 2026-12-31)
INFO: MCP server ready with 23 tools

Common MCP Client Issues¶

Issue: "License detected locally but not in Claude Desktop"¶

Cause: Claude Desktop doesn't inherit your shell environment variables.

Solution: Explicitly set CODE_SCALPEL_LICENSE_PATH in claude_desktop_config.json:

{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"],
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "/Users/yourname/.config/code-scalpel/license.jwt"
      }
    }
  }
}

Issue: "Community tier in VS Code, Pro tier in terminal"¶

Cause: VS Code workspace has different working directory or environment.

Solution: Use absolute path in .vscode/settings.json:

{
  "mcp.servers": {
    "code-scalpel": {
      "env": {
        "CODE_SCALPEL_LICENSE_PATH": "/home/yourname/.config/code-scalpel/license.jwt"
      }
    }
  }
}

Issue: "License works in Zed but not in Continue"¶

Cause: Each client has different working directory when launching MCP server.

Solution: Use user-wide license location (~/.config/code-scalpel/license.jwt) instead of project-specific location.

MCP Server Environment Variables¶

When configuring any MCP client, you can set these environment variables:

Example with all variables:

{
  "command": "uvx",
  "args": ["codescalpel", "mcp"],
  "env": {
    "CODE_SCALPEL_LICENSE_PATH": "/home/user/.config/code-scalpel/license.jwt",
    "CODE_SCALPEL_ROOT": "${workspaceFolder}",
    "CODE_SCALPEL_LOG_LEVEL": "INFO"
  }
}

Troubleshooting¶

❌ "No license found" (defaulting to Community)¶

Cause: License file not in expected location.

Solutions:

1. Check file location:

   # Is the file where you think it is?
   ls -lh .code-scalpel/license/license.jwt
   ls -lh ~/.config/code-scalpel/license.jwt
   

2. Check file permissions:

   # File must be readable
   chmod 644 .code-scalpel/license/license.jwt
   

3. Use explicit path:

   export CODE_SCALPEL_LICENSE_PATH="/full/path/to/license.jwt"
   

4. Check directory structure:

   # Correct structure
   .code-scalpel/
   └── license/
       └── license.jwt    ← File here
   
   # NOT this
   .code-scalpel/
   └── license/
       └── license/       ← Extra folder
           └── license.jwt
   

❌ "Invalid token format" or "Failed to decode license"¶

Cause: Corrupted or incomplete license file.

Solutions:

1. Check file contents:

   # JWT should be a single line, no line breaks
   head -n 1 .code-scalpel/license/license.jwt
   

Valid format:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0...  (long string, no spaces)

1. Re-download the license:
2. Original file may have been corrupted during download

3. Check your email for fresh download link

4. Remove hidden characters:

   # Remove trailing whitespace/newlines
   cat license.jwt | tr -d '\n\r' > license-clean.jwt
   mv license-clean.jwt license.jwt
   

❌ "Invalid signature - license may be tampered"¶

Cause: License signature verification failed.

Solutions:

1. Check file integrity:

   # License should start with "eyJ"
   head -c 10 .code-scalpel/license/license.jwt
   # Should output: eyJhbGciOi
   

2. Verify it's a valid JWT:

3. Paste your license into jwt.io

4. Should show header + payload (don't share the full token publicly!)

5. Re-download from trusted source:

6. License may have been modified

7. Get fresh copy from original email

8. Check system time:

   # System clock must be accurate for JWT validation
   date
   # If wrong, sync with NTP
   sudo ntpdate -s time.nist.gov  # Linux
   sudo sntp -sS time.apple.com   # macOS
   

❌ "License expired X days ago"¶

Cause: License expiration date has passed.

Solutions:

1. Check expiration date:

   from code_scalpel.licensing.jwt_validator import JWTLicenseValidator
   
   validator = JWTLicenseValidator()
   license_data = validator.validate()
   print(f"Expires: {license_data.expiration}")
   print(f"Days until expiration: {license_data.days_until_expiration}")
   

2. Grace period (7 days):

3. Expired licenses work for 7 days after expiration

4. Renew before grace period ends

5. Renew license:

6. Pro: Automatic renewal via Stripe (check billing settings)
7. Enterprise: Contact your account manager

8. Beta: Request extension via beta program

9. Emergency access (Community tier):

   # Remove license to fall back to Community tier
   mv .code-scalpel/license/license.jwt .code-scalpel/license/expired-license.jwt.backup
   

❌ "PyJWT not installed"¶

Cause: Missing dependency for Pro/Enterprise license validation.

Solution:

# Install PyJWT and cryptography
pip install PyJWT cryptography

# Or reinstall Code Scalpel with all dependencies
pip install --upgrade codescalpel

❌ License works locally but not in CI/CD¶

Cause: License file not accessible in container/CI environment.

Solutions:

1. GitHub Actions:

   - name: Setup Code Scalpel License
     env:
       LICENSE_JWT: ${{ secrets.CODESCALPEL_LICENSE }}
     run: |
       mkdir -p .code-scalpel/license
       echo "$LICENSE_JWT" > .code-scalpel/license/license.jwt
   

2. GitLab CI:

   before_script:
     - mkdir -p .code-scalpel/license
     - echo "$CODESCALPEL_LICENSE" > .code-scalpel/license/license.jwt
   
   variables:
     CODE_SCALPEL_LICENSE_PATH: ".code-scalpel/license/license.jwt"
   

3. Docker:

   # Copy license during build (for private images only)
   COPY license.jwt /app/.code-scalpel/license/license.jwt
   
   # Or inject at runtime via volume/secret
   

Advanced Configuration¶

Multiple Organizations (Enterprise)¶

If you work with multiple Enterprise organizations:

# Project A (Org 1)
cd /projects/project-a
mkdir -p .code-scalpel/license
cp ~/licenses/org1-license.jwt .code-scalpel/license/license.jwt

# Project B (Org 2)
cd /projects/project-b
mkdir -p .code-scalpel/license
cp ~/licenses/org2-license.jwt .code-scalpel/license/license.jwt

Each project will use its own organization's license.

License Verification Logs¶

Enable debug logging to troubleshoot license issues:

import logging
logging.basicConfig(level=logging.DEBUG)

from code_scalpel.licensing.jwt_validator import JWTLicenseValidator

validator = JWTLicenseValidator()
license_data = validator.validate()

Look for these log messages:

• Found license file: .code-scalpel/license/license.jwt ✅
• No license file found in standard locations ⚠️
• Invalid license signature ❌
• License expired X days ago ⚠️

License Caching¶

Code Scalpel caches license validation results for 24 hours to avoid repeated cryptographic operations.

Cache behavior:

• Cache key: File path + modification time + file size + CRL state
• Cache duration: 24 hours
• Cache invalidation: Automatic when license file changes

Force re-validation:

# Modify the file timestamp
touch .code-scalpel/license/license.jwt

# Or restart the MCP server

Security Best Practices¶

✅ Do:¶

1. Store licenses in .gitignore:

   echo ".code-scalpel/license/" >> .gitignore
   echo "**/*.jwt" >> .gitignore
   

2. Use environment variables in CI/CD:

3. Store license as secret (GitHub Secrets, GitLab Variables, etc.)

4. Inject at runtime, never commit

5. Restrict file permissions:

   chmod 600 .code-scalpel/license/license.jwt  # Owner read/write only
   

6. Rotate licenses periodically:

7. Enterprise: Annual renewal recommended
8. Pro: Automatic Stripe renewal

❌ Don't:¶

1. Never commit licenses to version control:

   # BAD - don't do this
   git add .code-scalpel/license/license.jwt
   

2. Never share license files publicly:

3. Don't paste in Slack, Discord, forums

4. Don't share in screenshots

5. Never use production licenses in development:

6. Request separate dev/staging licenses from Enterprise account manager

7. Don't hardcode licenses in code:

   # BAD - don't do this
   license = "eyJhbGciOiJSUzI1NiIsInR5..."
   

License Tiers Comparison¶

FAQ¶

Q: Can I use one Pro license across multiple machines?¶

A: Yes! Pro licenses are user-based, not machine-based. Install the same license.jwt file on all your development machines.

Q: What happens if my license expires during a long-running analysis?¶

A: Code Scalpel checks license status on startup and every 24 hours. A long-running analysis will complete, but new analyses will require license renewal.

Q: Can I upgrade from Pro to Enterprise?¶

A: Yes! Contact sales@codescalpel.dev. Your new Enterprise license will replace your Pro license—just overwrite the JWT file.

Q: Does Community tier require a license file?¶

A: No! Community tier works without any license. If Code Scalpel finds no valid license, it automatically falls back to Community tier (which is free forever).

Q: Where can I see my license details?¶

A: Decode your JWT at jwt.io to see: - Tier (pro/enterprise) - Expiration date - Organization - Features enabled - Customer ID

Q: My license was revoked. What should I do?¶

A: Contact support@codescalpel.dev immediately. License revocation typically occurs due to: - Payment failure (Pro tier) - Contract termination (Enterprise tier) - Terms of service violation

Getting Help¶

If you're still having issues with license activation:

• 📧 Email: support@codescalpel.dev
• 💬 Discord: discord.gg/codescalpel
• 📚 Docs: codescalpel.dev/docs
• 🐛 GitHub Issues: github.com/code-scalpel/code-scalpel/issues

Include in your support request:

1. Tier you're trying to activate (Pro/Enterprise)
2. Output of activation verification script
3. Any error messages from logs
4. Operating system and Python version

Next Steps¶

Once your license is activated:

• ✅ Explore Pro/Enterprise tools
• ✅ Set up team deployment
• ✅ Enable compliance reporting