MCP Authentication & Security¶

This guide covers authentication, authorization, and security considerations for Code Scalpel MCP server deployments.

Current Security Implementation¶

✅ Implemented Features¶

❌ Not Yet Implemented¶

Authentication Architecture¶

Current: License-Based Authorization¶

Code Scalpel currently implements authorization (feature access control) but not authentication (identity verification) for HTTP endpoints.

┌─────────────┐
│   Client    │
└──────┬──────┘
       │ No authentication required
       │ for HTTP endpoints
       ▼
┌─────────────┐
│ Code Scalpel│
│ MCP Server  │
└──────┬──────┘
       │ License validation
       │ determines tier
       ▼
┌─────────────┐
│   Tools     │
│ (Tier-gated)│
└─────────────┘

What this means: - Anyone who can reach the HTTP endpoint can use the server - License validates what features are available (Pro/Enterprise) - No way to restrict who can connect remotely

Needed: Request Authentication¶

For production remote deployments, you need authentication:

┌─────────────┐
│   Client    │
└──────┬──────┘
       │ Authorization: Bearer <token>
       ▼
┌─────────────┐
│   Proxy     │◄─── Authentication
│ (nginx/Caddy)│     middleware
└──────┬──────┘
       │ Authenticated
       ▼
┌─────────────┐
│ Code Scalpel│◄─── License validation
│ MCP Server  │     (authorization)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Tools     │
└─────────────┘

Deployment Scenarios & Security¶

Scenario 1: Local Development (stdio)¶

Security Profile: Maximum

• Client spawns server as subprocess
• Process-level isolation
• No network exposure
• No authentication needed

Configuration:

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

Risk Level: 🟢 Low - Runs in user's context with their permissions

Scenario 2: Docker Local (stdio)¶

Security Profile: High

• Container isolation
• Read-only volume mounts
• No network exposure

Configuration:

{
  "mcpServers": {
    "code-scalpel": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "${workspaceFolder}:/workspace:ro",
        "code-scalpel:latest", "mcp"
      ]
    }
  }
}

Risk Level: 🟢 Low - Isolated in container with limited permissions

Scenario 3: HTTP on Localhost (Development)¶

Security Profile: Medium

• Network socket on localhost
• Accessible to all local processes
• No authentication

Configuration:

# Server
codescalpel mcp --transport sse --host 127.0.0.1 --port 8080

# Client
{
  "mcpServers": {
    "code-scalpel": {
      "url": "http://localhost:8080/sse",
      "transport": "sse"
    }
  }
}

Risk Level: 🟡 Medium - Any local process can connect

Mitigation: - Use on development machines only - Don't expose port to network - Run on non-standard port

Scenario 4: HTTP on LAN (Team Network)¶

Security Profile: Medium-Low

• Exposed to local network
• Anyone on network can connect
• No authentication

Configuration:

# Server (INSECURE - do not use in untrusted networks)
codescalpel mcp --transport sse --host 0.0.0.0 --port 8080 --allow-lan

Risk Level: 🟠 Medium-High - Network-accessible without authentication

Current Workarounds:

Option A: Use VPN

# Server on private IP
codescalpel mcp --transport sse --host 10.0.1.100 --port 8080 --allow-lan

# Clients connect via VPN
# VPN provides network-level authentication

Option B: SSH Tunnel

# Client creates tunnel to server
ssh -L 8080:localhost:8080 user@server

# Client connects to localhost
# SSH provides authentication

Option C: Reverse Proxy with Authentication (Recommended)

See Reverse Proxy Guide below.

Scenario 5: Public Cloud (Production)¶

Security Profile: Low (without authentication)

• Exposed to internet
• NEVER deploy without authentication
• Requires HTTPS + authentication

Current Limitation: ⚠️ NOT RECOMMENDED without reverse proxy

Required Setup: 1. HTTPS (not optional) 2. Reverse proxy with authentication 3. Firewall rules

See Production Deployment below.

Reverse Proxy Authentication¶

Until Code Scalpel implements native HTTP authentication, use a reverse proxy.

Option 1: nginx with Basic Auth (Simplest)¶

1. Generate password file¶

# Install htpasswd
sudo apt-get install apache2-utils  # Debian/Ubuntu
sudo yum install httpd-tools         # CentOS/RHEL

# Create password for user
htpasswd -c /etc/nginx/.htpasswd username

2. Configure nginx¶

# /etc/nginx/sites-available/code-scalpel
upstream code_scalpel {
    server 127.0.0.1:8080;
}

server {
    listen 443 ssl http2;
    server_name code-scalpel.example.com;

    ssl_certificate /etc/ssl/certs/code-scalpel.crt;
    ssl_certificate_key /etc/ssl/private/code-scalpel.key;

    # Modern SSL configuration
    ssl_protocols TLSv1.3 TLSv1.2;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    location / {
        # Basic authentication
        auth_basic "Code Scalpel MCP";
        auth_basic_user_file /etc/nginx/.htpasswd;

        # Proxy to Code Scalpel
        proxy_pass http://code_scalpel;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Disable buffering for SSE
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400;
    }
}

3. Enable and restart¶

sudo ln -s /etc/nginx/sites-available/code-scalpel /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

4. Client configuration¶

Most MCP clients don't support Basic Auth natively. You need to:

Option A: Use curl with auth (for testing)

curl -u username:password https://code-scalpel.example.com/sse

Option B: Use Cloudflare Tunnel (for Claude Desktop)

See Cloudflare Tunnel below.

Option 2: Caddy with Automatic HTTPS¶

Caddy is simpler than nginx and handles HTTPS automatically.

1. Install Caddy¶

# Debian/Ubuntu
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sSL 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sSL 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

2. Configure Caddyfile¶

# /etc/caddy/Caddyfile
code-scalpel.example.com {
    # Basic authentication
    basicauth {
        username $2a$14$<bcrypt_hash>
    }

    # Reverse proxy to Code Scalpel
    reverse_proxy localhost:8080 {
        # Disable buffering for SSE
        flush_interval -1
    }
}

Generate bcrypt hash:

caddy hash-password

3. Start Caddy¶

sudo systemctl restart caddy

Caddy automatically: - Obtains Let's Encrypt certificates - Renews certificates - Redirects HTTP to HTTPS

Option 3: Cloudflare Tunnel (Best for Remote Access)¶

Cloudflare Tunnel provides zero-trust authentication without exposing your server.

1. Install cloudflared¶

# Linux (Debian/Ubuntu)
wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb

# macOS
brew install cloudflare/cloudflare/cloudflared

2. Authenticate with Cloudflare¶

cloudflared tunnel login

3. Create tunnel¶

cloudflared tunnel create code-scalpel
# Note the tunnel ID

4. Configure tunnel¶

# ~/.cloudflared/config.yml
tunnel: <tunnel-id>
credentials-file: /home/user/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: code-scalpel.example.com
    service: http://localhost:8080
  - service: http_status:404

5. Route DNS¶

cloudflared tunnel route dns code-scalpel code-scalpel.example.com

6. Run tunnel¶

cloudflared tunnel run code-scalpel

7. Configure Cloudflare Access¶

In Cloudflare dashboard: 1. Go to Zero Trust → Access → Applications 2. Add application for code-scalpel.example.com 3. Configure authentication policies (email, GitHub, Google, etc.)

Advantages: - Zero-trust authentication - No port forwarding needed - No SSL certificate management - Works with any OAuth provider - Free for personal use

Client Configuration:

{
  "mcpServers": {
    "code-scalpel": {
      "url": "https://code-scalpel.example.com/sse",
      "transport": "sse"
    }
  }
}

Clients authenticate via browser on first connection.

Production Deployment with Authentication¶

Complete Stack Recommendation¶

For production Code Scalpel deployments:

┌──────────────────┐
│  User/AI Client  │
└────────┬─────────┘
         │ HTTPS
         ▼
┌──────────────────┐
│ Cloudflare Tunnel│◄─── OAuth authentication
│   or nginx       │     Rate limiting
└────────┬─────────┘     DDoS protection
         │
         ▼
┌──────────────────┐
│  Code Scalpel    │◄─── License validation
│   MCP Server     │     (Pro/Enterprise tiers)
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│   Your Code      │
│  (Read-Only)     │
└──────────────────┘

Deployment Checklist¶

• Start Code Scalpel on localhost

  codescalpel mcp --transport sse --host 127.0.0.1 --port 8080
  

• Configure reverse proxy (nginx/Caddy/Cloudflare Tunnel)

• HTTPS/TLS enabled
• Authentication configured

• Rate limiting enabled

• Set environment variables

  export CODE_SCALPEL_LICENSE_PATH=/etc/code-scalpel/license.jwt
  export SCALPEL_MCP_OUTPUT=WARNING  # Minimal logging
  

• Configure firewall

  # Allow HTTPS only
  sudo ufw allow 443/tcp
  sudo ufw deny 8080/tcp  # Block direct access to Code Scalpel
  

• Set up monitoring

• Reverse proxy access logs
• Code Scalpel error logs (stderr)
• HTTP status codes

• Response times

• Test authentication

  # Should fail without credentials
  curl https://code-scalpel.example.com/sse
  
  # Should succeed with credentials
  curl -u username:password https://code-scalpel.example.com/sse
  

Security Best Practices¶

Network Security¶

1. Never expose Code Scalpel directly to the internet
2. Always use localhost binding: --host 127.0.0.1

3. Use reverse proxy for remote access

4. Use HTTPS for any network deployment

   codescalpel mcp --transport sse \
     --ssl-cert /path/to/cert.pem \
     --ssl-key /path/to/key.pem
   

5. Limit network access

6. Use --allow-lan only on trusted networks
7. Configure firewall rules
8. Use VPN for team access

Application Security¶

1. Use read-only volume mounts

   docker run -v $(pwd):/workspace:ro code-scalpel
   

2. Run with minimal permissions

   # systemd unit
   [Service]
   User=codescalpel
   Group=codescalpel
   NoNewPrivileges=true
   

3. Keep Code Scalpel updated

   pip install --upgrade code-scalpel
   

4. Monitor access logs

5. Reverse proxy logs
6. Unusual access patterns
7. Failed authentication attempts

License Security¶

1. Protect license files

   chmod 600 /etc/code-scalpel/license.jwt
   chown codescalpel:codescalpel /etc/code-scalpel/license.jwt
   

2. Use environment variables in containers

   environment:
     CODE_SCALPEL_LICENSE_PATH: /secrets/license.jwt
   volumes:
     - ~/.code-scalpel/license.jwt:/secrets/license.jwt:ro
   

3. Rotate licenses regularly

4. Set expiration dates
5. Monitor license status
6. Have renewal process

Future Authentication Implementation¶

Code Scalpel plans to add native HTTP authentication in a future release.

Planned Features¶

Community Contributions Welcome¶

We welcome pull requests for authentication features:

1. Bearer Token Middleware
2. Validate Authorization: Bearer <token> header
3. Token storage and rotation

4. Per-token rate limits

5. API Key System

6. Generate/revoke API keys
7. Key-based access control

8. Usage tracking per key

9. OAuth Integration

10. OAuth 2.1 flow
11. Provider configuration (Google, GitHub, etc.)
12. Token refresh logic

See Contributing for contribution guidelines.

Summary: Security Checklist by Scenario¶

Key Takeaway: For any internet-facing deployment, authentication is mandatory but currently requires a reverse proxy solution.

Getting Help¶

• MCP Transports Guide - Transport configuration
• Deployment Matrix - Platform compatibility
• GitHub Issues - Report security concerns
• Security & Governance - Responsible disclosure and security overview