Model Context Protocol (MCP)

SnapBack integrates with AI coding assistants through the Model Context Protocol (MCP), enabling seamless context sharing for snapshots, risk detection, and learning capture.

Two Integration Modes

Local MCP Setup

Supported AI Assistants

Claude Code (Cursor)

Configure Cursor to use SnapBack’s local MCP server:

Copy// ~/.cursor/mcp.json
{
  "mcpServers": {
    "snapback": {
      "command": "snap",
      "args": ["mcp", "--stdio"],
      "type": "stdio"
    }
  }
}

GitHub Copilot

Coming soon. Track progress at GitHub Discussions.

Continue

Configure in .continue/config.json:

Copy{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "snapback",
        "command": "snap",
        "args": ["mcp", "--stdio"]
      }
    ]
  }
}

Available MCP Tools

The local MCP server provides a small, focused set of core commands by default. Advanced intelligence tools can be enabled for power users.

Default Surface (Minimal)

Core Commands (7):

• PERCEIVE: pulse - workspace health check
• REASON: advise, guide - get recommendations and concrete plans
• ACT: snap, check - task and validation
• REFLECT: snap_learn, snap_end - capture learnings
• UTILITY: snap_fix, snap_help - snapshots and help

What you get:

• Clean, focused tool list for AI assistants
• Fast tool discovery and invocation
• Anthropic MCP best-practice compliance
• All essential SnapBack workflows

Full Surface (Advanced)

Set SNAPBACK_MCP_INTELLIGENCE_SURFACE=full to enable advanced tools:

Additional Tools (11):

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

Enabling Full Surface:

Copy// In your MCP config (e.g., ~/.cursor/mcp.json)
{
  "mcpServers": {
    "snapback": {
      "command": "npx",
      "args": ["@snapback/cli", "mcp", "--stdio"],
      "env": {
        "SNAPBACK_MCP_INTELLIGENCE_SURFACE": "full"
      }
    }
  }
}

Use full surface when:

• You need proactive risk assessment with external context (GitHub, Sentry, Context7)
• You want pattern-based learning and insights
• You’re debugging complex production issues
• You need violation tracking and lifecycle management

1. pulse - Workspace Vitals (PERCEIVE)

Quick health check of workspace state before taking action.

Parameters:

Copy{
  record_change?: string;  // Optional file path to record as change
}

Wire Response:

Copy🫀|pulse:elevated|cpm:18|pressure:45|risk:M|changes:7|action:monitor

2. advise - Get Recommendations (REASON)

Get AI-powered advice on next steps based on current workspace state.

Parameters:

Copy{
  task?: string;    // What you're about to do
  files?: string[]; // Files you plan to modify
  intent?: 'implement' | 'refactor' | 'debug' | 'test' | 'deploy';
}

Wire Response:

Copy🧠|conf:65|rec:review|warn:2|learn:3|viol:1|hint:check_error_handling

3. snap - Universal Entry Point (ACT)

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';
  thorough?: boolean;   // Enable 7-layer validation (check mode)
  compact?: boolean;    // Use compact wire format
  goal?: {              // Goal for task completion validation
    metric: 'bundle' | 'performance' | 'coverage';
    target: number;
    unit: string;
  };
}

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'
});

4. check - Code Validation (ACT)

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

Parameters:

Copy{
  mode?: 'quick' | 'full' | 'patterns' | 'build' | 'impact' | 'circular' 
       | 'docs' | 'learnings' | 'architecture' | 'trace' | 'security' 
       | 'coverage' | 'orphans' | 'health';
  files?: string | string[];  // Files to check
  diff?: 'staged' | 'changed' | 'uncommitted'; // Auto-detect from git
  code?: string;              // Code to validate (for patterns mode)
  tests?: boolean;            // Run tests
  compact?: boolean;          // Use compact wire format
}

Modes (14 total):

• quick: Fast TypeScript + lint check (default)
• full: Comprehensive 7-layer validation
• patterns: Pattern-only style compliance
• build: Build verification (runs pnpm build)
• impact: Change impact analysis with risk scoring
• circular: Circular dependency detection
• docs: Documentation freshness check
• learnings: Learning tier maintenance and stats
• architecture: Layer dependency validation
• trace: Deep dependency analysis with confidence
• security: Secret detection and threat scanning
• coverage: Test coverage analysis
• orphans: Find orphan files and skipped tests
• health: MCP server diagnostics

5. snap_end - Complete Task (REFLECT)

Complete a task and capture learnings.

Parameters:

Copy{
  outcome?: 'completed' | 'abandoned' | 'blocked';
  learnings?: string[];   // Key learnings from this task
  notes?: string;         // Additional completion notes
  efficiency?: {          // Your estimate of session efficiency
    saved?: string;       // Tokens saved (e.g., '~15K')
    prevented?: string;   // Mistakes avoided (e.g., '2 - wrong layer')
    helped?: string;      // What context helped (e.g., 'auth patterns')
  };
  survey?: {              // Optional self-assessment (helps improve SnapBack)
    patterns_used?: number;      // How many patterns applied
    pitfalls_avoided?: number;   // How many mistakes avoided
    helpfulness?: number;        // Rating 1-5
    unhelpful_count?: number;    // Count of unhelpful suggestions
  };
  compact?: boolean;      // Use compact wire format
}

Wire Response:

Copy🧢|E|status:OK|learn:2L|files:3F|lines:+45-12

6. snap_fix - Snapshot Operations (UTILITY)

List snapshots, restore, or compare.

Parameters:

Copy{
  action?: 'list' | 'restore' | 'diff';  // Operation type (default: list)
  id?: string;        // Snapshot ID (for restore/diff)
  diffWith?: string;  // Second snapshot ID (for diff)
  dryRun?: boolean;   // Preview mode (default: true for safety)
  confirm?: boolean;  // Required with dryRun:false for actual restore
  files?: string[];   // Specific files to restore
  compact?: boolean;  // Use compact wire format
}

Usage Example:

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

// Preview restore (default - safe)
await mcp.call('snap_fix', { action: 'restore', id: 'snap_abc123' });

// Actually restore (requires both flags)
await mcp.call('snap_fix', { action: 'restore', id: 'snap_abc123', dryRun: false, confirm: true });

// Compare two snapshots
await mcp.call('snap_fix', { action: 'diff', id: 'snap_before', diffWith: 'snap_after' });

7. snap_help - Help and Discovery (UTILITY)

Get help with SnapBack operations. Returns plain text only (no wire format) - the escape hatch when wire format is confusing.

Parameters:

Copy{
  topic?: 'tools' | 'status' | 'wire' | 'modes' | 'thresholds' | 'decision' | 'all';
}

Topics:

• tools: List all available tools with modes
• status: Current session state
• wire: Wire format grammar and field meanings
• modes: Explanation of all snap and check modes
• thresholds: Auto-promotion rules (3x→pattern, 5x→automation)
• decision: Tool selection decision tree
• all: Comprehensive help (default)

8. snap_learn - Capture Learning (REFLECT)

Capture mid-session insights for future reference. Use this mid-task for immediate insights (vs snap_end for end-of-task summary).

Parameters:

Copy{
  trigger: string;  // REQUIRED: What situation triggers this learning
  action: string;   // REQUIRED: What to do when triggered
  type?: 'pattern' | 'pitfall' | 'efficiency' | 'discovery' | 'workflow';
  source?: string;  // Where this learning originated
  compact?: boolean;
}

Learning Types:

• pattern: Something that worked well (“When doing X, always do Y”)
• pitfall: Mistake to avoid (“Never do X because Y happens”)
• efficiency: Token/time optimization (“Use X instead of Y”)
• discovery: New codebase knowledge (“File X handles Y”)
• workflow: Process improvement (“Better way to do X”)

Wire Response:

Copy🧢|L|status:OK|id:learn_abc123|type:pattern

Usage Example:

Copyawait mcp.call('snap_learn', {
  trigger: 'modifying auth middleware',
  action: 'always validate session before token refresh',
  type: 'pitfall'
});

9. snap_violation - Report Violation (REFLECT)

Report a mistake for pattern learning. Use for actual bugs/errors (vs snap_learn pitfall for potential mistakes).

Parameters:

Copy{
  type: string;        // REQUIRED: Violation category (e.g., 'silent_catch')
  file: string;        // REQUIRED: File where violation occurred
  description: string; // REQUIRED: What went wrong
  reason?: string;     // Why it happened (optional)
  prevention: string;  // REQUIRED: How to prevent in future
  compact?: boolean;
}

Auto-Escalation:

• 1st time: Recorded and tracked
• 3rd time: Promoted to pattern (prevents future occurrences)
• 5th time: Flagged for automation

Wire Response:

Copy🧢|V|status:OK|type:silent_catch|count:3|promote:PROMOTED

Usage Example:

Copyawait mcp.call('snap_violation', {
  type: 'silent_catch',
  file: 'src/auth.ts',
  description: 'Catch block swallowed error without logging',
  reason: 'Rushed implementation, forgot logging',
  prevention: 'Always log in catch blocks with context'
});

Intelligence Layer Tools (Advanced)

The Intelligence Layer transforms SnapBack from reactive protection to proactive prevention:

Before: AI makes change → SnapBack snapshots it → User restores if broken

After: AI proposes change → SnapBack evaluates against context → Informed decision before damage

Prerequisites

Intelligence Layer tools require external MCP server connections:

• GitHub MCP (@modelcontextprotocol/server-github) - Commit history, PR discussions, issue references
• Context7 MCP - API documentation validation, deprecation warnings
• Sentry MCP (@modelcontextprotocol/server-sentry) - Error tracking, stacktraces, failure patterns

1. snapback_validate_change - Proactive Change Validation

Validate file changes against aggregated external context before they’re applied.

Parameters:

Copy{
  files: Array<{           // Files to validate
    path: string;
    content?: string;      // New content (optional)
    diff?: string;         // Git diff (optional)
  }>;
  context?: {
    intent?: string;       // Why this change is being made
    relatedIssues?: string[]; // GitHub issue references
  };
}

Response:

Copy{
  validationResult: {
    overallRisk: number;   // 0-100 risk score
    riskLevel: 'low' | 'medium' | 'high' | 'critical';
    findings: Array<{
      file: string;
      type: 'security' | 'deprecation' | 'pattern_violation' | 'error_prone';
      severity: 'low' | 'medium' | 'high' | 'critical';
      message: string;
      source: 'github' | 'sentry' | 'context7' | 'local';
      confidence: number; // 0-100
    }>;
    recommendation: 'proceed' | 'review' | 'block';
    context: {
      recentErrors?: number;     // From Sentry
      relatedCommits?: number;   // From GitHub
      deprecationWarnings?: number; // From Context7
    };
  };
}

Wire Response:

Copy🔍|V|score:45|level:medium|findings:3|rec:review|src:github+sentry

Usage Example:

Copy// AI assistant validates before applying changes
const validation = await mcp.call('snapback_validate_change', {
  files: [{
    path: 'src/auth.ts',
    content: '// proposed new content...'
  }],
  context: {
    intent: 'Add JWT token refresh logic',
    relatedIssues: ['#123']
  }
});

if (validation.validationResult.recommendation === 'block') {
  console.warn('High risk detected - review required');
}

2. snapback_get_risk_score - Weighted Risk Assessment

Get comprehensive risk score with weighted factors from multiple sources.

Parameters:

Copy{
  files: string[];         // File paths to analyze
  includeContext?: boolean; // Include full context details
}

Response:

Copy{
  riskScore: number;       // 0-100 weighted score
  riskLevel: 'low' | 'medium' | 'high' | 'critical';
  factors: Array<{
    source: 'github' | 'sentry' | 'context7' | 'local';
    weight: number;        // 0-1 contribution to score
    score: number;         // 0-100 for this factor
    reason: string;
  }>;
  recommendation: string;
  confidence: number;      // 0-100 overall confidence
}

Wire Response:

Copy🎯|R|score:67|level:high|factors:4|conf:85|rec:snapshot_first

Usage Example:

Copyconst risk = await mcp.call('snapback_get_risk_score', {
  files: ['src/payment.ts', 'src/api.ts'],
  includeContext: true
});

console.log(`Risk: ${risk.riskLevel} (${risk.riskScore}/100)`);
risk.factors.forEach(f => {
  console.log(`- ${f.source}: ${f.score} (weight: ${f.weight})`);
});

3. snapback_query_patterns - Pattern Database Query

Query SnapBack’s patterns, violations, and learnings database.

Parameters:

Copy{
  query: string;           // Search query
  type?: 'pattern' | 'violation' | 'learning' | 'all';
  filters?: {
    files?: string[];      // Filter by file patterns
    severity?: string[];   // Filter by severity
    since?: string;        // ISO date - patterns since date
  };
  limit?: number;          // Max results (default: 10)
}

Response:

Copy{
  results: Array<{
    type: 'pattern' | 'violation' | 'learning';
    id: string;
    trigger: string;       // When this applies
    action: string;        // What to do
    occurrences: number;   // How many times seen
    lastSeen: string;      // ISO date
    confidence: number;    // 0-100
    relatedFiles: string[];
  }>;
  total: number;
  query: string;
}

Wire Response:

Copy🔎|P|results:7|type:violation|query:auth|conf:92

Usage Example:

Copy// Check for known auth-related pitfalls
const patterns = await mcp.call('snapback_query_patterns', {
  query: 'authentication',
  type: 'violation',
  filters: { severity: ['high', 'critical'] }
});

patterns.results.forEach(p => {
  console.log(`⚠️ ${p.trigger} → ${p.action}`);
});

4. snapback_get_context - Aggregated External Context

Get comprehensive context from all integrated external sources.

Parameters:

Copy{
  files: string[];         // Files to get context for
  sources?: Array<'github' | 'sentry' | 'context7' | 'local'>; // Filter sources
  depth?: 'shallow' | 'deep'; // Context depth
}

Response:

Copy{
  context: {
    github?: {
      recentCommits: Array<{...}>;
      relatedPRs: Array<{...}>;
      issues: Array<{...}>;
    };
    sentry?: {
      recentErrors: Array<{...}>;
      errorFrequency: number;
      affectedUsers: number;
    };
    context7?: {
      apiDocs: Array<{...}>;
      deprecations: Array<{...}>;
      versionInfo: {...};
    };
    local?: {
      snapshots: number;
      changeVelocity: number;
      aiDetectionSignals: Array<{...}>;
    };
  };
  aggregatedAt: string;    // ISO timestamp
  sources: string[];       // Active sources
}

Wire Response:

Copy🌐|C|sources:3|commits:12|errors:5|docs:8|depth:deep

Usage Example:

Copyconst context = await mcp.call('snapback_get_context', {
  files: ['src/auth.ts'],
  sources: ['github', 'sentry'],
  depth: 'deep'
});

if (context.context.sentry?.errorFrequency > 10) {
  console.warn('High error rate detected in this file');
}

5. snapback_suggest_rollback - Intelligent Rollback Suggestions

Get rollback suggestions based on failure patterns and context.

Parameters:

Copy{
  reason?: string;         // Why rollback is needed
  files?: string[];        // Specific files to consider
  includeAnalysis?: boolean; // Include detailed analysis
}

Response:

Copy{
  suggestions: Array<{
    snapshotId: string;
    timestamp: string;
    reason: string;
    confidence: number;    // 0-100
    filesAffected: string[];
    riskOfRollback: 'low' | 'medium' | 'high';
    relatedContext: {
      commitsBetween?: number;
      errorsSince?: number;
    };
  }>;
  recommended?: string;    // Recommended snapshot ID
  analysis?: {             // If includeAnalysis: true
    currentState: {...};
    targetState: {...};
    impact: {...};
  };
}

Wire Response:

Copy🔄|RB|suggestions:3|recommended:snap_abc|conf:88|risk:low

Usage Example:

Copyconst rollback = await mcp.call('snapback_suggest_rollback', {
  reason: 'Critical error after auth refactor',
  files: ['src/auth.ts'],
  includeAnalysis: true
});

const best = rollback.suggestions[0];
console.log(`Suggest rolling back to: ${best.snapshotId}`);
console.log(`Confidence: ${best.confidence}%`);
console.log(`Risk: ${best.riskOfRollback}`);

Setup External MCP Servers

Copy# Install GitHub MCP server
npm install -g @modelcontextprotocol/server-github

# Configure in MCP settings
# Add to your AI assistant's MCP config:
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Copy# Install Sentry MCP server
npm install -g @modelcontextprotocol/server-sentry

# Configure in MCP settings
{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-sentry"],
      "env": {
        "SENTRY_AUTH_TOKEN": "your_token_here",
        "SENTRY_ORG": "your-org",
        "SENTRY_PROJECT": "your-project"
      }
    }
  }
}

Copy# Install Context7 MCP (requires subscription)
npm install -g @context7/mcp-server

# Configure in MCP settings
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["@context7/mcp-server"],
      "env": {
        "CONTEXT7_API_KEY": "your_api_key"
      }
    }
  }
}

Integration Architecture

CopyAI Assistant
     │
     ▼
SnapBack MCP Server (Local)
     │
     ├──► GitHub MCP ──► GitHub API
     ├──► Sentry MCP ──► Sentry API
     └──► Context7 MCP ──► Context7 API
          │
          ▼
    Aggregated Context
          │
          ▼
    Risk Engine (Weighted Scoring)
          │
          ▼
    Intelligence Response

Privacy Note: External MCP servers make API calls using YOUR tokens/credentials. SnapBack orchestrates these calls but doesn’t store or transmit your credentials.

Backend MCP (Planned)

What’s Planned

Backend MCP will add cloud-powered capabilities to your local MCP integration:

Privacy Notice

What’s Uploaded (with Backend MCP):

• ✓ Snapshot metadata: File paths, sizes, hashes (encrypted)
• ✓ Risk analysis results: Severity scores, violation types (no code content)
• ✓ Session metadata: Session names, durations, tag data
• ✓ Policy configurations: File policies, team .snapbackrc settings

What’s Never Uploaded:

• ❌ File contents (unless cloud backup is explicitly enabled)
• ❌ API keys or secrets (always redacted)
• ❌ Personal identifiable information (PII is sanitized)
• ❌ Source code snippets (only metadata and hashes)

Planned Backend Tools

cloud_backup (Planned)

Upload a snapshot to encrypted cloud storage.

Parameters:

Copy{
  snapshotId: string;
  workspacePath: string;
  retention?: number; // days (default: tier-based)
}

cloud_restore (Planned)

Restore a snapshot from cloud storage to your local machine.

guardian_ai_score (Planned)

Analyze code using cloud-based Guardian AI for enhanced risk detection.

Key Differences from Local analyze_risk:

• ☁️ Cloud-based ML model (higher accuracy)
• 📊 Confidence scores and explanations
• 🔧 Suggested fixes for violations
• 🚀 Faster analysis for large codebases (parallel processing)

Configuration for All Supported AI Assistants

Supported AI Assistants

SnapBack supports 11 AI assistants with automatic MCP configuration:

1. Claude Desktop — Anthropic’s desktop app
2. Cursor — AI-first code editor
3. Windsurf — Codeium’s AI editor
4. Qoder — AI coding assistant
5. VS Code — With MCP extensions
6. Continue — Open source AI assistant
7. Cline — Claude-powered coding assistant
8. Zed — High-performance editor
9. Roo Code — AI coding companion
10. Aider — AI pair programmer (CLI)
11. Gemini/Antigravity — Google’s AI assistant

Multi-Workspace Architecture

Example:

CopyCursor Workspace A → snap mcp --stdio --workspace /path/to/project-a → Process #1
Cursor Workspace B → snap mcp --stdio --workspace /path/to/project-b → Process #2
Cursor Workspace C → snap mcp --stdio --workspace /path/to/project-c → Process #3
                                    ↓
              All connect to: ~/.snapback/daemon/daemon.sock

Benefits:

• ✅ Isolation — Changes in one workspace don’t affect others
• ✅ Performance — Each server only watches its own files
• ✅ Reliability — If one crashes, others keep working
• ✅ Scalability — No cross-workspace coordination overhead

Manual Configuration by Client

Understanding Transport Modes

SnapBack’s MCP server can operate in different transport modes:

--stdio Mode (Recommended)

Direct local communication using standard input/output streams. This is the default and recommended mode for all local development.

Copysnap mcp --stdio --workspace /path/to/project

Characteristics:

• ✅ 100% local, no network requests
• ✅ Fastest response time (no network latency)
• ✅ Works completely offline
• ✅ Full privacy guarantee
• ✅ Supported by all major AI assistants

Use this when: You want local, private MCP functionality (99% of use cases).

shim Mode (Advanced)

A stdio-to-SSE bridge that proxies local stdio requests to a remote Server-Sent Events endpoint at https://snapback-mcp.fly.dev.

Copysnap mcp shim --workspace /path/to/project

Characteristics:

• ☁️ Connects to remote Fly.io server
• 🌐 Requires internet connectivity
• ⚠️ May encounter 404 errors if server not deployed
• 🔄 Intended for stdio-only clients that need remote features

Use this when: You specifically need to connect stdio-only clients (like certain AI assistants) to a remote SSE-enabled MCP server.

Copy"args": ["mcp", "shim", "--workspace", "..."]

Copy"args": ["mcp", "--stdio", "--workspace", "..."]

1. Claude Desktop

Config File Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

Copy{
  "mcpServers": {
    "snapback": {
      "command": "npx",
      "args": [
        "@snapback/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "${workspaceFolder}"
      ]
    }
  }
}

2. Cursor

Config File Locations:

• Project-level (recommended): .cursor/mcp.json in your project root
• Global: ~/.cursor/mcp.json

Project-Level Configuration (Recommended):

Copy{
  "mcpServers": {
    "snapback": {
      "command": "npx",
      "args": [
        "@snapback/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "${workspaceFolder}"
      ]
    }
  }
}

Global Configuration:

Copy{
  "mcpServers": {
    "snapback": {
      "command": "npx",
      "args": [
        "@snapback/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "${workspaceFolder}"
      ]
    }
  }
}

3. Windsurf

Config File Location: ~/.codeium/windsurf/mcp_config.json

Configuration:

Copy{
  "mcpServers": {
    "snapback": {
      "command": "npx",
      "args": [
        "@snapback/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "${workspaceFolder}"
      ]
    }
  }
}

4. Qoder

Config File Locations:

• macOS: ~/Library/Application Support/Qoder/SharedClientCache/extension/local/mcp.json
• Windows: %APPDATA%\Qoder\mcp.json
• Linux: ~/.config/Qoder/mcp.json
• Project-level: .qoder-mcp-config.json in your project root

Configuration:

Copy{
  "mcpServers": {
    "snapback": {
      "command": "npx",
      "args": [
        "@snapback/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "${workspaceFolder}"
      ]
    }
  }
}

5. VS Code

Config File Location: .vscode/mcp.json in your project root

Configuration:

Copy{
  "servers": {
    "snapback": {
      "command": "npx",
      "args": [
        "@snapback/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "${workspaceFolder}"
      ]
    }
  }
}

6. Continue

Config File Location: ~/.continue/config.json

Configuration:

Copy{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "snapback",
        "command": "npx",
        "args": [
          "@snapback/cli",
          "mcp",
          "--stdio"
        ]
      }
    ]
  }
}

7. Cline

Config File Location: ~/.cline/mcp.json

Configuration:

Copy{
  "mcpServers": {
    "snapback": {
      "command": "npx",
      "args": [
        "@snapback/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "${workspaceFolder}"
      ]
    }
  }
}

8. Zed

Config File Location: ~/.config/zed/settings.json

Configuration:

Copy{
  "context_servers": {
    "snapback": {
      "command": "npx",
      "args": [
        "@snapback/cli",
        "mcp",
        "--stdio"
      ]
    }
  }
}

9. Roo Code

Config File Location: ~/.roo-code/mcp.json

Configuration:

Copy{
  "mcpServers": {
    "snapback": {
      "command": "npx",
      "args": [
        "@snapback/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "${workspaceFolder}"
      ]
    }
  }
}

10. Aider (CLI)

Config File Location: ~/.aider/mcp.yaml

Configuration (YAML):

Copyservers:
  snapback:
    command: npx
    args:
      - "@snapback/cli"
      - mcp
      - --stdio

11. Gemini/Antigravity

Config File Location: ~/.gemini/settings.json

Configuration:

Copy{
  "context_servers": {
    "snapback": {
      "command": "npx",
      "args": [
        "@snapback/cli",
        "mcp",
        "--stdio"
      ]
    }
  }
}

Troubleshooting MCP Connections

Status Bar Indicators

The SnapBack VS Code extension shows MCP status in the status bar:

Common Issue: “Checkmark but Disconnected”

Symptom: Status bar shows SB·MCP ✓ (checkmark) but Qoder/Cursor can’t use MCP tools.

What’s Happening:

• The status bar detects the MCP process is running
• But the daemon socket connection is broken
• This creates a false “connected” state

Why It Affects All AI Assistants: All MCP server processes connect to the same daemon socket (~/.snapback/daemon/daemon.sock). When the daemon connection breaks:

• ❌ Qoder’s MCP server → Can’t reach daemon
• ❌ Cursor’s MCP server → Can’t reach daemon
• ❌ Claude’s MCP server → Can’t reach daemon
• ❌ All other AI assistants → Can’t reach daemon

Solution:

1. Quick Fix - Use the New Reconnect Command:

   Copy1. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
   2. Run: SnapBack: MCP Reconnect
   3. Confirm reconnection

   This forces a fresh daemon connection and fixes ALL workspaces and AI assistants at once.

2. Alternative - Run Diagnostics:

   CopyCommand Palette → SnapBack: MCP Diagnose

   This shows:

   • Actual connection state
   • Circuit breaker status
   • Queue depth
   • Daemon health

3. Reset Configuration (if needed):

   CopyCommand Palette → SnapBack: MCP Reset

   Then restart VS Code.

Checking MCP Process Status

See all running MCP servers:

Copyps aux | grep "snap mcp --stdio"

Expected output for 3 workspaces:

Copyuser  12345  snap mcp --stdio --workspace /Users/you/project-a
user  12346  snap mcp --stdio --workspace /Users/you/project-b
user  12347  snap mcp --stdio --workspace /Users/you/project-c

Check daemon socket:

Copyls -la ~/.snapback/daemon/daemon.sock

If the socket doesn’t exist, the daemon isn’t running.

Multi-Workspace Troubleshooting

Problem: One workspace’s MCP works, others don’t.

Cause: Each workspace has its own MCP server process with a different workspace path.

Solution:

1. Verify each workspace has correct path:

   Copy# Check running processes
   ps aux | grep "snap mcp"
   
   # Look for --workspace arguments
   # Each should point to its respective project root

2. Check project-level configs:

   Copy# In each project
   cat .cursor/mcp.json
   cat .qoder-mcp-config.json
   cat .vscode/mcp.json

3. Ensure ${workspaceFolder} variable is used:

   • Good: "--workspace", "${workspaceFolder}"
   • Bad: "--workspace", "/hardcoded/path/to/one/project"

CLI Not Installed

Symptom: Status bar shows SB·MCP ⚠ with “CLI not installed” message.

Solution:

1. Install SnapBack CLI globally:

   Copynpm install -g @snapback/cli

2. Verify installation:

   Copysnap --version
   npx @snapback/cli --version

3. Restart your AI assistant (Cursor, Qoder, etc.)

Configuration Priority

SnapBack looks for MCP configuration in this order:

1. Project-level config (highest priority)

   • .cursor/mcp.json
   • .qoder-mcp-config.json
   • .vscode/mcp.json
   • .windsurf/mcp.json

2. Global config

   • ~/.cursor/mcp.json
   • ~/Library/Application Support/Qoder/.../mcp.json
   • etc.

Auto-Configuration

How it works:

1. Install SnapBack VS Code extension
2. Extension auto-detects installed AI assistants
3. Silently configures MCP for each one
4. Shows toast confirming protection is active

No manual configuration needed!

Supported for auto-configuration:

• ✅ Claude Desktop
• ✅ Cursor
• ✅ Windsurf
• ✅ Qoder
• ✅ VS Code
• ✅ Continue
• ✅ Cline
• ✅ Zed
• ✅ Roo Code

Manual configuration needed:

• ⚠️ Aider (CLI tool, no auto-detect)
• ⚠️ Gemini (less common, may need manual setup)

To manually trigger auto-configuration:

CopyCommand Palette → SnapBack: Configure MCP

Validation Commands

Check your MCP configuration:

Copy# Scan for all AI assistants
snap mcp scan

# Validate configurations
snap mcp validate

# Repair broken configurations
snap mcp repair

VS Code commands:

CopySnapBack: MCP Diagnose     — Show connection status
SnapBack: MCP Reconnect    — Force reconnection
SnapBack: MCP Reset        — Reset configuration state
SnapBack: MCP Validate     — Check all configurations
SnapBack: MCP Status       — Quick status check

Next Steps

• Install SnapBack — Get started in 2 minutes
• Configure for Cursor — Cursor-specific setup
• Configure for Copilot — GitHub Copilot integration
• Learn about AI detection — How SnapBack detects AI changes