Troubleshooting Guide

Symptoms

• Error 404 when scanning a GitHub URL
• Cannot access repository

Possible Causes

• •The repository URL is incorrect or misspelled
• •The repository is private and you haven't authenticated
• •The repository has been deleted or renamed

Solutions

• Double-check the repository URL for typos
• For private repos, authenticate with GitHub OAuth in settings
• Verify the repository exists by visiting the URL directly

Symptoms

• Command not found: mcpsafe
• mcpsafe is not recognized

Possible Causes

• •CLI not installed globally
• •npm/node bin directory not in PATH
• •Installation failed silently

Solutions

• Reinstall with: npm install -g @mcpsafe/cli
• Check npm bin directory: npm bin -g
• Add npm bin to PATH: export PATH=$PATH:$(npm bin -g)

Example Fix

# Check if CLI is installed
npm list -g @mcpsafe/cli

# Reinstall if needed
npm install -g @mcpsafe/cli

# Verify installation
mcpsafe --version

Symptoms

• API returns 401 error
• Invalid API key message

Possible Causes

• •API key is missing or incorrect
• •API key has been revoked or expired
• •Wrong header format

Solutions

• Verify your API key in Settings → API Keys
• Regenerate a new API key if needed
• Ensure header is: Authorization: Bearer YOUR_KEY

Example Fix

# Check your environment variable
echo $MCPSAFE_API_KEY

# Test with curl
curl -H "Authorization: Bearer $MCPSAFE_API_KEY" \
  https://api.mcpsafe.org/api/v1/servers

Symptoms

• API returns 429 error
• Too many requests message

Possible Causes

• •Exceeded your plan's rate limit
• •Too many concurrent requests
• •Polling too frequently

Solutions

• Wait for the rate limit to reset (check Retry-After header)
• Implement exponential backoff in your code
• Use webhooks instead of polling
• Upgrade to a higher tier for increased limits

Symptoms

• Vulnerability reported that isn't actually vulnerable
• Safe code flagged as dangerous

Possible Causes

• •Static analysis limitations
• •Context not fully understood by scanner
• •Intentional use of dynamic patterns

Solutions

• Review the finding carefully to confirm it's a false positive
• Add a suppression comment in your config file
• Open an issue to help improve the rule

Example Fix

// In mcp.config.json
{
  "mcpsafe": {
    "rules": {
      "CMD001": "off"  // Disable specific rule
    },
    "ignore": [
      "**/*.test.ts"   // Ignore test files
    ]
  }
}

Symptoms

• Webhook URL not called
• No events received after scan

Possible Causes

• •Webhook URL is not HTTPS
• •Endpoint is not publicly accessible
• •Firewall blocking incoming requests
• •Endpoint returns non-2xx status

Solutions

• Ensure webhook URL uses HTTPS
• Verify endpoint is publicly accessible
• Check firewall/security group settings
• Test endpoint returns 200 status

Example Fix

# Test your webhook endpoint
curl -X POST https://your-webhook-url.com/mcpsafe \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Symptoms

• Upload SARIF step fails
• Permission denied error

Possible Causes

• •Missing security-events: write permission
• •SARIF file not generated
• •File path incorrect

Solutions

• Add permissions: security-events: write to your workflow
• Verify SARIF file exists before upload
• Check the output path matches the upload path

Example Fix

# In your GitHub Actions workflow
permissions:
  contents: read
  security-events: write

steps:
  - name: Run scan
    run: mcpsafe scan ./ --format sarif --output results.sarif
    continue-on-error: true

  - name: Upload SARIF
    uses: github/codeql-action/upload-sarif@v3
    with:
      sarif_file: results.sarif

Symptoms

• Badge shows old grade
• Score doesn't match latest scan

Possible Causes

• •Badge is cached by CDN or browser
• •Using wrong server slug
• •Scan hasn't completed yet

Solutions

• Add cache-busting parameter: ?v=timestamp
• Clear browser cache or use incognito mode
• Verify scan completed successfully
• Check you're using the correct server slug