Local MCP Integration Free

SnapBack integrates with AI coding assistants through the Model Context Protocol (MCP), enabling seamless context sharing while working entirely offline. The local MCP integration is available on all tiers and requires no cloud connectivity.

Privacy Guarantee

Available MCP Tools

The local MCP server provides a small, focused set of core commands by default:

Core Commands (7):

• pulse, advise, guide - Workspace health, recommendations, and workflow plans (PERCEIVE/REASON)
• snap, check - Task management and validation (ACT)
• snap_learn, snap_end - Learning capture and session completion (REFLECT)
• snap_fix, snap_help - Snapshot operations and help (UTILITY)

Advanced Tools (opt-in via SNAPBACK_MCP_INTELLIGENCE_SURFACE=full):

• snap_violation - Report code violations
• learning_gc - Learning lifecycle management
• Intelligence Layer (5): External context integration (GitHub, Sentry, Context7)
  • snapback_validate_change, snapback_get_risk_score, snapback_query_patterns
  • snapback_get_context, snapback_suggest_rollback
• Learning Intelligence (5): Pattern-based learning system
  • intelligence.capture, intelligence.patterns, intelligence.insights
  • intelligence.explain, intelligence.outcome

1. snap - Universal Entry Point

Start tasks, get context, or quick check. This is the primary tool AI assistants should call first.

Parameters:

Copy{
  mode?: 'start' | 'check' | 'context'; // or legacy: 's' | 'c' | 'x'
  task?: string;        // Task description (for start mode)
  files?: string[];     // Files to work on
  keywords?: string[];  // Keywords for learning retrieval
  intent?: 'implement' | 'debug' | 'refactor' | 'review' | 'explore';
}

Modes:

• start (or s): Start a task, creates snapshot, loads learnings
• check (or c): Quick validation of files
• context (or x): Get current context without starting a task

Usage Example:

Copy// AI assistant starts a task
await mcp.call('snap', {
  mode: 'start',
  task: 'Refactor authentication module',
  files: ['src/auth.ts', 'src/config.ts'],
  intent: 'refactor'
});

2. check - Code Validation

Validate code against patterns, run builds, check for issues.

Parameters:

Copy{
  mode?: 'quick' | 'full' | 'patterns' | 'build' | 'impact' | 'circular' | 'docs';
  files?: string | string[];  // Files to check
  code?: string;              // Code to validate (for patterns mode)
  tests?: boolean;            // Run tests
}

Modes:

• quick (or q): Fast TypeScript + lint check
• full (or f): Comprehensive 7-layer validation
• patterns (or p): Pattern-only style compliance
• build (or b): Build verification
• impact (or i): Bundle size ROI analysis
• circular (or c): Circular dependency check
• docs (or d): Documentation freshness

Usage Example:

Copy// Quick validation before commit
const result = await mcp.call('check', {
  mode: 'quick',
  files: ['src/auth.ts']
});

3. snap_end - Complete Task

Complete a task and capture learnings.

Parameters:

Copy{
  ok: 0 | 1;                           // 1 = success, 0 = failed
  outcome: 'completed' | 'abandoned' | 'blocked';
  l?: string[];                        // Learnings captured
}

Usage Example:

Copyawait mcp.call('snap_end', {
  ok: 1,
  outcome: 'completed',
  l: ['Auth refactor reduced complexity by 40%']
});

4. snap_fix - Snapshot Operations

List snapshots, restore, or compare.

Parameters:

Copy{
  id?: string;    // Snapshot ID to restore
  diff?: string;  // Second snapshot ID for comparison
  dry?: boolean;  // Preview restore without applying
}

Usage Example:

Copy// List available snapshots
await mcp.call('snap_fix', {});

// Restore a specific snapshot
await mcp.call('snap_fix', { id: 'snap_abc123' });

5. snap_help - Help and Discovery

Get help with SnapBack operations.

Parameters:

Copy{
  q?: 'tools' | 'status' | 'wire';  // Query type
}

6. snap_learn - Capture Learning

Capture mid-session insights for future reference.

Parameters:

Copy{
  t: string;   // Trigger (when this applies)
  a: string;   // Action (what to do)
  type: 'pat' | 'pit' | 'eff' | 'disc' | 'wf';
  // pat=pattern, pit=pitfall, eff=efficiency, disc=discovery, wf=workflow
}

Usage Example:

Copyawait mcp.call('snap_learn', {
  t: 'modifying auth middleware',
  a: 'always validate session before token refresh',
  type: 'pit'
});

7. snap_violation - Report Violation

Report a mistake for pattern learning.

Parameters:

Copy{
  type: string;     // Violation category
  file: string;     // File where violation occurred
  what: string;     // What went wrong
  why: string;      // Why it happened
  prevent: string;  // How to prevent in future
}

Supported AI Assistants

SnapBack supports multiple AI assistants. Each client has specific configuration requirements.

Claude Desktop (macOS/Windows App)

Copy// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "snapback-claude": {
      "command": "npx",
      "args": ["@snapback/cli", "mcp", "--stdio", "--workspace", "/path/to/project"]
    }
  }
}

Full Claude Desktop setup guide →

Cursor

Cursor supports both stdio and HTTP transport. Recommended: stdio for reliability.

Copy// ~/.cursor/mcp.json (global) or .cursor/mcp.json (project)
{
  "mcpServers": {
    "snapback-cursor": {
      "command": "npx",
      "args": ["@snapback/cli", "mcp", "--stdio", "--workspace", "/path/to/project"]
    }
  }
}

Full Cursor setup guide →

VS Code (Native MCP Support)

VS Code uses a different config format with servers instead of mcpServers:

Copy// .vscode/mcp.json (project-level)
{
  "servers": {
    "snapback-vscode": {
      "type": "stdio",
      "command": "npx",
      "args": ["@snapback/cli", "mcp", "--stdio", "--workspace", "${workspaceFolder}"]
    }
  }
}

Windsurf

Windsurf uses the standard MCP format:

Copy// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "snapback-windsurf": {
      "command": "npx",
      "args": ["@snapback/cli", "mcp", "--stdio", "--workspace", "/path/to/project"]
    }
  }
}

Full Windsurf setup guide →

Cline (VS Code Extension)

Copy// ~/.cline/mcp.json
{
  "mcpServers": {
    "snapback": {
      "command": "npx",
      "args": ["@snapback/cli", "mcp", "--stdio", "--workspace", "/path/to/project"]
    }
  }
}

Configuration

Enabling Local MCP

Local MCP is enabled by default. To configure settings:

Copy// .snapbackconfig
{
  "mcp": {
    "local": {
      "enabled": true,
      "port": 3333, // Optional: custom port
      "autoStart": true // Start MCP server when extension activates
    }
  }
}

VS Code Extension Settings

Copy// VS Code settings.json
{
  "snapback.mcp.local.enabled": true,
  "snapback.mcp.local.autoStart": true,
  "snapback.mcp.local.logLevel": "info" // debug | info | warn | error
}

How It Works

The local MCP server operates entirely on your machine:

1. Startup: SnapBack extension starts a local MCP server on localhost:3333
2. Connection: AI assistants connect to the local server via stdio or HTTP
3. Tool Invocation: Assistants call MCP tools to interact with SnapBack
4. Response: SnapBack processes requests locally and returns results
5. No Network: All operations happen offline—no external requests

Context Shared Locally

The local MCP integration provides AI assistants with:

Protection Levels

File protection metadata to avoid risky modifications:

Copy{
  "protectionLevels": {
    "src/config.ts": "warn",
    "src/.env": "block",
    "src/secrets.json": "block"
  }
}

Session Context

Current session information for better assistance:

Copy{
  "currentSession": {
    "id": "session_12345",
    "name": "Implement authentication",
    "duration": 2400, // seconds
    "filesModified": ["src/auth.ts", "src/config.ts"],
    "snapshotCount": 3
  }
}

Risk Analysis Results

Recent security findings to avoid introducing similar risks:

Copy{
  "recentFindings": [
    {
      "type": "secret",
      "file": "src/config.ts",
      "severity": "high",
      "resolved": true,
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ]
}

Privacy and Security

What Stays on Your Machine

• Everything: All data, snapshots, and analysis results remain local
• File contents and code
• Protection levels and policies
• Session metadata
• Risk analysis findings
• Configuration settings

What’s Never Shared

Local MCP integration never sends data externally:

• ❌ No file contents to cloud
• ❌ No code snippets to servers
• ❌ No personal information transmitted
• ❌ No usage telemetry (unless you opt-in separately)

Troubleshooting

Transport Configuration Errors

Error: “command” field expected but received undefined

Copy[{"code": "invalid_type", "expected": "string", "received": "undefined",
  "path": ["mcpServers", "snapback", "command"]}]

Cause: The client received HTTP transport config but requires stdio transport.

Solution: Use command + args instead of url:

Copy// ❌ Wrong - HTTP transport (not supported by Claude Desktop)
{
  "mcpServers": {
    "snapback": {
      "url": "http://localhost:3333"
    }
  }
}

// ✅ Correct - stdio transport
{
  "mcpServers": {
    "snapback": {
      "command": "npx",
      "args": ["@snapback/cli", "mcp", "--stdio", "--workspace", "/your/project"]
    }
  }
}

Quick fix:

Copysnap tools configure --force  # Regenerates with correct transport

Transport Compatibility Matrix

MCP Server Not Starting

Copy# Test MCP server manually
snap mcp --help

# Run MCP server with verbose output
snap mcp --stdio --workspace .

# If @snapback/cli isn't installed globally
npm install -g @snapback/cli

Command Not Found

If npx or snap isn’t found:

1. Find the correct path:

   Copywhich npx        # e.g., /usr/local/bin/npx
   which snap       # e.g., /usr/local/bin/snap

2. Use absolute path in config:

   Copy{
     "command": "/usr/local/bin/npx",
     "args": ["@snapback/cli", "mcp", "--stdio", "--workspace", "/your/project"]
   }

3. Or use node directly:

   Copynpm root -g  # Find global modules path

   Copy{
     "command": "node",
     "args": ["/usr/local/lib/node_modules/@snapback/cli/dist/cli.js", "mcp", "--stdio"]
   }

AI Assistant Can’t Connect

1. Verify command works: snap mcp --help
2. Check workspace is valid (has .git/, package.json, or .snapback/)
3. Restart your AI assistant
4. Set MCP_QUIET=1 env var to suppress logging

Performance Issues

If MCP operations are slow:

1. Reduce snapshot retention to free up disk space
2. Exclude large files from risk analysis via .snapbackignore
3. Disable auto-snapshots during heavy AI assistance sessions

CLI Commands

Copy# Start local MCP server (stdio transport)
snap mcp --stdio

# Check MCP server status
snapback mcp status

# Stop MCP server
snapback mcp stop

# View MCP logs
snapback mcp logs [--tail 100]

# Test MCP connection
snapback mcp test

# Show shared context (for debugging)
snapback mcp context --format json

Best Practices

Upgrade to Backend MCP

Want cloud-powered features like advanced AI scoring and team collaboration?

Backend MCP (available on Solo, Team, and Enterprise plans) adds:

• ✓ Cloud-based Guardian AI risk scoring
• ✓ Team snapshot sharing
• ✓ Cloud backup and restore
• ✓ API access with authentication

Learn about Backend MCP →

Related Documentation

• Protection Levels - Configure file protection
• AI Detection - Understand risk analysis
• Session Time-Travel - Navigate your coding history
• CLI Reference - Command-line tools