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

Recommended Setup

Copy# Or install via CLI
code --install-extension MarcelleLabs.snapback-vscode

Copynpm install -g @snapback/cli
snap tools configure --claude

Copysnap login

Manual Setup (Advanced)

Continue

Configure in .continue/config.json:

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

SOPR MCP Open-Source Library

SnapBack’s MCP integration is powered by an internal implementation of the Service-Oriented Protocol Router (SOPR) pattern.

For teams who want to reuse that architecture directly, we publish the core server framework as an open-source NPM package:

• Library: @snapback-oss/sopr-mcp
• Source: snapback-oss/snapback-mcp

This library gives you:

• A SOPR-based MCP server factory (createSOPRServer) built around the same protocol → registry → tools → services layering used in SnapBack
• First-class support for mode-based tools instead of a large, flat list of commands
• Extension points for routers, telemetry, and resilience, so you can plug in your own transport and analytics

Tip: Start with the library docs in the repository’s docs/ folder:

• docs/architecture.mdx – how the SOPR MCP server is wired internally
• docs/usage-sopr-mcp.mdx – how to build your own MCP server on top of it
• docs/diagrams.mdx – visual diagrams of the architecture and request flow

If you like how SnapBack behaves inside your editor today, @snapback-oss/sopr-mcp is the foundation you can reuse to build similar MCP-powered workflows for your own tools.

Default Surface (Minimal)

Core Commands (5):

• 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

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 detection
• 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) ⚡ RECOMMENDED
• full: Comprehensive 7-layer validation 🎯 PRODUCTION READY
• 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: ❌ NOT YET IMPLEMENTED - Returns error message. Use quick or full instead.
• 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_learn - Capture Learning (REFLECT)

Capture mid-session learnings for future reference. Use this mid-task for immediate learnings (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'
});

7. 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 Restore Suggestions

Get restore suggestions based on failure patterns and context.

Parameters:

Copy{
  reason?: string;         // Why restore 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[];
    riskOfRestore: '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 restore = await mcp.call('snapback_suggest_rollback', {
  reason: 'Critical error after auth refactor',
  files: ['src/auth.ts'],
  includeAnalysis: true
});

const best = restore.suggestions[0];
console.log(`Suggest restoring to: ${best.snapshotId}`);
console.log(`Confidence: ${best.confidence}%`);
console.log(`Risk: ${best.riskOfRestore}`);

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).

--sse Mode (Multi-Client)

Local HTTP Server-Sent Events server for multi-client connections on localhost:8765.

Copy# Start daemon with SSE transport
snap daemon start

# SSE is available at http://localhost:8765/events

Characteristics:

• ✅ Multiple clients can connect simultaneously
• ✅ Persistent connections without stdin overhead
• ✅ Unified authentication with SnapBack account
• ✅ Works with any SSE-compatible MCP client

Configuration:

Set the SSE port (default: 8765):

Copyexport SNAPBACK_SSE_PORT=8765

Connecting to SSE:

Configure your MCP client to connect to the SSE endpoint:

Copy{
  "mcpServers": {
    "snapback": {
      "url": "http://localhost:8765/events",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer sk_live_xxx"
      }
    }
  }
}

Authentication:

SSE transport supports two authentication methods:

1. API Key (recommended): Use your SnapBack API key (sk_live_xxx or sk_test_xxx)

   • Validated against api.snapback.dev
   • Provides user context (tier, permissions) for rate limiting

2. Local Token: Automatically uses your CLI login session

   • Retrieved from ~/.snapback/mcp-token
   • No additional configuration needed

Use this when: Running multiple AI assistants simultaneously or need persistent connections.

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

Manual Configuration:

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

2. Cursor

Config File Locations (for manual setup):

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

Manual Configuration:

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

3. Windsurf

Config File Location (for manual setup): ~/.codeium/windsurf/mcp_config.json

Manual 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 status in the status bar using the 🧢 prefix. Setup gates appear first if any precondition is unmet:

Common Issue: Status Bar Still Shows a Gate State

Symptom: You resolved a setup step (e.g. installed the CLI, configured MCP) but the status bar still shows the gate message.

Why this happens: The status bar refreshes when SnapBack detects a relevant change, such as a daemon state transition. If the daemon was already running and stable, no event fires immediately after you complete a step.

Fix: Click the status bar item again — it re-evaluates all gates. If that doesn’t work, reload VS Code (⌘+Shift+P → Developer: Reload Window).

Common Issue: MCP Tools Work but Daemon Shows Disconnected

Symptom: Your AI assistant can call snap tools, but the status bar shows $(sync~spin) Starting SnapBack... or the daemon appears offline.

What’s happening: The MCP server process is running independently of the daemon socket connection. MCP tool calls can still succeed if the server process is alive, even when the daemon socket is temporarily broken.

Solution:

1. Run ⌘+Shift+P → SnapBack: MCP Reconnect to force a fresh daemon connection.
2. If reconnection fails, run ⌘+Shift+P → SnapBack: MCP Diagnose to see actual state.
3. As a last resort, run ⌘+Shift+P → SnapBack: MCP Reset, then reload 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 $(warning) Install SnapBack CLI.

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 setup commands (status bar gate actions):

CopySnapBack: Install CLI          — Install the SnapBack CLI
SnapBack: Start Daemon         — Start the background daemon
SnapBack: Sign In              — Authenticate with SnapBack
SnapBack: Initialize Workspace — Initialize this workspace
SnapBack: Configure MCP        — Auto-configure MCP for your AI tools

VS Code MCP 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
• CLI Reference — Use SnapBack from the terminal
• How It Works — How SnapBack detects AI changes
• Troubleshooting — Common issues and fixes