Deployment Compatibility Matrix¶

This document provides a comprehensive view of Code Scalpel's compatibility with all known MCP server deployment methods.

📋 Full Compliance Audit: See the MCP Compliance Audit for point-by-point validation against official MCP requirements.

Transport Layer Support¶

Local Deployment Methods¶

Desktop/Development Environments¶

Client-Specific Configurations¶

Network & Cloud Deployment¶

Container Platforms¶

Cloud Platforms¶

Platform as a Service¶

Authentication Support¶

⚠️ Critical Limitation for Remote Deployments

Code Scalpel currently implements authorization (tier-based feature gating) but not authentication (identity verification) for HTTP endpoints.

Current Support¶

Not Yet Implemented¶

What This Means¶

For local development (stdio): ✅ No authentication needed - process isolation provides security

For network deployments (SSE/HTTP): ⚠️ Must use workaround

• ✅ LAN/Team: Use VPN, SSH tunnel, or private network
• ✅ Production: REQUIRED - Use reverse proxy (nginx/Caddy) or Cloudflare Tunnel
• ❌ Public Internet: NEVER expose directly without authentication

Complete Authentication Guide¶

See the Authentication & Security Guide for: - Detailed security analysis for each deployment scenario - Step-by-step reverse proxy configuration (nginx, Caddy, Cloudflare Tunnel) - Production deployment checklist - Authentication implementations (workarounds until native support)

Serverless Limitations¶

Code Scalpel is designed as a stateful, long-running server and has limitations on serverless platforms:

Why Serverless is Limited¶

Recommended Serverless Architecture¶

For serverless deployments:

1. Use Container-based Serverless (Cloud Run, ECS Fargate) instead of FaaS
2. Implement External State Store for AST cache persistence
3. Use Session Management to maintain context across invocations
4. Deploy as "Always-On" Container with min instances = 1

Example: AWS Lambda Deployment (Experimental)¶

# lambda_handler.py
import json
from code_scalpel.mcp.server import handle_mcp_request

def lambda_handler(event, context):
    """
    Lambda wrapper for Code Scalpel MCP server.
    WARNING: Limited functionality due to stateless constraints.
    """
    try:
        # Parse MCP request from API Gateway
        body = json.loads(event.get('body', '{}'))

        # Handle MCP tool call
        result = handle_mcp_request(body)

        return {
            'statusCode': 200,
            'headers': {'Content-Type': 'application/json'},
            'body': json.dumps(result)
        }
    except Exception as e:
        return {
            'statusCode': 500,
            'body': json.dumps({'error': str(e)})
        }

Note: This requires implementing handle_mcp_request as a stateless interface, which is not currently in the codebase.

Windows Deployment¶

PowerShell Configuration¶

# Claude Desktop config (Windows)
$configPath = "$env:APPDATA\Claude\claude_desktop_config.json"

# With uvx (recommended)
@"
{
  "mcpServers": {
    "code-scalpel": {
      "command": "uvx",
      "args": ["codescalpel", "mcp"]
    }
  }
}
"@ | Out-File -FilePath $configPath -Encoding utf8

cmd.exe Support¶

Code Scalpel works with Windows Command Prompt, but paths must be proper Windows paths:

{
  "mcpServers": {
    "code-scalpel": {
      "command": "cmd",
      "args": ["/c", "python", "-m", "code_scalpel.cli", "mcp"]
    }
  }
}

Fly.io Deployment¶

Fly.io is ideal for stateful MCP servers with single-tenant isolation.

fly.toml Configuration¶

app = "code-scalpel"
primary_region = "sjc"

[build]
  image = "ghcr.io/your-org/code-scalpel:latest"

[env]
  CODE_SCALPEL_TIER = "enterprise"

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = false
  auto_start_machines = true
  min_machines_running = 1

[[services]]
  protocol = "tcp"
  internal_port = 8080

  [[services.ports]]
    port = 443
    handlers = ["tls", "http"]

  [[services.tcp_checks]]
    interval = "15s"
    timeout = "2s"

Deploy:

fly deploy
flyctl secrets set CODE_SCALPEL_LICENSE_PATH=/etc/code-scalpel/license.jwt

Deployment Decision Tree¶

Need to deploy Code Scalpel?
│
├─ Local AI client? (Claude Desktop, VS Code, Cursor)
│  └─ ✅ Use stdio transport (simplest)
│
├─ Docker/Kubernetes deployment?
│  ├─ Behind load balancer? → ✅ Use streamable-http
│  └─ Direct access? → ✅ Use SSE
│
├─ Cloud VM? (EC2, Droplets, Fly.io)
│  └─ ✅ Use SSE or streamable-http with systemd service
│
├─ Serverless? (Lambda, Azure Functions)
│  ├─ Can use containers? (Cloud Run, Fargate)
│  │  └─ ✅ Use streamable-http transport
│  └─ Pure FaaS? (Lambda, Functions)
│     └─ ⚠️ Limited support - consider VM/container instead
│
└─ On-premises/Enterprise?
   ├─ Need authentication? → Use reverse proxy (nginx/Caddy) + SSE
   ├─ Behind firewall? → ✅ Use HTTP transport + VPN
   └─ Air-gapped? → ✅ Use stdio on local machines

Status Legend¶

Getting Help¶

If your deployment scenario isn't covered:

1. Check the MCP Transports Guide for transport-specific details
2. Review the Installation Guides for platform-specific setup
3. Open an issue on GitHub describing your deployment environment

Contributing¶

Know of a deployment method not covered here? We welcome contributions:

• Documentation improvements
• Platform-specific deployment guides
• Authentication implementations
• Serverless adapters

See Contributing for contribution guidelines.