MCP Deployment Compliance Audit¶

This document provides a point-by-point validation of Code Scalpel's compliance with the comprehensive Model Context Protocol (MCP) deployment requirements.

Executive Summary¶

Bottom Line: Code Scalpel can be deployed in all major MCP scenarios with production-ready configurations. Authentication for remote endpoints requires reverse proxy (documented with working examples).

1. Local Transport Deployment (STDIO)¶

Requirement 1.1: Direct Execution (Python/Node)¶

Specification: Server must be runnable from terminal command (e.g., uv run code_scalpel.py)

Code Scalpel Implementation:

✅ PASS - Multiple execution methods supported:

# Method 1: uvx (recommended)
uvx codescalpel mcp

# Method 2: pip installation
pip install codescalpel
codescalpel mcp

# Method 3: Python module
python -m code_scalpel.cli mcp

# Method 4: Direct module execution
uvx codescalpel mcp

Evidence: - cli.py:1875-1933 - MCP command parser - cli.py:454-573 - start_mcp_server() function - mcp/server.py:5050-5199 - run_server() implementation

Verdict: ✅ Fully Compliant

Requirement 1.2: stdout/stderr Separation¶

Specification: Must not log debug information to stdout (corrupts protocol), only to stderr

Code Scalpel Implementation:

✅ PASS - Strict stderr-only logging enforced:

# server.py:160-192
def _configure_logging(transport: str = "stdio"):
    """Configure logging based on transport type."""
    # Always log to stderr to avoid corrupting stdio transport
    handler = logging.StreamHandler(sys.stderr)  # Line 169
    # ...
    root_logger.addHandler(handler)

Additional Evidence: - server.py:5175-5179 - Output routing based on transport - server.py:199-211 - _debug_print() always uses sys.stderr - cli.py:518-527 - User-facing messages only to stderr for stdio

Testing:

# Verify no stdout pollution
codescalpel mcp 2>/dev/null | wc -l  # Should be 0 (no stdout output)

Verdict: ✅ Fully Compliant

Requirement 1.3: Dockerized (Local Container)¶

Specification: Users must be able to run via docker run with proper stdio handling

Code Scalpel Implementation:

✅ PASS - Docker support with stdio transport:

Client Configuration:

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

Docker Compose Alternative:

services:
  code-scalpel:
    image: ghcr.io/your-org/code-scalpel:latest
    command: ["mcp"]
    stdin_open: true
    tty: false

Evidence: - website/docs/getting-started/installation/docker.md:113-130 - Docker stdio config - website/docs/guides/deployment-matrix.md:28 - Docker deployment status

Verdict: ✅ Fully Compliant

Requirement 1.4: Windows/Legacy Shells¶

Specification: Compatibility with Windows cmd.exe and legacy shells

Code Scalpel Implementation:

✅ PASS - Windows compatibility documented and tested:

PowerShell Configuration:

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

cmd.exe with Wrapper:

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

Evidence: - website/docs/guides/deployment-matrix.md:42-55 - Windows deployment section - website/docs/getting-started/installation/claude-desktop.md:88-100 - Windows config

Verdict: ✅ Fully Compliant

2. Remote Transport Deployment (HTTP & SSE)¶

Requirement 2.1: Server-Sent Events (SSE)¶

Specification: Must expose /sse endpoint for server-to-client streaming

Code Scalpel Implementation:

✅ PASS - SSE transport fully implemented:

Server Startup:

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

Client Configuration:

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

Evidence: - cli.py:1881 - --transport choices include "sse" - server.py:5191-5199 - SSE transport configuration - cli.py:532 - Endpoint path routing (/sse for SSE)

Verdict: ✅ Fully Compliant

Requirement 2.2: Streamable HTTP¶

Specification: Must support HTTP streaming (newer standard for Gemini CLI, Cline)

Code Scalpel Implementation:

✅ PASS - streamable-http transport implemented:

Server Startup:

codescalpel mcp --transport streamable-http --host 0.0.0.0 --port 8080

Client Configuration:

{
  "mcpServers": {
    "code-scalpel": {
      "url": "http://localhost:8080/mcp",
      "transport": "http"
    }
  }
}

Evidence: - cli.py:1881 - --transport choices include "streamable-http" - cli.py:532 - Endpoint path /mcp for streamable-http - server.py:5191 - Transport configuration for streamable-http

Verdict: ✅ Fully Compliant

Requirement 2.3: Authentication Support ⚠️¶

Specification: Must support authentication headers (Authorization: Bearer <token>) or OAuth flows for remote deployments

Code Scalpel Implementation:

❌ NOT IMPLEMENTED - No native HTTP authentication

Current State: - No Authorization header validation - No Bearer token checking - No OAuth 2.0/2.1 implementation - No API key system

Code Analysis:

# Search for authentication in MCP server
grep -i "authorization\|bearer\|oauth" src/code_scalpel/mcp/server.py
# Result: No authentication middleware found

License != Authentication: Code Scalpel implements license validation (authorization/feature gating) but NOT authentication (identity verification):

# server.py:5112-5119 - License validation (NOT HTTP auth)
validator = JWTLicenseValidator()
effective_tier = compute_effective_tier_for_startup(
    requested_tier=requested_tier,
    validator=validator,
)

Impact Analysis:

Workarounds Implemented:

✅ Production-Ready Solutions Documented:

1. nginx with Basic Auth
2. Full configuration: website/docs/guides/authentication-security.md:125-175

3. Status: Production-ready

4. Caddy with OAuth

5. Full configuration: website/docs/guides/authentication-security.md:179-223

6. Status: Production-ready

7. Cloudflare Tunnel (Recommended)

8. Full configuration: website/docs/guides/authentication-security.md:227-299
9. Zero-trust authentication
10. Status: Production-ready

Example Production Stack:

┌─────────────┐
│   Client    │
└──────┬──────┘
       │ HTTPS with OAuth
       ▼
┌─────────────────┐
│ Cloudflare      │◄─── Authentication Layer
│ Access (OAuth)  │     (Google, GitHub, SAML)
└──────┬──────────┘
       │ Authenticated requests only
       ▼
┌─────────────────┐
│ Code Scalpel    │◄─── License Validation
│ MCP Server      │     (Pro/Enterprise tiers)
│ (localhost:8080)│
└─────────────────┘

Verdict: ❌ NOT COMPLIANT - ⚠️ Workaround Required for Production

Documentation Status: ✅ Comprehensive workarounds documented

Future Roadmap: - v1.4.0: Bearer Token authentication (planned) - v1.5.0: OAuth 2.1 integration (planned) - v2.0.0: SAML 2.0 enterprise SSO (planned)

3. Cloud & Serverless Hosting Strategies¶

Requirement 3.1: FaaS (Functions as a Service)¶

Specification: Must support AWS Lambda, Azure Functions, Google Cloud Run with state management

Code Scalpel Implementation:

⚠️ LIMITED SUPPORT - Not optimized for stateless FaaS

Current Architecture:

# server.py is designed as long-running stateful server
# - In-memory AST cache
# - Project root context
# - License validation cache

Limitations for Pure FaaS (Lambda/Azure Functions):

Container-Based FaaS (✅ SUPPORTED):

Code Scalpel works well with container-based serverless:

1. Google Cloud Run ✅

   service:
     name: code-scalpel
     image: gcr.io/project/code-scalpel:latest
     env:
       - name: CODE_SCALPEL_LICENSE_PATH
         value: /secrets/license.jwt
   

2. AWS ECS Fargate ✅

   taskDefinition:
     containerDefinitions:
       - name: code-scalpel
         image: code-scalpel:latest
         command: ["mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8080"]
   

3. Azure Container Instances ✅

   containerGroup:
     containers:
       - name: code-scalpel
         image: code-scalpel:latest
         command: ["mcp", "--transport", "streamable-http"]
   

Evidence: - website/docs/guides/deployment-matrix.md:120-166 - Serverless limitations - website/docs/guides/deployment-matrix.md:55-66 - Container platforms

Verdict: ⚠️ PARTIAL COMPLIANCE - ✅ Container-based serverless: Fully Supported - ⚠️ Pure FaaS (Lambda/Functions): Limited - Use containers instead

Requirement 3.2: Virtual Machines (Fly.io/EC2)¶

Specification: Run on VMs with stateful operations and single-tenant patterns

Code Scalpel Implementation:

✅ PASS - Optimized for VM deployments

Supported Platforms: - AWS EC2 - Google Compute Engine - Azure VMs - DigitalOcean Droplets - Fly.io (with configuration) - Linode - Vultr

Fly.io Configuration Example:

# fly.toml
app = "code-scalpel"
primary_region = "sjc"

[build]
  image = "code-scalpel:latest"

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

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

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

Single-Tenant Pattern:

# Deploy one instance per team/user
flyctl deploy --app code-scalpel-team-a
flyctl deploy --app code-scalpel-team-b

Evidence: - website/docs/guides/deployment-matrix.md:51-60 - Cloud VM platforms - website/docs/guides/deployment-matrix.md:285-318 - Fly.io deployment

Verdict: ✅ Fully Compliant

Requirement 3.3: Apify/Marketplace Hosting¶

Specification: Support for marketplace platforms like Apify with pay-per-event models

Code Scalpel Implementation:

🔄 EXPERIMENTAL - Marketplace hosting patterns possible but not officially supported

Status by Platform:

Why Limited for Apify: - Apify optimized for web scraping/crawling actors - MCP server requires persistent connection - Pay-per-event model doesn't align with long-running server

Alternative Marketplace Deployment: Consider packaging Code Scalpel for: - VS Code Marketplace (as MCP extension) - GitHub Marketplace (as action) - Docker Hub / Container registries

Evidence: - website/docs/guides/deployment-matrix.md:72-76 - Platform as a Service section

Verdict: 🔄 EXPERIMENTAL - Community contributions welcome

Overall Compliance Matrix¶

Summary by Category¶

Compliance Score¶

Implementation: 7/10 (70%) ⚠️ With Documented Workarounds: 9/10 (90%) ✅

Categories: - Local Deployment: 4/4 (100%) ✅ - Remote Deployment: ⅔ (67%) ⚠️ - Cloud/Serverless: 1.5/3 (50%) ⚠️

Critical Gaps & Mitigation¶

Gap 1: HTTP Authentication¶

Severity: 🔴 Critical for production deployments

Mitigation Status: ✅ Production-ready workarounds documented

Solutions: 1. ✅ nginx + Basic Auth (15min setup) 2. ✅ Caddy + OAuth (30min setup) 3. ✅ Cloudflare Tunnel + Access (10min setup, recommended)

Documentation: - website/docs/guides/authentication-security.md (700+ lines) - Complete production deployment guide - Security checklist - Configuration examples

No Code Changes Required: Use Code Scalpel as-is with reverse proxy

Gap 2: Pure FaaS Optimization¶

Severity: 🟡 Medium - Use container alternatives

Mitigation Status: ✅ Container-based serverless fully supported

Solutions: 1. ✅ Google Cloud Run 2. ✅ AWS Fargate 3. ✅ Azure Container Instances

Trade-off: Slightly higher cost vs pure Lambda, but better performance and no refactoring needed

Documentation: - website/docs/guides/deployment-matrix.md:120-166

Gap 3: Marketplace Hosting¶

Severity: 🟢 Low - Experimental feature

Mitigation Status: Community contributions welcome

Alternative Distribution Channels: 1. ✅ PyPI (pip install) 2. ✅ Docker Hub / ghcr.io 3. ✅ GitHub Releases 4. 🔄 VS Code Marketplace (future)

Deployment Decision Matrix¶

Use this table to choose the right deployment method:

Testing Validation¶

Validated Scenarios¶

✅ Tested and Working: 1. Claude Desktop (macOS, Windows, Linux) - stdio 2. VS Code + Copilot - stdio 3. Cursor - stdio 4. Docker Compose - SSE 5. Kubernetes - streamable-http 6. nginx reverse proxy - All transports 7. Cloudflare Tunnel - SSE

⚠️ Tested with Limitations: 1. AWS Lambda - Works but slow cold starts 2. Azure Functions - Works but limited execution time

🔄 Experimental: 1. Apify Actors - Theoretically possible, not validated

Recommendations¶

For Code Scalpel Maintainers¶

Priority 1 (P0) - Critical: - [ ] Implement Bearer token authentication middleware - [ ] Add API key system with revocation - [ ] OAuth 2.1 integration example

Priority 2 (P1) - Important: - [ ] FaaS adapter for stateless deployments - [ ] External cache integration (Redis/DynamoDB) - [ ] Session management for serverless

Priority 3 (P2) - Nice to Have: - [ ] VS Code Marketplace extension - [ ] GitHub Marketplace action - [ ] Apify Actor template

For Code Scalpel Users¶

Development: - ✅ Use stdio transport - works perfectly

Production: - ✅ MUST use reverse proxy for authentication - ✅ Deploy on VMs or container platforms (not pure FaaS) - ✅ Follow security checklist in authentication guide

Don't: - ❌ Expose HTTP endpoints directly to internet - ❌ Use pure Lambda/Functions (use Cloud Run/Fargate) - ❌ Rely on host validation alone for security

Conclusion¶

Code Scalpel achieves 90% compliance with comprehensive MCP deployment requirements.

What Works Out of the Box ✅¶

• All local deployment methods (stdio)
• All remote transports (SSE, streamable-http)
• All major cloud platforms (VMs, containers)
• Docker, Kubernetes, Docker Compose
• Windows, macOS, Linux
• All major AI clients (Claude, Cursor, VS Code)

What Requires Workarounds ⚠️¶

• HTTP authentication → Use reverse proxy (documented)
• Pure serverless → Use container-based (documented)

What's Not Supported ❌¶

• Apify Marketplace (experimental only)
• Native OAuth (use proxy until v1.5.0)

Overall Assessment: ✅ Production-ready for all major deployment scenarios with documented, tested workaround patterns for known gaps.

References¶

• Authentication & Security Guide
• MCP Transports Guide
• Deployment Matrix
• Docker Installation
• Claude Desktop Setup