Skip to main content

​
Overview

MCPJam Inspector is a sophisticated multi-platform application that runs in three distinct modes: Web Application, Electron Desktop App, and Docker Container. This architecture guide explains how the system adapts to each deployment mode while maintaining a unified codebase.

Web App

Standalone web application with separate client and server

Desktop App

Electron application with embedded Hono server

Container

Dockerized deployment for cloud hosting

​
High-Level Architecture

The application consists of distinct layers that work together across all deployment modes:

​
Deployment Modes

​
Mode Detection Flow

The application automatically detects its runtime environment and configures itself accordingly:
When: NODE_ENV=development (no Electron)Characteristics:
  • Backend: Hono server on localhost:3000
  • Frontend: Vite dev server on localhost:8080
  • CORS enabled for cross-origin requests
  • Hot module replacement (HMR)
  • API-only server (no static file serving)
Key Files:
  • server/app.ts:135-142 - Development mode routing
  • client/vite.config.ts - Vite configuration
When: NODE_ENV=production (no Electron)Characteristics:
  • Backend: Hono server on 0.0.0.0:3001
  • Frontend: Served from dist/client
  • SPA fallback to index.html
  • Optimized production bundles
  • No CORS (same-origin)
Key Files:
  • server/app.ts:119-126 - Production static serving
  • server/index.ts - Standalone server entry point
When: ELECTRON_APP=true and IS_PACKAGED=falseCharacteristics:
  • Embedded Hono server on localhost:3000
  • Frontend: Vite dev server redirects
  • Resources from app.getAppPath()
  • DevTools enabled
  • Auto-reload on changes
Key Files:
  • src/main.ts:62-92 - Server startup
  • src/main.ts:112 - Vite dev server URL loading
When: ELECTRON_APP=true and IS_PACKAGED=trueCharacteristics:
  • Embedded Hono server on 127.0.0.1:3000
  • Frontend: Bundled in resources/client
  • Resources from process.resourcesPath
  • Code signing enabled
  • Single .app/.exe bundle
Key Files:
  • src/main.ts:68-73 - Environment setup
  • server/app.ts:119-124 - Packaged static serving

​
Server Architecture

​
Hono Application Factory

The server uses a factory pattern to create the Hono app, allowing it to be reused across different contexts: Key Implementation: server/app.ts:20-146 The factory function createHonoApp() is called from:
  • server/index.ts - Standalone web server
  • src/main.ts:75 - Electron embedded server

​
Request Lifecycle

Every HTTP request flows through multiple layers:

​
API Routes Structure

  • MCP Routes
  • File Locations
/api/mcp
├── /servers
│   ├── GET / - List all servers
│   ├── POST /:id/connect - Connect to server
│   ├── POST /:id/disconnect - Disconnect from server
│   ├── /tools
│   │   ├── GET / - List tools
│   │   └── POST /:name/call - Call tool
│   ├── /resources
│   │   ├── GET / - List resources
│   │   └── GET /:uri - Read resource
│   └── /prompts
│       ├── GET / - List prompts
│       └── POST /:name/get - Get prompt
├── /health - Health check
└── /rpc-logs - SSE logs stream

​
Electron Integration

​
Process Architecture

Electron uses a multi-process architecture for security and stability:
Security Note: The renderer process has no direct access to Node.js APIs. All privileged operations must go through the preload script and IPC.

​
Startup Sequence

Here’s what happens when you launch the Electron app:

Environment Setup

src/main.ts:66-73 sets critical environment variables that tell the server it’s running in Electron

Server Start

src/main.ts:62-92 starts the embedded Hono server on an available port

Window Creation

src/main.ts:94-133 creates the main BrowserWindow with security settings

IPC Setup

src/ipc/listeners-register.ts registers all IPC event handlers

​
OAuth Deep Linking

The Electron app handles OAuth callbacks through a custom protocol handler:

OAuth Architecture

Learn about the complete OAuth flow including deep linking, state management, and security
 Quick Overview: Key Files:
  • src/main.ts:31-33 - Protocol registration
  • src/main.ts:273-313 - Deep link handler
  • client/src/hooks/useElectronOAuth.ts - React OAuth hook

​
MCP Client Management

​
MCPClientManager Architecture

The MCPClientManager is the heart of MCP server integration:

STDIO Transport

Spawns child processes for local MCP servers

SSE Transport

EventSource connections for remote servers

HTTP Transport

Fetch-based requests with streaming support

​
Client Lifecycle

For detailed MCP client implementation, see MCP Client Manager Architecture

​
State Management

​
Frontend State Architecture

The application uses a hybrid state management approach:
Purpose: Manage server-side data with caching and auto-refetchUsed for:
  • MCP server lists
  • Tool/resource/prompt data
  • Eval results
  • Real-time data synchronization
Key features:
  • Automatic background refetching
  • Optimistic updates
  • Request deduplication
  • Stale-while-revalidate
Purpose: Manage client-side UI stateUsed for:
  • User preferences (theme, layout)
  • UI state (modals, sidebars)
  • Form state
  • Temporary local data
Key features:
  • Simple API
  • No boilerplate
  • TypeScript support
  • Middleware (persist, devtools)
Purpose: Provide scoped state to component treesUsed for:
  • Authentication (WorkOS AuthKit)
  • Theme provider
  • Feature flags
Key features:
  • React-native
  • Component composition
  • Clean separation of concerns

​
Real-time Communication

​
SSE Event Bus

Real-time RPC logging uses Server-Sent Events for live updates: Flow:
  1. MCPClientManager calls a tool
  2. RPC logger callback fires
  3. Publishes to rpcLogBus
  4. Bus emits to all SSE connections
  5. Frontend EventSource receives event
  6. React components update UI
Key Files:
  • server/services/rpc-log-bus.ts - Event bus implementation
  • server/app.ts:67-79 - RPC logger setup
  • client/src/hooks/useRPCLogs.ts - Frontend subscription

​
Environment Configuration

The application adapts to its environment through a series of configuration steps:

​
Required Environment Variables

VariablePurposeSet ByRequired
CONVEX_HTTP_URLConvex backend URLUser/CI✅ Yes
ELECTRON_APPIndicates Electron runtimeMain processAuto
IS_PACKAGEDIndicates packaged appMain processAuto
ELECTRON_RESOURCES_PATHResources directoryMain processAuto
NODE_ENVRuntime environmentBuild/UserAuto
PORTServer portUserOptional (default: 3001)
DEBUG_MCP_SELECTIONEnable debug logsUserOptional

​
Build & Deployment

​
Build Process Flow

  • Web Deployment
  • Electron Deployment
  • Docker Deployment
Production Build:
npm run build
npm start
Artifacts:
  • dist/client/ - Frontend static files
  • dist/server/ - Backend Node.js files
Server: Hono serves both API and static files

​
Performance Considerations

​
Caching Strategy

Key Optimizations:
  • Query cache reduces API calls by 80%+
  • Stale-while-revalidate provides instant UI updates
  • Background refetching keeps data fresh
  • Mutation invalidation ensures consistency

​
Connection Pooling

The MCPClientManager maintains a pool of connections to avoid repeated handshakes:

​
Security Architecture

The application handles sensitive data including API keys, OAuth tokens, and MCP server access. Security is a top priority.

​
Security Layers

Context Isolation: Renderer has no direct Node.js accessSecure Preload: src/preload.ts exposes only safe APIsNo Remote Module: Disabled for securityProtocol Registration: Custom mcpjam:// protocol for OAuth
WorkOS AuthKit: Enterprise-grade OAuth 2.0Token Storage: Secure localStorage with expirationPKCE Flow: Proof Key for Code Exchange in ElectronConvex Integration: Server-side token validation
Zod Schemas: Runtime type validationSanitization: All user inputs cleanedRate Limiting: Prevent abuseError Handling: No sensitive data in error messages

​
Monitoring & Observability

​
Telemetry Pipeline

Error Tracking:
  • Sentry integration in both main and renderer processes
  • Automatic error reporting in production
  • Source maps for stack traces
  • User context and breadcrumbs
Performance Monitoring:
  • React Query DevTools for cache inspection
  • Browser DevTools for profiling
  • Network tab for API timing
  • Electron process manager for memory

​
Next Steps

MCP Client Manager

Deep dive into MCP protocol implementation

OAuth Architecture

Learn about authentication and OAuth flow

Playground Architecture

Understand the LLM playground system

Evals Architecture

Explore the evaluation framework
Now you understand the complete system architecture! Ready to contribute? Check out the Contributing Guide.
⌘I