# modelcontextprotocol/inspector architecture

> Architecture diagram of the GitHub repository modelcontextprotocol/inspector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/modelcontextprotocol/inspector
- Repository: https://github.com/modelcontextprotocol/inspector

## Overview

##### Project Type and Purpose
- This project is a developer tool designed for testing and debugging MCP (Model Context Protocol) servers. It consists of two major parts: an MCP Inspector Client UI (a frontend) and an MCP Proxy Server (a backend). The tool can be used via npx to launch the inspector alongside an MCP server, and it supports features such as bearer token authentication, SSE connections, and configuration settings.

##### File Structure
- Notice the clear separation between the client and server code:
- The “client” directory contains code for the web-based UI:
▫ The “src” folder holds React components (e.g., App.tsx) and utility modules.
▫ Configuration files for build tools like Vite, Tailwind CSS, TypeScript configs, etc.
▫ Testing configurations and mocks reside in subdirectories.
- The “server” directory contains the backend code written in TypeScript:
▫ “index.ts” and “mcpProxy.ts” represent the entry points and core proxy server functionality.
- There are additional directories (e.g., “bin”) that include CLI scripts to launch parts of the application.

##### Key Components
a. MCP Inspector Client (Frontend):
- This component is a web-based UI built with modern JavaScript/TypeScript (likely React as seen in App.tsx and various component files).
- It handles user interactions like entering bearer tokens, configuring settings, and displaying server responses (via SSE, for example).

b. MCP Proxy Server (Backend):
- Implemented in Node.js with TypeScript (located under the “server” directory).
- Functions as a mediator between the inspector client and the actual MCP server.
- Responsible for launching and proxying requests/responses to the MCP server, including the management of environment variables and command-line arguments.

c. External MCP Server:
- Although not part of this repository, the MCP Inspector communicates with a provided MCP server (user-specified when using “npx ...”). This is an external process that is inspected and debugged.

d. CLI Interface:
- Both “bin/cli.js” in the top-level and “client/bin/cli.js” indicate that there’s a command-line tool which facilitates launching the inspector. This CLI layer coordinates starting both the Proxy server and the Client UI.

##### Relationships and Data Flows
▸ The client sends requests (e.g., SSE for live updates, configuration settings, authentication details) to the proxy server.
▸ The proxy server relays requests to the external MCP server, capturing its responses.
▸ The server then forwards responses back to the client.
▸ The CLI may act as the orchestrator, launching both server and client components.

##### Architectural Patterns and Design Principles
- The separation of concerns is evident: a clear distinction between frontend (UI), backend (proxy logic), and the target MCP server.
- The design fits a typical full-stack application setup; however, the backend here doesn’t represent a full business logic layer but a proxy to channel communications between the frontend and external server.
- Marking authentication (bearer token) flows and how environment variables and runtime parameters are passed through the CLI to both the proxy and the MCP server.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Interface Subgraph
    subgraph "CLI Interface"
        CLI1["bin/cli.js"]:::cli
        CLI2["client/bin/cli.js"]:::cli
    end

    %% MCP Inspector Client (UI) Subgraph
    subgraph "MCP Inspector Client (UI)"
        ClientApp["App.tsx"]:::client
        ClientSrc["client/src (Components & Utils)"]:::client
    end

    %% MCP Proxy Server Subgraph
    subgraph "MCP Proxy Server"
        ProxyIndex["index.ts"]:::server
        ProxyMCP["mcpProxy.ts"]:::server
    end

    %% External MCP Server
    External["MCP Server (External)"]:::external

    %% Relationships
    CLI1 -->|"CLI_args&EnvVars"| ClientApp
    CLI1 -->|"CLI_args&EnvVars"| ProxyIndex
    CLI2 -->|"CLI_args&EnvVars"| ClientApp
    CLI2 -->|"CLI_args&EnvVars"| ProxyIndex

    ClientApp -->|"SSE/AuthToken"| ProxyMCP
    ClientSrc -->|"SSE/AuthToken"| ProxyMCP

    ProxyMCP -->|"Proxy_Request"| External
    External -->|"Proxy_Response"| ProxyMCP
    ProxyMCP -->|"Data_Update"| ClientApp
    ProxyMCP -->|"Data_Update"| ClientSrc

    %% Click Events for CLI Interface
    click CLI1 "https://github.com/modelcontextprotocol/inspector/blob/main/bin/cli.js"
    click CLI2 "https://github.com/modelcontextprotocol/inspector/blob/main/client/bin/cli.js"

    %% Click Events for MCP Inspector Client (UI)
    click ClientApp "https://github.com/modelcontextprotocol/inspector/blob/main/client/src/App.tsx"
    click ClientSrc "https://github.com/modelcontextprotocol/inspector/tree/main/client/src"

    %% Click Events for MCP Proxy Server
    click ProxyIndex "https://github.com/modelcontextprotocol/inspector/blob/main/server/src/index.ts"
    click ProxyMCP "https://github.com/modelcontextprotocol/inspector/blob/main/server/src/mcpProxy.ts"

    %% Styles
    classDef cli fill:#E8F5E9,stroke:#1B5E20,stroke-width:2px;
    classDef client fill:#E0F7FA,stroke:#006064,stroke-width:2px;
    classDef server fill:#FFF3E0,stroke:#E65100,stroke-width:2px;
    classDef external fill:#F3E5F5,stroke:#4A148C,stroke-width:2px;
```
