Claude Desktop Integration

This section covers comprehensive integration of AIRS MCP-FS with Claude Desktop, including configuration, troubleshooting, and advanced usage patterns.

MCP Server Configuration

Claude Desktop uses JSON configuration to define MCP servers. AIRS MCP-FS integrates as a standard MCP server with additional environment variable support.

Basic Configuration

Add AIRS MCP-FS to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "airsprotocols-mcpserver-filesystem": {
      "command": "/path/to/airsprotocols-mcpserver-filesystem",
      "env": {
        "AIRS_MCP_FS_ENV": "development"
      }
    }
  }
}

Complete Configuration

For full control over AIRS MCP-FS behavior:

{
  "mcpServers": {
    "airsprotocols-mcpserver-filesystem": {
      "command": "/Users/username/path/to/airsprotocols-mcpserver-filesystem",
      "env": {
        "AIRS_MCP_FS_ENV": "development",
        "AIRS_MCP_FS_CONFIG_DIR": "/Users/username/.config/airsprotocols-mcpserver-filesystem",
        "AIRS_MCP_FS_LOG_DIR": "/Users/username/.local/share/airsprotocols-mcpserver-filesystem/logs",
        "RUST_LOG": "info"
      }
    }
  }
}

Environment Variable Configuration

AIRS MCP-FS behavior is controlled through environment variables in the Claude Desktop configuration:

Core Environment Variables

Variable	Purpose	Example	Required
AIRS_MCP_FS_ENV	Environment type	development	Yes
AIRS_MCP_FS_CONFIG_DIR	Configuration directory	~/.config/airsprotocols-mcpserver-filesystem	Recommended
AIRS_MCP_FS_LOG_DIR	Log output directory	~/.local/share/airsprotocols-mcpserver-filesystem/logs	Recommended
RUST_LOG	Logging level	info, debug	Optional

Security Override Variables

Variable	Purpose	Example
AIRS_MCP_FS_SECURITY_FILESYSTEM_ALLOWED_PATHS	Override allowed paths	~/projects/**/*,~/docs/**/*
AIRS_MCP_FS_SECURITY_OPERATIONS_WRITE_REQUIRES_POLICY	Control write policy	false
AIRS_MCP_FS_BINARY_MAX_FILE_SIZE	Max file size	52428800 (50MB)

Configuration Examples

Development Workstation

Ideal for local development with broad file access:

{
  "mcpServers": {
    "airsprotocols-mcpserver-filesystem": {
      "command": "/usr/local/bin/airsprotocols-mcpserver-filesystem",
      "env": {
        "AIRS_MCP_FS_ENV": "development",
        "AIRS_MCP_FS_CONFIG_DIR": "/Users/developer/.config/airsprotocols-mcpserver-filesystem",
        "AIRS_MCP_FS_LOG_DIR": "/Users/developer/.local/share/airsprotocols-mcpserver-filesystem/logs",
        "AIRS_MCP_FS_SECURITY_FILESYSTEM_ALLOWED_PATHS": "/Users/developer/projects/**/*,/Users/developer/Documents/**/*,/Users/developer/Desktop/**/*",
        "RUST_LOG": "info"
      }
    }
  }
}

Content Creation Setup

Optimized for writing, blogging, and content management:

{
  "mcpServers": {
    "airsprotocols-mcpserver-filesystem": {
      "command": "/usr/local/bin/airsprotocols-mcpserver-filesystem",
      "env": {
        "AIRS_MCP_FS_ENV": "development",
        "AIRS_MCP_FS_CONFIG_DIR": "/Users/writer/.config/airsprotocols-mcpserver-filesystem",
        "AIRS_MCP_FS_SECURITY_FILESYSTEM_ALLOWED_PATHS": "/Users/writer/writing/**/*,/Users/writer/blog/**/*,/Users/writer/assets/**/*",
        "AIRS_MCP_FS_BINARY_ENABLE_IMAGE_PROCESSING": "true",
        "AIRS_MCP_FS_BINARY_MAX_FILE_SIZE": "209715200"
      }
    }
  }
}

Secure Production Environment

Minimal permissions for production use:

{
  "mcpServers": {
    "airsprotocols-mcpserver-filesystem": {
      "command": "/opt/airsprotocols-mcpserver-filesystem/bin/airsprotocols-mcpserver-filesystem",
      "env": {
        "AIRS_MCP_FS_ENV": "production",
        "AIRS_MCP_FS_CONFIG_DIR": "/etc/airsprotocols-mcpserver-filesystem",
        "AIRS_MCP_FS_LOG_DIR": "/var/log/airsprotocols-mcpserver-filesystem",
        "AIRS_MCP_FS_SECURITY_FILESYSTEM_ALLOWED_PATHS": "/app/data/**/*.json",
        "AIRS_MCP_FS_SECURITY_OPERATIONS_WRITE_REQUIRES_POLICY": "true",
        "RUST_LOG": "warn"
      }
    }
  }
}

Integration Workflow

Initial Setup Process

1. Install AIRS MCP-FS

   cargo build --release --bin airsprotocols-mcpserver-filesystem
   

2. Generate Configuration

   airsprotocols-mcpserver-filesystem generate-config --env development
   

3. Configure Claude Desktop

   # Edit Claude Desktop configuration
   nano "~/Library/Application Support/Claude/claude_desktop_config.json"
   

4. Restart Claude Desktop

5. Quit Claude Desktop completely

6. Restart to load new MCP server configuration

7. Verify Integration

   User: "List the files in my current directory"
   Claude: *uses list_directory tool* → shows directory contents
   

Configuration Validation

After setup, validate your configuration:

1. Check Configuration Loading

   # Run AIRS MCP-FS manually to check configuration
   AIRS_MCP_FS_ENV=development /path/to/airsprotocols-mcpserver-filesystem
   

2. Verify File Access

   User: "Can you read my README.md file?"
   Claude: *uses read_file tool* → displays README content
   

3. Test Security Policies

   User: "Try to read a file in a restricted directory"
   Claude: *attempts access* → should receive permission denied
   

Advanced Integration Patterns

Multi-Environment Setup

Configure different AIRS MCP-FS instances for different environments:

{
  "mcpServers": {
    "airsprotocols-mcpserver-filesystem-dev": {
      "command": "/usr/local/bin/airsprotocols-mcpserver-filesystem",
      "env": {
        "AIRS_MCP_FS_ENV": "development",
        "AIRS_MCP_FS_CONFIG_DIR": "/Users/dev/.config/airsprotocols-mcpserver-filesystem-dev"
      }
    },
    "airsprotocols-mcpserver-filesystem-prod": {
      "command": "/usr/local/bin/airsprotocols-mcpserver-filesystem",
      "env": {
        "AIRS_MCP_FS_ENV": "production",
        "AIRS_MCP_FS_CONFIG_DIR": "/Users/dev/.config/airsprotocols-mcpserver-filesystem-prod"
      }
    }
  }
}

Project-Specific Configuration

Use different configurations for different projects:

{
  "mcpServers": {
    "airsprotocols-mcpserver-filesystem-project-a": {
      "command": "/usr/local/bin/airsprotocols-mcpserver-filesystem",
      "env": {
        "AIRS_MCP_FS_ENV": "development",
        "AIRS_MCP_FS_SECURITY_FILESYSTEM_ALLOWED_PATHS": "/Users/dev/project-a/**/*"
      }
    },
    "airsprotocols-mcpserver-filesystem-project-b": {
      "command": "/usr/local/bin/airsprotocols-mcpserver-filesystem", 
      "env": {
        "AIRS_MCP_FS_ENV": "development",
        "AIRS_MCP_FS_SECURITY_FILESYSTEM_ALLOWED_PATHS": "/Users/dev/project-b/**/*"
      }
    }
  }
}

MCP Tool Usage

Once configured, Claude Desktop can use AIRS MCP-FS tools:

Available Tools

Tool	Purpose	Example Usage
read_file	Read file contents	"Read my package.json file"
write_file	Create or update files	"Create a new component file"
list_directory	Browse directories	"List files in my src directory"
create_directory	Create directories	"Create a new folder structure"
delete_file	Remove files	"Delete the old backup files"
move_file	Move/rename files	"Rename this file to main.rs"
copy_file	Copy files	"Make a backup copy of this file"

Example Interactions

Reading Project Files

User: "Analyze the structure of my Rust project"
Claude: *uses list_directory and read_file tools*
→ Examines Cargo.toml, src/ directory, and main source files
→ Provides comprehensive project analysis

Creating New Files

User: "Create a new React component for user authentication"
Claude: *uses write_file tool*
→ Creates src/components/AuthComponent.tsx
→ Includes proper TypeScript interfaces and React hooks

File Organization

User: "Organize my Downloads folder by file type"
Claude: *uses list_directory, create_directory, and move_file tools*
→ Creates folders by file type
→ Moves files into appropriate directories
→ Provides summary of organization

Troubleshooting Integration

Common Integration Issues

MCP Server Not Loading

Symptoms: Claude Desktop doesn't show filesystem tools available

Solutions: 1. Check Binary Path

# Verify binary exists and is executable
ls -la /path/to/airsprotocols-mcpserver-filesystem
chmod +x /path/to/airsprotocols-mcpserver-filesystem

1. Validate JSON Configuration

   # Check JSON syntax
   cat "~/Library/Application Support/Claude/claude_desktop_config.json" | python -m json.tool
   

2. Check Logs

   # Check AIRS MCP-FS logs
   tail -f ~/.local/share/airsprotocols-mcpserver-filesystem/logs/airsprotocols-mcpserver-filesystem.log
   

Permission Denied Errors

Symptoms: "Security validation failed: Access denied"

Solutions: 1. Check Allowed Paths

# Verify path is in allowed_paths
[security.filesystem]
allowed_paths = ["/Users/username/Documents/**/*"]

1. Check Glob Patterns

   # Ensure patterns include both directory and contents
   allowed_paths = [
       "/Users/username/Documents",      # Directory itself
       "/Users/username/Documents/**/*"  # Directory contents
   ]
   

2. Review Security Policies

   # Check if operation is allowed by policy
   [security.policies.documents]
   patterns = ["/Users/username/Documents/**/*"]
   operations = ["read", "write", "list"]
   

Configuration Not Loading

Symptoms: AIRS MCP-FS using default configuration instead of custom

Solutions: 1. Verify Environment Variables

{
  "env": {
    "AIRS_MCP_FS_ENV": "development",
    "AIRS_MCP_FS_CONFIG_DIR": "/correct/path/to/config"
  }
}

1. Check File Existence

   # Verify configuration file exists
   ls -la ~/.config/airsprotocols-mcpserver-filesystem/development.toml
   

2. Validate Configuration Syntax

   # Test configuration loading
   AIRS_MCP_FS_ENV=development /path/to/airsprotocols-mcpserver-filesystem
   

Debug Mode

Enable debug logging for detailed troubleshooting:

{
  "mcpServers": {
    "airsprotocols-mcpserver-filesystem": {
      "command": "/usr/local/bin/airsprotocols-mcpserver-filesystem",
      "env": {
        "AIRS_MCP_FS_ENV": "development",
        "RUST_LOG": "debug"
      }
    }
  }
}

This provides detailed logging of: - Configuration loading process - Security validation decisions - MCP protocol communication - File operation execution

Integration Best Practices

Security Best Practices

1. Environment-Specific Configuration: Use different configurations for different environments
2. Minimal Permissions: Grant only necessary file access permissions
3. Regular Updates: Keep AIRS MCP-FS updated for security fixes
4. Audit Logging: Monitor file access patterns and unusual activity

Configuration Management

1. Version Control: Keep configuration files in version control
2. Documentation: Document environment-specific settings
3. Testing: Test configuration changes before deploying
4. Backup: Maintain backup configurations for rollback

Performance Optimization

1. Specific Paths: Use specific path patterns to reduce security checking overhead
2. File Size Limits: Set appropriate file size limits for your use case
3. Binary Processing: Disable unused binary processing features
4. Log Levels: Use appropriate log levels (avoid debug in production)

Maintenance

1. Regular Reviews: Periodically review and update configurations
2. Log Monitoring: Monitor logs for errors and security issues
3. Performance Monitoring: Track file operation performance
4. Update Planning: Plan for AIRS MCP-FS updates and migrations

Related Sections

• Configuration Overview: Overall configuration architecture
• Environment Setup: Environment-specific configuration
• Security Policies: Security policy configuration
• Troubleshooting: Detailed troubleshooting guide