Skip to main content

Configuration

Learn how to configure MCP Gatekeeper to suit your needs.

Environment Variables​

MCP Gatekeeper uses environment variables for configuration. Create .env files in the appropriate directories.

Backend Configuration​

Located at apps/backend/.env:

# Database Configuration
DATABASE_URL=sqlite:///./mcp_gatekeeper.db

# Server Configuration
HOST=127.0.0.1  # Bind to localhost only (security)
PORT=8000       # Backend API port

# Authentication
AUTH_TOKEN=your-secret-token-here
AUTH_TOKEN_HEADER_NAME=X-MCPGK-Token

# CORS Origins (comma-separated)
CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173

# Log Level
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL

Database Configuration​

  • SQLite (default): sqlite:///./gatekeeper.db
  • PostgreSQL: postgresql://user:password@localhost/gatekeeper
  • MySQL: mysql://user:password@localhost/gatekeeper

Security Settings​

The backend binds to 127.0.0.1 (localhost) by default for security. This prevents external network access.

Frontend Configuration​

Located at apps/frontend/.env:

# Backend API URL
VITE_API_URL=http://127.0.0.1:8000

# Optional: Custom API timeout (milliseconds)
VITE_API_TIMEOUT=30000

Application Settings​

Port Configuration​

Changing Backend Port​

Edit apps/backend/.env:

PORT=8080  # Change to your desired port

Update CORS origins to match:

CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173

Changing Frontend Port​

Edit apps/frontend/vite.config.ts:

export default defineConfig({
  server: {
    port: 3000,  // Change to your desired port
    host: true,
  },
  // ... rest of config
});

Update backend CORS to match:

CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

Log Level Configuration​

Control backend logging verbosity:

LOG_LEVEL=DEBUG  # Most verbose
LOG_LEVEL=INFO   # Standard (recommended)
LOG_LEVEL=WARNING
LOG_LEVEL=ERROR
LOG_LEVEL=CRITICAL  # Least verbose

Agent Configuration Files​

MCP Gatekeeper can read and write to agent configuration files:

Claude Desktop​

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

Windsurf​

  • macOS: ~/Library/Application Support/Windsurf/config.json
  • Windows: %APPDATA%\Windsurf\config.json

These paths are automatically detected by the agent configuration scanner.

Turborepo Configuration​

Root turbo.json configures the build pipeline:

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "build/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Package Manager Configuration​

npm Registry​

By default, packages are installed from the public npm registry. You can configure a custom registry:

Edit apps/backend/app/services/package_manager.py or set environment variable:

NPM_REGISTRY=https://registry.npmjs.org/

STDIO Package Installation Directory​

STDIO server packages are installed in ~/.mcp-gatekeeper/packages by default.

To change this, update the package manager service configuration.

Development vs Production​

Development Mode​

npm run dev

Features:

  • Hot reload enabled
  • Verbose logging
  • Source maps
  • Development tools enabled

Production Build​

npm run build

This creates optimized production builds:

  • Frontend: apps/frontend/dist/
  • Backend: Python bytecode compilation

Running Production Build​

# Build first
npm run build

# Serve frontend production build
npm run frontend:serve

# Run backend (use a process manager like PM2 or systemd)
cd apps/backend
python -m app.main

Advanced Configuration​

Custom MCP Server Wrapper​

The STDIO wrapper template is located at:

  • apps/backend/app/templates/wrapper_template.js

Customize this to modify metrics collection behavior.

WebSocket Configuration​

WebSocket endpoint: ws://127.0.0.1:8000/api/ws/metrics

Configure reconnection settings in apps/frontend/src/services/api.ts.

Configuration Files Reference​

mcp-gatekeeper/
├── .env                          # Root environment (optional)
├── apps/backend/.env             # Backend configuration
├── apps/frontend/.env            # Frontend configuration
├── turbo.json                    # Turborepo pipeline config
├── package.json                  # Root package.json
└── apps/
    ├── backend/
    │   ├── app/core/config.py   # Backend config loader
    │   └── requirements.txt     # Python dependencies
    └── frontend/
        ├── vite.config.ts       # Vite configuration
        └── package.json         # Frontend dependencies

Next Steps​