🔌 How-To: MCP Client Compatibility

Goal: Configure the MCP ADR Analysis Server to work seamlessly with any MCP-compatible AI assistant or IDE.

When to use this guide: When you want to set up the MCP ADR Analysis Server with your preferred AI assistant (Claude Desktop, Cline, Cursor, Gemini, etc.) or IDE.

---

🎯 Quick Compatibility Matrix

AI Assistant/IDE	MCP Support	Config File	Command	Status
Claude Desktop	✅ Native	claude_desktop_config.json	mcp-adr-analysis-server	Recommended
Cline	✅ Extension	cline_mcp_settings.json	npx mcp-adr-analysis-server	Full Support
Cursor	✅ Native	.cursor/mcp.json	npx mcp-adr-analysis-server	Full Support
Gemini	✅ Native	gemini_mcp_config.json	mcp-adr-analysis-server	Full Support
Continue.dev	✅ Extension	.continue/config.json	npx mcp-adr-analysis-server	Full Support
Aider	✅ Native	.aider_config.yaml	mcp-adr-analysis-server	Full Support
Windsurf	✅ Native	mcp_config.json	mcp-adr-analysis-server	Full Support
VS Code	✅ Via Extensions	Various	npx mcp-adr-analysis-server	Full Support

---

🚀 Universal Setup Steps

Step 1: Install the Server

# Option 1: Global installation (recommended)
npm install -g mcp-adr-analysis-server

# Option 2: Local installation (for development)
npm install mcp-adr-analysis-server

Step 2: Verify Installation

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

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

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

Step 3: Configure Environment Variables

# Set required environment variables
export PROJECT_PATH="/absolute/path/to/your/project"
export OPENROUTER_API_KEY="your_openrouter_api_key_here"
export EXECUTION_MODE="full"

# Optional: Enable Firecrawl for web research (recommended)
export FIRECRAWL_ENABLED="true"
export FIRECRAWL_API_KEY="fc-your-api-key-here"

Step 4: Choose Your Client Configuration

Select the configuration that matches your preferred AI assistant or IDE:

---

🖥️ Claude Desktop (Recommended)

Best for: General use, best AI integration, most stable

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": "fc-your-api-key-here"
      }
    }
  }
}

Advantages

• ✅ Native MCP support
• ✅ Best AI integration
• ✅ Stable and reliable
• ✅ Easy configuration

---

🔧 Cline (VS Code Extension)

Best for: VS Code development, team collaboration

Configuration Location

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

Basic Configuration

{
  "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}"
      }
    }
  }
}

Advantages

• ✅ VS Code integration
• ✅ Workspace-aware
• ✅ Team-friendly
• ✅ Environment variable support

---

🎯 Cursor

Best for: AI-powered coding, modern development workflow

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"
      }
    }
  }
}

Advantages

• ✅ AI-native IDE
• ✅ Built-in MCP support
• ✅ Modern interface
• ✅ Fast performance

---

🤖 Gemini (Google AI)

Best for: Google AI ecosystem, multimodal capabilities

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-1.5"
      }
    }
  }
}

Advantages

• ✅ Google AI integration
• ✅ Multimodal capabilities
• ✅ Large context windows
• ✅ Advanced reasoning

---

🔄 Continue.dev (VS Code Extension)

Best for: VS Code users, open-source alternative

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"
      }
    }
  ]
}

Advantages

• ✅ Open-source
• ✅ VS Code integration
• ✅ Extensible
• ✅ Community-driven

---

🛠️ Aider (Command Line)

Best for: Command-line users, automation, CI/CD

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"

Advantages

• ✅ Command-line interface
• ✅ Automation-friendly
• ✅ CI/CD integration
• ✅ Lightweight

---

🌊 Windsurf

Best for: Professional development, enterprise features

Configuration Location

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

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"
      }
    }
  }
}

Advantages

• ✅ Professional features
• ✅ Enterprise support
• ✅ Advanced AI capabilities
• ✅ Performance optimized

---

🧪 Testing Your Configuration

Step 1: Test Server Installation

# Verify the server is installed and working
mcp-adr-analysis-server --version
mcp-adr-analysis-server --test

Step 2: Test Client Connection

# Test with your specific client
# For Claude Desktop: Restart Claude Desktop
# For VS Code: Reload window
# For Cursor: Restart Cursor

Step 3: Verify Tools Availability

In your AI assistant, try:

"List the available MCP tools for ADR analysis"

Expected response should include tools like:

• analyze_project_ecosystem
• generate_adrs_from_prd
• analyze_content_security
• And 34+ other tools

---

🚨 Common Issues & Solutions

"Server not found" or "Unknown tool"

# Solution 1: Verify installation
which mcp-adr-analysis-server
npm list -g mcp-adr-analysis-server

# Solution 2: Check PATH
echo $PATH | grep -E "(node|npm)"

# Solution 3: Restart your AI client

"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"
  }
}

"Command not found: npx"

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

Environment variables not working

# Check if variables are set
echo $PROJECT_PATH
echo $OPENROUTER_API_KEY

# Set them in your shell profile
export PROJECT_PATH="/absolute/path/to/project"
export OPENROUTER_API_KEY="your_key_here"

---

🔧 Advanced Configuration

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"
      }
    },
    "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"
      }
    }
  }
}

Performance Optimization

{
  "env": {
    "AI_CACHE_ENABLED": "true",
    "AI_CACHE_TTL": "3600",
    "MAX_FILES_PER_ANALYSIS": "500",
    "LOG_LEVEL": "WARN"
  }
}

Security Configuration

{
  "env": {
    "ENABLE_CONTENT_MASKING": "true",
    "MASKING_LEVEL": "strict",
    "FIRECRAWL_ENABLED": "true",
    "FIRECRAWL_API_KEY": "your_firecrawl_key"
  }
}

---

📚 Further Reading

• Complete MCP Client Configuration - Detailed configuration reference
• Environment Configuration - Environment variables guide
• Installation Guide - Complete installation instructions
• Troubleshooting Guide - Common issues and solutions

---

Need help with a specific client? → Join the Discussion

Having compatibility issues? → Check Troubleshooting