langprotect-mcp-gateway 1.3.5
Security gateway for Model Context Protocol (MCP) to protect AI tool interactions
License: MIT
Requires Python: >=3.8
Keywords: mcp, security, ai-security, langprotect, model-context-protocol

# LangProtect MCP Gateway

🛡️ **Security gateway for Model Context Protocol (MCP)** - Protect your AI tool interactions from security threats.

[![PyPI version](https://badge.fury.io/py/langprotect-mcp-gateway.svg)](https://pypi.org/project/langprotect-mcp-gateway/)

## 🆕 What's New in v1.3.0

### Layer 2: Output Scanning 🔍
- **Automatic secret masking** in AI-generated responses
- **30+ secret types detected**: AWS, Google Cloud, Azure, Stripe, GitHub, JWTs, DB credentials, private keys
- **Non-blocking warnings** - never interrupts workflow
- **Preserves structure** - masks secrets while keeping code/content readable

### Enhanced Security Controls 🔐
- **Fail-closed mode** - Block requests on scan failures (optional)
- **Configurable timeouts** - Control scan performance
- **High-entropy detection** - Catch unknown secret formats

### Example

**Before** (v1.2.6):
```bash
AI: Here's your AWS deployment script:
export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG..."
```

**After** (v1.3.0):
```bash
AI: Here's your AWS deployment script:
export AWS_ACCESS_KEY_ID="<REDACTED:AWS_ACCESS_KEY:1a5d44a2>"
export AWS_SECRET_ACCESS_KEY="<REDACTED:AWS_SECRET_KEY:73ec276f>"
```
✅ **Secrets masked** | 🔒 **Code structure preserved** | 📝 **Audit trail maintained**

---

## Features

✅ **Two-Layer Protection**
- **Layer 1 (Input)**: Blocks dangerous requests before sending to MCP server
- **Layer 2 (Output)**: Masks secrets in AI responses

✅ **Automatic Threat Detection** - Scans all MCP requests for security risks  
✅ **Access Control** - Whitelist/blacklist MCP servers and tools  
✅ **Full Audit Trail** - Logs all AI interactions for compliance  
✅ **IDE Support** - Works with VS Code, Cursor, and all MCP-compatible IDEs  
✅ **Easy Setup** - 30-second installation
✅ **Fail-Open Design** - Won't block your workflow if backend is unavailable

## Quick Start

### 1. Installation

The gateway runs as a global CLI tool. We recommend using `pipx` to manage the installation.

```bash
# Recommended: Install via pipx
pipx install langprotect-mcp-gateway
```

### 2. Automatic Setup (Recommended) 🚀

Run our automated setup command to configure VS Code, Cursor, or Claude Desktop for all workspaces:

```bash
langprotect-gateway-setup
```

**What happens:**
- 🔐 **Prompts for credentials** interactively (password hidden)
- ✅ **Validates credentials** in real-time against your backend
- 🔄 **Retries on failure** with helpful error messages
- 📝 **Creates wrapper script** at `~/.local/bin/langprotect-mcp-wrapper.sh`
- ⚙️ **Configures VS Code** for global visibility in ALL workspaces
- 🚀 **Auto-start enabled** for seamless protection

**Example:**
```bash
$ langprotect-gateway-setup

🚀 Setting up LangProtect MCP Gateway...

═══════════════════════════════════════════════════════════════
         🔐 Enter Your LangProtect Credentials
═══════════════════════════════════════════════════════════════

Backend URL [http://localhost:8000]: http://localhost:8000
Email: your.email@company.com
Password: ●●●●●●●●●●

      Validating credentials...
      ✓ Credentials validated successfully!

📝 Creating global wrapper script...
   ✅ Created: ~/.local/bin/langprotect-mcp-wrapper.sh

⚙️  Configuring VS Code...
   ✅ Updated: ~/.config/Code/User/settings.json

✅ Setup complete!
```

**Alternative: Pre-set credentials via environment variables**
```bash
export LANGPROTECT_URL="http://localhost:8000"
export LANGPROTECT_EMAIL="your.email@company.com"
export LANGPROTECT_PASSWORD="your-password"
langprotect-gateway-setup
```

### 3. Reload VS Code

Press `Ctrl+Shift+P` → `Developer: Reload Window`

**That's it!** ✅ LangProtect will now protect all your workspaces.

---

## ⚙️ Configuration Options (v1.3.0+)

Configure security behavior with environment variables in your wrapper script:

```bash
# Security Controls
export LANGPROTECT_ENABLE_MASKING=true      # Enable output masking (default: true)
export LANGPROTECT_FAIL_CLOSED=false        # Block on scan errors (default: false = fail-open)
export LANGPROTECT_SCAN_TIMEOUT=5.0         # Scan timeout in seconds (default: 5.0)
export LANGPROTECT_ENTROPY_DETECTION=true   # Detect unknown secrets via entropy (default: true)

# Backend Connection
export LANGPROTECT_URL="http://localhost:8000"
export LANGPROTECT_EMAIL="your.email@company.com"
export LANGPROTECT_PASSWORD="your-password"
```

### Security Modes

**Fail-Open (Default)** - Recommended for development:
```bash
export LANGPROTECT_FAIL_CLOSED=false
```
- If scan times out or fails → **Allow request** (log warning)
- Won't block your workflow
- Best for development environments

**Fail-Closed** - Recommended for production:
```bash
export LANGPROTECT_FAIL_CLOSED=true
```
- If scan times out or fails → **Block request**
- Maximum security
- Best for production/sensitive environments

### Output Masking

Control how AI-generated secrets are handled:

```bash
# Enable masking (default)
export LANGPROTECT_ENABLE_MASKING=true

# Disable masking (see secrets in plain text - not recommended)
export LANGPROTECT_ENABLE_MASKING=false
```

**Masked format**: `<REDACTED:SECRET_TYPE:hash>`
- Example: `<REDACTED:AWS_ACCESS_KEY:1a5d44a2>`
- Hash allows deduplication across logs
- Preserves code structure

---

## 🏗️ Manual Setup (Per-Workspace)

If you prefer to enable LangProtect only for a specific project, you can use a local `.vscode/mcp.json` file.

1. Create a wrapper script (e.g., `langprotect-wrapper.sh`):

```bash
#!/bin/bash
export LANGPROTECT_URL="http://localhost:8000"  # Your LangProtect backend
export LANGPROTECT_EMAIL="your.email@company.com"
export LANGPROTECT_PASSWORD="your-password"
export MCP_SERVER_COMMAND="npx"
export MCP_SERVER_ARGS="-y,@modelcontextprotocol/server-filesystem,/path/to/allowed/dir"

exec langprotect-gateway "$@"
```

2. Make it executable: `chmod +x langprotect-wrapper.sh`

3. Create `.vscode/mcp.json`:

```json
{
  "servers": {
    "langprotect-filesystem": {
      "type": "stdio",
      "command": "/path/to/langprotect-wrapper.sh",
      "args": []
    }
  }
}
```

4. Reload VS Code: `Ctrl+Shift+P` → "Developer: Reload Window"

5. Start the server: `Ctrl+Shift+P` → "MCP: List Servers" → Click "Start"

### Cursor Setup

```json
{
  "mcpServers": {
    "langprotect-gateway": {
      "command": "langprotect-gateway",
      "args": ["--mcp-json-path", "~/.cursor/mcp.json"],
      "env": {
        "LANGPROTECT_URL": "http://localhost:8000",
        "LANGPROTECT_EMAIL": "your.email@company.com",
        "LANGPROTECT_PASSWORD": "your-password"
      },
      "servers": {
        "filesystem": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
        }
      }
    }
  }
}
```

### Claude Desktop Setup

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "langprotect-gateway": {
      "command": "langprotect-gateway",
      "args": ["--mcp-json-path", "~/Library/Application Support/Claude/claude_desktop_config.json"],
      "env": {
        "LANGPROTECT_URL": "http://localhost:8000",
        "LANGPROTECT_EMAIL": "your.email@company.com",
        "LANGPROTECT_PASSWORD": "your-password"
      },
      "servers": {
        "filesystem": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
        }
      }
    }
  }
}
```

## How It Works

```
┌─────────────┐     ┌────────────────────┐     ┌──────────────────┐
│   VS Code   │────▶│ LangProtect Gateway│────▶│  Filesystem MCP  │
│  (Copilot)  │     │   (Security Scan)  │     │    Server        │
└─────────────┘     └────────────────────┘     └──────────────────┘
                              │
                              ▼
                    ┌────────────────────┐
                    │ LangProtect Backend│
                    │  (Policy Check)    │
                    └────────────────────┘
```

1. **Intercepts** all MCP tool calls from your AI assistant
2. **Sends** each request to LangProtect backend for security scanning
3. **Blocks** requests that violate your security policies
4. **Forwards** allowed requests to the actual MCP server
5. **Logs** everything for audit trail
         ↓
LangProtect Gateway (this package)
         ↓
    [Security Scan]
         ↓
MCP Servers (filesystem, github, etc.)
```

Every request is:
1. Intercepted by the gateway
2. Scanned for security threats
3. Logged to LangProtect backend
4. Forwarded to actual MCP server (if safe)
5. Response returned to AI

## Dashboard

Monitor all activity at your LangProtect dashboard:
- View all AI interactions
- See security threats blocked
- Track IDE usage
- Generate compliance reports

## Security

The gateway protects against:
- 🚫 Sensitive file access (`.env`, SSH keys, etc.)
- 🚫 Dangerous commands (`rm -rf`, data exfiltration)
- 🚫 SQL injection patterns
- 🚫 Hardcoded credentials in suggestions
- 🚫 Prompt injection attacks

## Troubleshooting

**"externally-managed-environment" error on Linux:**
- Modern Linux systems protect system Python. Use `pipx` instead:
  ```bash
  sudo apt install pipx -y
  pipx install langprotect-mcp-gateway
  ```

**Authentication failed:**
- Check `LANGPROTECT_URL`, `LANGPROTECT_EMAIL`, `LANGPROTECT_PASSWORD` are correct
- Ensure LangProtect backend is accessible

**Gateway not starting:**
- Check Python version: `python3 --version` (need 3.8+)
- Check package installed: `pipx list | grep langprotect`
- Verify path: `which langprotect-gateway`

**Tools not working:**
- Check MCP servers are configured under `"servers"` section
- Restart IDE completely

**Command not found after install:**
- Run `pipx ensurepath` and restart your terminal
- Or add `~/.local/bin` to your PATH manually

## For Team Leads

### Quick Team Rollout:

1. **Share credentials** with each team member:
   ```
   Email: user@company.com
   Password: secure-password
   Server: http://langprotect.company.com:8000
   ```

2. **Team members install:**
   ```bash
   # Linux/macOS
   sudo apt install pipx -y  # or: brew install pipx
   pipx install langprotect-mcp-gateway
   
   # Configure mcp.json with credentials
   # Restart IDE
   ```

3. **Monitor dashboard:** See all team activity in real-time

## Updates

```bash
# Upgrade with pipx
pipx upgrade langprotect-mcp-gateway

# Or reinstall specific version
pipx install langprotect-mcp-gateway==1.1.0 --force
```

## Support

- **Documentation:** https://www.langprotect.com/docs
- **Issues:** https://github.com/langprotect/mcp-gateway/issues
- **Security:** security@langprotect.com

## License

MIT License - see LICENSE file for details

## Links

- **Homepage:** https://www.langprotect.com/
- **GitHub:** https://github.com/langprotect/mcp-gateway
- **Documentation:** https://www.langprotect.com/docs