Skip to content

MCP Protocol

Code Scalpel implements the Model Context Protocol (MCP), enabling seamless integration with AI agents like Claude, GitHub Copilot, and Cursor.

What is MCP?

The Model Context Protocol is an open standard for connecting AI models to external tools and data sources. It provides:

  • Standardized communication between AI agents and tools
  • Discovery of available capabilities
  • Structured requests and responses
  • Error handling with recovery suggestions

Protocol Flow

sequenceDiagram
    participant AI as AI Agent
    participant MCP as MCP Client
    participant CS as Code Scalpel Server

    AI->>MCP: "Analyze this code"
    MCP->>CS: tools/analyze_code
    CS-->>MCP: ToolResponse
    MCP-->>AI: Formatted result

Server Discovery

Code Scalpel supports three MCP transport types for maximum deployment flexibility. See the MCP Transports Guide for comprehensive setup instructions.

Best for local AI clients (Claude Desktop, Cursor, VS Code). Zero network overhead, microsecond latency.

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

Start server: 

codescalpel mcp

SSE Transport (Server-Sent Events)

Best for network deployments, remote teams, Docker/Kubernetes. HTTP-based with efficient streaming.

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

Start server: 

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

With HTTPS: 

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

streamable-http Transport

Best for production systems, load balancers, reverse proxies. Standard HTTP POST with streaming responses.

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

Start server: 

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

With HTTPS: 

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

Transport Comparison

Transport Best For Endpoint Network Required
stdio Local AI clients N/A (process pipe) No
sse Network deployments /sse Yes
streamable-http Production/proxies /mcp Yes

For detailed setup, security, and deployment examples, see the MCP Transports Guide.

Tool Invocation

Request Format

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "analyze_code",
    "arguments": {
      "code": "def hello(): pass",
      "language": "python"
    }
  },
  "id": 1
}

Response Format

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"data\": {...}, \"tier_applied\": \"community\"}"
      }
    ]
  },
  "id": 1
}

Available Tools

Code Scalpel exposes 22 tools through MCP:

Category Tools
Analysis analyze_code, get_file_context
Extraction extract_code, update_symbol, rename_symbol
Security security_scan, unified_sink_detect, cross_file_security_scan
Graph get_call_graph, get_graph_neighborhood, get_cross_file_dependencies
Symbolic symbolic_execute, generate_unit_tests, simulate_refactor
System crawl_project, get_project_map, scan_dependencies
Policy validate_paths, verify_policy_integrity, code_policy_check

Tool Discovery

List available tools:

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "analyze_code",
        "description": "Parse and extract code structure",
        "inputSchema": {
          "type": "object",
          "properties": {
            "code": {"type": "string", "description": "Code to analyze"},
            "language": {"type": "string", "default": "auto"}
          },
          "required": ["code"]
        }
      }
    ]
  },
  "id": 1
}

Capabilities

Code Scalpel advertises these MCP capabilities:

{
  "capabilities": {
    "tools": {
      "listChanged": true
    },
    "resources": {
      "subscribe": true,
      "listChanged": true
    },
    "prompts": {
      "listChanged": false
    }
  }
}

Resource URIs

Access code via URIs without file paths:

code:///python/utils/calculate_tax
code:///typescript/components/UserCard
code:///java/services.AuthService/authenticate

Error Handling

MCP errors include recovery suggestions:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "code": "SYMBOL_NOT_FOUND",
      "suggestion": "Did you mean 'process_order'?",
      "recovery_options": ["process_order"]
    }
  },
  "id": 1
}

Progress Notifications

Long-running operations report progress:

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "token": "op-123",
    "progress": 50,
    "message": "Analyzing files... (25/50)"
  }
}

Best Practices

  1. Check tool availability - Use tools/list before invocation
  2. Handle errors gracefully - Use recovery suggestions
  3. Monitor progress - Subscribe to progress notifications
  4. Respect rate limits - Enterprise: unlimited, Pro: 100/min
  5. Use appropriate tier - Some tools require Pro/Enterprise