Configuration

Environment variables, authentication modes, server settings, and LLM provider setup.

Environment Variables

Copy .env.example to .env:

BACKEND_PORT=5002
FRONTEND_PORT=5173
# MCP_LENS_API_KEY=your-secret-api-key
# DATABASE_URL=sqlite+aiosqlite:///mcp_secrets.db
# PERSIST_OAUTH_TOKENS=true

Authentication Modes

Mode Description Config
None No authentication auth: false
Bearer token Static JWT/token auth_mode: bearer_token
API key Static key auth_mode: api_key
OAuth OAuth 2.0 authorization code auth_mode: oauth
DCR Dynamic Client Registration + OAuth auth_mode: dcr

Bearer tokens and API keys are encrypted at rest (Fernet/AES-128-CBC). Set MCP_LENS_ENCRYPTION_KEY in .env.

Server Config Fields

Field Type Default Description
url string required MCP server endpoint URL
transport string streamable_http Transport protocol
auth bool false Whether auth is required
auth_mode string null Auth type
ssl_verify bool true Verify SSL certificates
timeout int 30 Connection timeout (seconds)
description string "" Human-readable description
oauth object null OAuth config
api_key_config object null API key config

Rules Configuration

MCP Lens includes 33 evaluation rules across 5 layers (protocol, quality, security, LLM, agent). All rules can be customized from the Rules tab in the web UI or via the REST API.

UI Controls

Control Description
Toggle Enable or disable individual rules. Disabled rules are skipped during evaluation.
Severity Override a rule's severity level (critical, high, medium, low, info). Affects scoring weight.
Parameters Expand a rule to adjust its parameters (e.g., overlap threshold, min description length).
Export / Import Export customizations as JSON. Import to restore settings or share across environments.
Reset Clear all overrides and restore code-defined defaults.

Storage

Rule overrides are stored in the SQLite database. Only overrides are persisted — rules left at their defaults use the code-defined values. New rules added in code are auto-seeded on startup.

Export Format

{
  "version": 1,
  "exported_at": "2026-09-19T10:00:00Z",
  "rules": [
    {
      "rule_id": "quality.desc_actionable",
      "enabled": true,
      "severity": "high",
      "params": null
    }
  ]
}

LLM Configuration

Create llm.json (copy llm.json.example):

{
  "default": "gemini-flash",
  "configs": {
    "gemini-flash": {
      "provider": "vertexai",
      "model": "gemini-2.5-flash",
      "credentials_env": "GOOGLE_APPLICATION_CREDENTIALS"
    },
    "claude": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "api_key_env": "ANTHROPIC_API_KEY"
    }
  }
}

Environment Variable Convention

Fields ending in _env reference environment variable names, not literal values. For example, "api_key_env": "ANTHROPIC_API_KEY" means MCP Lens reads the actual key from the ANTHROPIC_API_KEY environment variable at runtime.

Vertex AI

For Vertex AI providers (vertexai, anthropic-vertex), project and location are optional. If omitted, they are inferred from the service account credentials or application default credentials.

Supported Providers

openai anthropic vertexai anthropic-vertex