Skip to main content

🔌 MCP Client Configuration Reference

Complete guide to configuring MCP ADR Analysis Server with different MCP clients.

📋 Quick Setup Matrix​

ClientConfig FileCommandBest For
Claude Desktopclaude_desktop_config.jsonmcp-adr-analysis-serverGeneral use, best AI integration
Clinecline_mcp_settings.jsonnpx mcp-adr-analysis-serverVS Code development
Cursor.cursor/mcp.jsonnpx mcp-adr-analysis-serverAI-powered coding
Geminigemini_mcp_config.jsonmcp-adr-analysis-serverGoogle AI integration
Windsurfmcp_config.jsonmcp-adr-analysis-serverProfessional development
Continue.devconfig.jsonnpx mcp-adr-analysis-serverVS Code AI extension
Aider.aider_config.yamlmcp-adr-analysis-serverCommand-line AI coding

Configuration Location​

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

Basic Configuration​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/absolute/path/to/your/project",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "your_firecrawl_api_key_here"
      }
    }
  }
}

Advanced Configuration​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/Users/username/my-project",
        "OPENROUTER_API_KEY": "sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxx",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "ERROR",
        "AI_TEMPERATURE": "0.1",
        "AI_MAX_TOKENS": "4000",
        "AI_CACHE_ENABLED": "true",
        "ENABLE_CONTENT_MASKING": "true",
        "MASKING_LEVEL": "moderate"
      }
    }
  }
}

Multi-Project Setup​

{
  "mcpServers": {
    "adr-frontend": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/Users/username/frontend-project",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "ERROR"
      }
    },
    "adr-backend": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/Users/username/backend-project",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full",
        "ADR_DIRECTORY": "architecture/decisions",
        "LOG_LEVEL": "ERROR"
      }
    }
  }
}

Troubleshooting Claude Desktop​

Common Issues:

  1. "Server not found"

    # Verify installation
    which mcp-adr-analysis-server
    mcp-adr-analysis-server --version

  2. "Permission denied"

    {
      "env": {
        "PROJECT_PATH": "/absolute/path/not/relative"
      }
    }

  3. "Tools return prompts"

    {
      "env": {
        "EXECUTION_MODE": "full",
        "OPENROUTER_API_KEY": "required_for_ai"
      }
    }

🔧 Cline (VS Code Extension)​

Configuration Location​

File: cline_mcp_settings.json (in workspace or global settings)

Basic Configuration​

{
  "mcpServers": {
    "mcp-adr-analysis-server": {
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": "${workspaceFolder}",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "ERROR",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "your_firecrawl_api_key"
      }
    }
  }
}

Development Configuration​

{
  "mcpServers": {
    "mcp-adr-analysis-server": {
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": "${workspaceFolder}",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-haiku",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "DEBUG",
        "AI_CACHE_ENABLED": "true",
        "TIMING_ENABLED": "true",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "your_firecrawl_key"
      }
    }
  }
}

Workspace-Specific Configuration​

Create .vscode/cline_mcp_settings.json:

{
  "mcpServers": {
    "project-adr-analysis": {
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": "${workspaceFolder}",
        "OPENROUTER_API_KEY": "${env:OPENROUTER_API_KEY}",
        "EXECUTION_MODE": "full",
        "ADR_DIRECTORY": "architecture/adrs",
        "LOG_LEVEL": "INFO",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "${env:FIRECRAWL_API_KEY}"
      }
    }
  }
}

Cline Best Practices​

  1. Use workspace variables: ${workspaceFolder} for PROJECT_PATH
  2. Environment variables: ${env:VAR_NAME} for secrets
  3. npx command: Ensures latest version without global install
  4. DEBUG logging: Helpful during development

🎯 Cursor​

Configuration Location​

File: .cursor/mcp.json (in project root)

Basic Configuration​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": ".",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "ERROR",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "your_firecrawl_api_key_here"
      }
    }
  }
}

AI-Optimized Configuration​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": ".",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "ERROR",
        "AI_TEMPERATURE": "0.05",
        "AI_MAX_TOKENS": "3000",
        "ENABLE_CONTENT_MASKING": "true"
      }
    }
  }
}

Team Configuration​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": ".",
        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "ADR_DIRECTORY": "./architecture/decisions",
        "LOG_LEVEL": "WARN",
        "AI_CACHE_ENABLED": "true",
        "MASKING_LEVEL": "strict"
      }
    }
  }
}

Cursor Tips​

  1. Relative paths: Use "." for PROJECT_PATH in Cursor
  2. Environment variables: Reference with ${VAR_NAME}
  3. Version in .gitignore: Add .cursor/ to .gitignore if it contains secrets
  4. Team sharing: Use environment variables for API keys

🤖 Gemini (Google AI)​

Configuration Location​

File: gemini_mcp_config.json (in project root or user config directory)

Basic Configuration​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/absolute/path/to/project",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "google/gemini-pro",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Google AI Optimized Configuration​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/Users/username/project",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "google/gemini-pro-1.5",
        "ADR_DIRECTORY": "./architecture/decisions",
        "LOG_LEVEL": "INFO",
        "AI_TEMPERATURE": "0.2",
        "AI_MAX_TOKENS": "8192",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "your_firecrawl_key"
      }
    }
  }
}

Gemini Best Practices​

  1. Model Selection: Use google/gemini-pro-1.5 for best performance
  2. Temperature: Lower values (0.1-0.3) for consistent architectural analysis
  3. Token Limits: Gemini supports larger contexts, use higher limits
  4. Multimodal: Gemini can process images and documents in ADRs

🔄 Continue.dev (VS Code Extension)​

Configuration Location​

File: config.json (in .continue directory)

Basic Configuration​

{
  "mcpServers": [
    {
      "name": "adr-analysis",
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": "${workspaceFolder}",
        "OPENROUTER_API_KEY": "${env:OPENROUTER_API_KEY}",
        "EXECUTION_MODE": "full",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "INFO"
      }
    }
  ]
}

VS Code Integration Configuration​

{
  "mcpServers": [
    {
      "name": "adr-analysis",
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": "${workspaceFolder}",
        "OPENROUTER_API_KEY": "${env:OPENROUTER_API_KEY}",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "ADR_DIRECTORY": "./docs/adrs",
        "LOG_LEVEL": "DEBUG",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "${env:FIRECRAWL_API_KEY}"
      }
    }
  ]
}

Continue.dev Best Practices​

  1. Workspace Integration: Use ${workspaceFolder} for seamless VS Code integration
  2. Environment Variables: Leverage VS Code's environment variable support
  3. Debug Mode: Enable DEBUG logging for development troubleshooting
  4. Multi-Project: Configure different servers for different workspace folders

🛠️ Aider (Command Line)​

Configuration Location​

File: .aider_config.yaml (in project root or home directory)

Basic Configuration​

mcp_servers:
  - name: adr-analysis
    command: mcp-adr-analysis-server
    env:
      PROJECT_PATH: "/absolute/path/to/project"
      OPENROUTER_API_KEY: "your_openrouter_api_key_here"
      EXECUTION_MODE: "full"
      ADR_DIRECTORY: "./adrs"
      LOG_LEVEL: "INFO"

Advanced Aider Configuration​

mcp_servers:
  - name: adr-analysis
    command: mcp-adr-analysis-server
    env:
      PROJECT_PATH: "/Users/username/project"
      OPENROUTER_API_KEY: "your_key_here"
      EXECUTION_MODE: "full"
      AI_MODEL: "anthropic/claude-3-sonnet"
      ADR_DIRECTORY: "./architecture/decisions"
      LOG_LEVEL: "DEBUG"
      AI_TEMPERATURE: "0.1"
      AI_MAX_TOKENS: "4000"
      FIRECRAWL_ENABLED: "true"
      FIRECRAWL_API_KEY: "your_firecrawl_key"
      ENABLE_CONTENT_MASKING: "true"
      MASKING_LEVEL: "strict"

Aider Best Practices​

  1. YAML Format: Use proper YAML indentation and syntax
  2. Absolute Paths: Always use absolute paths for PROJECT_PATH
  3. Security: Enable content masking for sensitive projects
  4. Performance: Use DEBUG logging only when needed

🌊 Windsurf​

Configuration Location​

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

Basic Configuration​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "args": [],
      "env": {
        "PROJECT_PATH": "/absolute/path/to/your/project",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "ERROR",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "your_firecrawl_api_key_here"
      }
    }
  }
}

Professional Configuration​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "args": [],
      "env": {
        "PROJECT_PATH": "/Users/developer/current-project",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "ERROR",
        "AI_CACHE_ENABLED": "true",
        "AI_CACHE_TTL": "3600",
        "ENABLE_CONTENT_MASKING": "true",
        "MASKING_LEVEL": "strict"
      }
    }
  }
}

Enterprise Configuration​

{
  "mcpServers": {
    "enterprise-adr": {
      "command": "mcp-adr-analysis-server",
      "args": [],
      "env": {
        "PROJECT_PATH": "/enterprise/project/path",
        "OPENROUTER_API_KEY": "enterprise_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "ADR_DIRECTORY": "architecture/decisions",
        "LOG_LEVEL": "WARN",
        "AI_TEMPERATURE": "0.1",
        "AI_MAX_TOKENS": "4000",
        "ENABLE_CONTENT_MASKING": "true",
        "MASKING_LEVEL": "strict",
        "CUSTOM_SECRET_PATTERNS": "ENTERPRISE_.*,INTERNAL_.*"
      }
    }
  }
}

🔧 Alternative Clients​

Continue (VS Code Extension)​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "${workspaceFolder}",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full"
      }
    }
  }
}

Custom MCP Client​

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({
  name: 'adr-analysis-client',
  version: '1.0.0',
});

await client.connect({
  command: 'mcp-adr-analysis-server',
  env: {
    PROJECT_PATH: '/path/to/project',
    OPENROUTER_API_KEY: 'your_key_here',
    EXECUTION_MODE: 'full',
  },
});

🚀 Performance Optimization​

Fast Configuration (Development)​

{
  "env": {
    "AI_MODEL": "anthropic/claude-3-haiku",
    "AI_MAX_TOKENS": "2000",
    "AI_TEMPERATURE": "0.05",
    "AI_CACHE_ENABLED": "true",
    "LOG_LEVEL": "ERROR"
  }
}

Quality Configuration (Production)​

{
  "env": {
    "AI_MODEL": "anthropic/claude-3-sonnet",
    "AI_MAX_TOKENS": "4000",
    "AI_TEMPERATURE": "0.1",
    "AI_CACHE_ENABLED": "true",
    "AI_CACHE_TTL": "86400",
    "LOG_LEVEL": "WARN"
  }
}

Large Project Configuration​

{
  "env": {
    "MAX_FILES_PER_ANALYSIS": "500",
    "MAX_RECURSION_DEPTH": "5",
    "AI_TIMEOUT": "120000",
    "CACHE_DIRECTORY": "/tmp/mcp-cache",
    "MAX_CACHE_SIZE": "500MB"
  }
}

🔥 Firecrawl Configuration​

Firecrawl integration provides enhanced web research capabilities for comprehensive architectural analysis.

Firecrawl Environment Variables​

VariableRequiredDefaultDescription
FIRECRAWL_ENABLEDNofalseEnable Firecrawl integration
FIRECRAWL_API_KEYNo*-API key for cloud service
FIRECRAWL_BASE_URLNohttp://localhost:3000Self-hosted instance URL

*Required if using cloud service

Configuration Examples​

{
  "env": {
    "FIRECRAWL_ENABLED": "true",
    "FIRECRAWL_API_KEY": "fc-your-api-key-here"
  }
}

Self-Hosted​

{
  "env": {
    "FIRECRAWL_ENABLED": "true",
    "FIRECRAWL_BASE_URL": "http://localhost:3000"
  }
}

Disabled (Default)​

{
  "env": {
    "FIRECRAWL_ENABLED": "false"
  }
}

Client-Specific Firecrawl Configuration​

Claude Desktop​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/absolute/path/to/project",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "fc-your-api-key-here"
      }
    }
  }
}

Cline (VS Code)​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": "${workspaceFolder}",
        "OPENROUTER_API_KEY": "${env:OPENROUTER_API_KEY}",
        "EXECUTION_MODE": "full",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "${env:FIRECRAWL_API_KEY}"
      }
    }
  }
}

Cursor​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": ".",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "fc-your-api-key-here"
      }
    }
  }
}

Gemini​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/absolute/path/to/project",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "google/gemini-pro-1.5",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "fc-your-api-key-here"
      }
    }
  }
}

Continue.dev​

{
  "mcpServers": [
    {
      "name": "adr-analysis",
      "command": "npx",
      "args": ["mcp-adr-analysis-server"],
      "env": {
        "PROJECT_PATH": "${workspaceFolder}",
        "OPENROUTER_API_KEY": "${env:OPENROUTER_API_KEY}",
        "EXECUTION_MODE": "full",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "${env:FIRECRAWL_API_KEY}"
      }
    }
  ]
}

Aider (YAML)​

mcp_servers:
  - name: adr-analysis
    command: mcp-adr-analysis-server
    env:
      PROJECT_PATH: "/absolute/path/to/project"
      OPENROUTER_API_KEY: "your_key_here"
      EXECUTION_MODE: "full"
      FIRECRAWL_ENABLED: "true"
      FIRECRAWL_API_KEY: "fc-your-api-key-here"

Windsurf​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "args": [],
      "env": {
        "PROJECT_PATH": "/absolute/path/to/project",
        "OPENROUTER_API_KEY": "your_key_here",
        "EXECUTION_MODE": "full",
        "FIRECRAWL_ENABLED": "true",
        "FIRECRAWL_API_KEY": "fc-your-api-key-here"
      }
    }
  }
}

Firecrawl Benefits​

  • Real-time Research - Access current best practices and architectural patterns
  • Enhanced ADRs - Generate more comprehensive decision records with external context
  • Intelligent Scraping - Extract relevant content from technical documentation and blogs
  • Fallback Support - Graceful degradation when web search is unavailable

Getting Your Firecrawl API Key​

  1. Visit: https://firecrawl.dev
  2. Sign up for an account
  3. Get your API key (starts with "fc-")
  4. Add to configuration as shown above

🚨 Client-Specific Troubleshooting​

Claude Desktop Issues​

"Server not found" or "Unknown tool"​

# 1. Verify global installation
which mcp-adr-analysis-server
npm list -g mcp-adr-analysis-server

# 2. Check PATH in Claude Desktop
# Ensure Node.js and npm are in your system PATH
echo $PATH | grep -E "(node|npm)"

# 3. Restart Claude Desktop after installation

"Permission denied" errors​

{
  "env": {
    "PROJECT_PATH": "/absolute/path/not/relative"
  }
}

"Tools return prompts instead of results"​

{
  "env": {
    "EXECUTION_MODE": "full",
    "OPENROUTER_API_KEY": "required_for_ai_features"
  }
}

Cline (VS Code) Issues​

"Command not found: npx"​

# Install Node.js and npm
# Then verify installation
node --version
npm --version

"Workspace folder not found"​

{
  "env": {
    "PROJECT_PATH": "${workspaceFolder}"
  }
}

"Environment variables not resolved"​

{
  "env": {
    "OPENROUTER_API_KEY": "${env:OPENROUTER_API_KEY}"
  }
}

Cursor Issues​

"Relative paths not working"​

{
  "env": {
    "PROJECT_PATH": "/absolute/path/to/project"
  }
}

"npx command fails"​

{
  "command": "mcp-adr-analysis-server",
  "args": []
}

Gemini Issues​

"Model not supported"​

{
  "env": {
    "AI_MODEL": "google/gemini-pro-1.5"
  }
}

"Token limit exceeded"​

{
  "env": {
    "AI_MAX_TOKENS": "8192"
  }
}

Continue.dev Issues​

"Array format expected"​

{
  "mcpServers": [
    {
      "name": "adr-analysis",
      "command": "npx",
      "args": ["mcp-adr-analysis-server"]
    }
  ]
}

"Workspace folder not accessible"​

{
  "env": {
    "PROJECT_PATH": "${workspaceFolder}"
  }
}

Aider Issues​

"YAML syntax error"​

# Check indentation (use spaces, not tabs)
mcp_servers:
  - name: adr-analysis
    command: mcp-adr-analysis-server
    env:
      PROJECT_PATH: "/absolute/path"

"Command not found"​

# Ensure mcp-adr-analysis-server is in PATH
which mcp-adr-analysis-server

Windsurf Issues​

"Configuration not loaded"​

# Check file location
ls -la ~/.codeium/windsurf/mcp_config.json

# Ensure proper JSON syntax
cat ~/.codeium/windsurf/mcp_config.json | jq .

"Environment variables not working"​

{
  "env": {
    "PROJECT_PATH": "/absolute/path",
    "OPENROUTER_API_KEY": "your_key_here"
  }
}

General Troubleshooting​

Test Server Installation​

# Test global installation
mcp-adr-analysis-server --version

# Test with npx
npx mcp-adr-analysis-server --version

# Test configuration
mcp-adr-analysis-server --test

Validate Configuration​

# Test JSON syntax
cat config.json | jq .

# Test YAML syntax (for Aider)
yamllint .aider_config.yaml

Check Environment Variables​

# List all environment variables
env | grep -E "(PROJECT_PATH|OPENROUTER|FIRECRAWL)"

# Test specific variables
echo $PROJECT_PATH
echo $OPENROUTER_API_KEY

Debug Mode​

{
  "env": {
    "LOG_LEVEL": "DEBUG"
  }
}

🔒 Security Best Practices​

Environment Variables​

Never hardcode API keys in config files:

# Set in your shell profile
export OPENROUTER_API_KEY="your_key_here"
{
  "env": {
    "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}"
  }
}

Secure Configuration Template​

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/absolute/path/to/project",
        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
        "EXECUTION_MODE": "full",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "ERROR",
        "ENABLE_CONTENT_MASKING": "true",
        "MASKING_LEVEL": "strict",
        "AI_CACHE_ENABLED": "false"
      }
    }
  }
}

File Permissions​

# Secure config file permissions
chmod 600 ~/.config/Claude/claude_desktop_config.json
chmod 600 .cursor/mcp.json

🧪 Testing Configuration​

Validate Setup​

  1. Test Server Installation
mcp-adr-analysis-server --version
mcp-adr-analysis-server --test
  1. Test MCP Connection
{
  "tool": "check_ai_execution_status"
}
  1. Test Basic Functionality
{
  "tool": "analyze_project_ecosystem",
  "parameters": {
    "projectPath": ".",
    "recursiveDepth": "shallow"
  }
}

Diagnostic Commands​

// Check environment
{
  "tool": "analyze_environment",
  "parameters": {
    "includeOptimizations": true
  }
}

// Test AI execution
{
  "tool": "suggest_adrs",
  "parameters": {
    "projectPath": ".",
    "maxSuggestions": 1
  }
}

🔧 Troubleshooting​

Common Configuration Issues​

IssueSymptomSolution
Server not found"Unknown tool" errorsInstall server globally: npm install -g mcp-adr-analysis-server
Tools return promptsGet instructions instead of resultsSet EXECUTION_MODE=full and add API key
Permission deniedFile access errorsUse absolute paths, check permissions
Slow performanceLong response timesUse claude-3-haiku model, enable caching
High API costsExpensive requestsReduce AI_MAX_TOKENS, use cheaper model

Debug Configuration​

{
  "env": {
    "LOG_LEVEL": "DEBUG",
    "VERBOSE": "true",
    "TIMING_ENABLED": "true",
    "MEMORY_TRACKING": "true"
  }
}

Reset Configuration​

# Backup current config
cp claude_desktop_config.json claude_desktop_config.json.backup

# Start with minimal config
cat > claude_desktop_config.json << 'EOF'
{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/absolute/path/to/project",
        "EXECUTION_MODE": "prompt-only"
      }
    }
  }
}
EOF

📚 Related Documentation​

Configuration not working? → Troubleshooting Guide or File an Issue