Using SnapBack with Claude Desktop

Claude Desktop is Anthropic’s standalone AI assistant app for macOS and Windows. SnapBack integrates with Claude Desktop through the Model Context Protocol (MCP), enabling Claude to understand your project’s risk context.

Important: Claude Desktop only supports stdio transport for MCP servers. This is different from Claude Code (CLI) which supports both stdio and HTTP transport.

Quick Setup

Install the SnapBack CLI

npm install -g @snapback/cli

Or with pnpm/yarn:

pnpm add -g @snapback/cli
# or
yarn global add @snapback/cli

Configure Claude Desktop

Run the automatic configuration:

snap tools configure --claude

This creates the correct MCP configuration in your Claude Desktop config file.

Restart Claude Desktop

Quit and reopen Claude Desktop. You should see “snapback” listed in the MCP servers.

Manual Configuration

If automatic configuration doesn’t work, you can manually configure:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Edit %APPDATA%\Claude\claude_desktop_config.json:

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

Edit ~/.config/Claude/claude_desktop_config.json:

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

Replace /path/to/your/project with the actual path to your workspace. This tells SnapBack which project to monitor.

Understanding Transport Types

Claude Desktop only supports stdio transport. This means:

Transport	Claude Desktop	Cursor	VS Code	Windsurf
stdio (command + args)	✅ Required	✅	✅	✅
HTTP (url)	❌ Not supported	✅	✅	✅

Stdio transport runs the MCP server as a subprocess:

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

HTTP transport connects to a running server (not supported by Claude Desktop):

{
  "url": "http://localhost:3333"
}

Troubleshooting

Error: “command” field expected but received undefined

This error occurs when Claude Desktop receives HTTP transport configuration instead of stdio:

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

Solution: Ensure your config uses command + args, not url:

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

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

Error: Command not found

If Claude Desktop can’t find the npx command:

Verify npx is installed:

which npx
# Should return something like /usr/local/bin/npx

Use absolute path:

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

Or use node directly:

# Find your global npm modules
npm root -g
# e.g., /usr/local/lib/node_modules

Then configure:

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

MCP Server Not Starting

Test the CLI manually:
```
snap mcp --help
```

Verify workspace is valid:

# Should have .git/, package.json, or .snapback/
ls -la /your/project

Check Claude Desktop logs:
- macOS: ~/Library/Logs/Claude/
- Windows: %APPDATA%\Claude\logs\

Repair Configuration

If configuration is corrupted, reset it:

# Remove and reconfigure
snap tools configure --claude --force

Available MCP Tools

Once configured, Claude Desktop can use these SnapBack tools:

Tool	Description
`snap`	Start tasks, get context, quick validation
`check`	Validate code against patterns
`snap_end`	Complete tasks and capture learnings
`snap_fix`	List and restore snapshots
`snap_learn`	Capture mid-session insights
`snap_violation`	Report mistakes for pattern learning

See Local MCP Tools for full documentation.

Privacy Note

All MCP communication is local. Claude Desktop runs the SnapBack CLI on your machine. No code or data is sent to external servers.

Next Steps

MCP Tools Reference - Full tool documentation
Cursor Integration - If also using Cursor
Claude Code Integration - For Claude Code CLI users