Architecture

System design and structure of the MCP Lens application.

Overview

MCP Lens is a full-stack application with a Python/FastAPI backend and React/Vite frontend. The backend provides a REST API for managing MCP server connections, fetching tool definitions, and running multi-layer evaluations. The frontend delivers an interactive UI for browsing tools, viewing reports, and configuring servers.

Directory Structure

        src/

          app/

            eval/            # Evaluation engine

              protocol.py    # Layer 1: MCP spec compliance

              quality.py     # Layer 2: Tool quality & overlap detection

              security.py    # Layer 3: Security analysis

              llm_eval.py    # Layer 4: LLM-assisted evaluation

              scoring.py     # Scoring & gate logic

              runner.py      # Orchestrates all layers

              model_adapter.py # LLM provider adapters

              llm_config.py  # Multi-LLM config loader (llm.json)

              regression.py  # Report comparison

            routes/

              servers.py     # CRUD endpoints for server configs

              tools.py       # Tool fetch, evaluation, false positives

              auth_routes.py # OAuth/DCR flows, token management

            database.py      # SQLAlchemy async models

            mcp_client.py    # MCP protocol client (JSON-RPC 2.0)

            auth.py          # OAuth token management, DCR

            config.py        # Configuration loader

          frontend/          # React + Vite + Tailwind UI

            src/

              components/

                ServerList.tsx      # Server cards

                ServerForm.tsx      # Add/edit server modal

                ToolsViewer.tsx     # Tool list + evaluation tabs

                EvaluationView.tsx  # Evaluation report

                ComparisonView.tsx  # Report comparison

                DownloadModal.tsx   # Export options

                LlmEvalModal.tsx   # LLM eval config

                AboutPage.tsx      # Evaluation rules reference

              api.ts              # API client

              types.ts            # TypeScript interfaces

        tests/

          eval/               # Evaluation engine tests (531+)

        llm.json.example      # Multi-LLM config template

Backend

FastAPI with async/await for all request handling
SQLAlchemy async for database access (SQLite default, PostgreSQL optional)
MCP client using JSON-RPC 2.0 over streamable HTTP
Evaluation engine with 4 pluggable layers (protocol, quality, security, LLM)
LLM adapters: Anthropic, OpenAI, Vertex AI (Gemini), Anthropic on Vertex

Frontend

React 18 with Vite build tool
Tailwind CSS for styling
State-based routing (no react-router)
API client for all backend communication
PDF/JSON export via jspdf

Architecture Diagram

Data Flow

Add Server

User adds MCP server via UI → stored in SQLite

Fetch Tools

User clicks "Fetch Tools" → backend connects via MCP client → tools cached in DB

Run Evaluation

4 layers execute sequentially → scored report saved to database

LLM Evaluation (optional)

Runs in parallel across selected models → merged into report

View & Export

Results displayed in UI → exportable as JSON/YAML/PDF

Security

Auth tokens encrypted at rest with Fernet (AES-128-CBC)
LLM evaluation is read-only — tools are never executed
API key authentication optional via X-API-Key header