# 🔌 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**
```bash
# 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**
```bash
# 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**
```bash
# 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
```json
{
"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
```json
{
"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
```json
{
"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
```json
{
"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
```json
{
"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
```yaml
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
```json
{
"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**
```bash
# Verify the server is installed and working
mcp-adr-analysis-server --version
mcp-adr-analysis-server --test
```
### **Step 2: Test Client Connection**
```bash
# 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"**
```bash
# 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**
```json
{
"env": {
"PROJECT_PATH": "/absolute/path/not/relative"
}
}
```
### **"Tools return prompts instead of results"**
```json
{
"env": {
"EXECUTION_MODE": "full",
"OPENROUTER_API_KEY": "required_for_ai_features"
}
}
```
### **"Command not found: npx"**
```bash
# Install Node.js and npm
# Then verify installation
node --version
npm --version
```
### **Environment variables not working**
```bash
# 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**
```json
{
"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**
```json
{
"env": {
"AI_CACHE_ENABLED": "true",
"AI_CACHE_TTL": "3600",
"MAX_FILES_PER_ANALYSIS": "500",
"LOG_LEVEL": "WARN"
}
}
```
### **Security Configuration**
```json
{
"env": {
"ENABLE_CONTENT_MASKING": "true",
"MASKING_LEVEL": "strict",
"FIRECRAWL_ENABLED": "true",
"FIRECRAWL_API_KEY": "your_firecrawl_key"
}
}
```
---
## 📚 Further Reading
- **[Complete MCP Client Configuration](../reference/mcp-client-config.md)** - Detailed configuration reference
- **[Environment Configuration](../reference/environment-config.md)** - Environment variables guide
- **[Installation Guide](./installation-guide.md)** - Complete installation instructions
- **[Troubleshooting Guide](./troubleshooting.md)** - Common issues and solutions
---
**Need help with a specific client?** → **[Join the Discussion](https://github.com/tosin2013/mcp-adr-analysis-server/issues)**
**Having compatibility issues?** → **[Check Troubleshooting](./troubleshooting.md#mcp-client-compatibility)**