MCPProxy

Implements full-text search indexing using Bleve (Go's BM25 search library) to enable sub-second discovery of tools across all connected upstream MCP servers. Instead of loading all tool schemas into agent context (causing token bloat), MCPProxy maintains an inverted index of tool names, descriptions, and metadata, allowing agents to query 'retrieve_tools' with search terms and receive only relevant results. The system achieves ~99% token reduction while maintaining 43% accuracy improvement over naive schema loading by ranking tools by relevance rather than returning all available tools.

Acts as a transparent gateway between AI agents and multiple upstream MCP servers, routing MCP protocol messages (initialize, call_tool, list_resources, etc.) to appropriate upstream servers based on tool ownership. Uses mark3labs/mcp-go library for protocol handling and implements routing logic in internal/server/mcp_routing.go that maintains connection state, handles message serialization/deserialization, and manages request/response correlation across multiple upstream connections. Supports three routing modes: retrieve_tools (search-based discovery), direct (pass-through to specific server), and code_execution (sandboxed tool invocation).

Provides native system tray application (internal/ui/systray/) for quick access to MCPProxy on desktop platforms. Tray app shows proxy status (running/stopped), allows starting/stopping the proxy, and provides quick links to web UI and logs. Implements platform-specific integrations using systray library for native look-and-feel. Supports auto-start on system boot and background operation without terminal window.

Implements optional per-server Docker containerization (internal/config/config.go lines 94-95) that sandboxes tool execution in isolated containers with configurable resource limits (CPU, memory, disk, network). Each tool execution runs in a fresh container with minimal filesystem access, preventing tools from accessing host system or other containers. Supports container image specification per server, allowing different tools to run in different environments (Python 3.9, Node.js 16, etc.). Includes automatic container cleanup and resource monitoring.

Supports two deployment editions optimized for different use cases: Personal edition (single-user desktop application with system tray and web UI) and Server edition (multi-user deployment with OAuth2 authentication, session management, and audit logging). Both editions share core MCP proxy logic but differ in authentication, UI, and operational features. Server edition includes multi-user session management (internal/data/session.go) and per-user activity logging for compliance.

Implements event-driven architecture (internal/runtime/events/) using publish-subscribe pattern for decoupled communication between components. Events are emitted for state changes (server connected/disconnected, tool added/removed, quarantine status changed) and can be subscribed to by multiple handlers (logging, UI updates, external webhooks). Event system supports filtering by event type and source, enabling selective subscription. Supports both in-process pub/sub and optional external event bus integration (Kafka, RabbitMQ).

Exposes diagnostic endpoints (/health, /metrics, /diagnostics) providing system health status, token usage metrics, and detailed diagnostics information. Health checks verify connectivity to upstream servers, database availability, and Docker daemon status. Token metrics track LLM token usage across tool calls, enabling cost analysis and optimization. Diagnostics endpoint provides detailed system information (Go version, memory usage, goroutine count) useful for troubleshooting.

Implements a security-first approach where newly connected upstream MCP servers are automatically quarantined until manually approved by an administrator. The quarantine system (internal/server/mcp.go line 46) prevents Tool Poisoning Attacks (TPAs) by preventing tool execution from untrusted servers while still allowing inspection and testing. Works in conjunction with sensitive data detection to identify tools that request credentials, API keys, or other sensitive information, flagging them for review. Uses Docker isolation (optional per-server containerization with resource limits) to sandbox tool execution from quarantined servers.

Supports both HTTP/2 and stdio-based transports for connecting to upstream MCP servers, implemented in the transport layer (internal/server/transport.go). HTTP transport uses persistent connections with connection pooling for efficient multi-server communication, while stdio transport spawns subprocess instances for each server connection. The transport abstraction layer (internal/contracts/types.go) allows seamless switching between transports without affecting routing logic. Handles transport-level concerns like connection lifecycle management, graceful shutdown, and error recovery.

Manages lifecycle of connections to upstream MCP servers with automatic state reconciliation (internal/runtime/supervisor/supervisor.go). Implements actor-pool pattern for concurrent connection handling, monitoring server health, detecting disconnections, and automatically reconnecting with exponential backoff. Maintains server registry (internal/data/registry.go) tracking all connected servers, their capabilities, and tool inventories. State reconciliation ensures that tool index remains consistent with upstream server state even when servers are added/removed dynamically or experience transient failures.

Implements tool execution engine (internal/server/mcp.go) that supports tool variants — multiple implementations of the same logical tool with different execution strategies (e.g., 'read_file' via local filesystem vs. S3 vs. HTTP). Routes tool calls based on intent metadata embedded in tool schemas, allowing agents to request specific variants without knowing implementation details. Handles parameter validation, type coercion, and error handling for tool execution. Supports code_execution routing mode for sandboxed Python/JavaScript execution with resource limits.

Implements configuration system (internal/config/config.go, internal/config/loader.go) supporting YAML/JSON configuration files with environment variable substitution and secret management. Secrets (API keys, credentials) are stored separately from configuration and injected at runtime using a secrets provider interface. Configuration loading supports multiple sources (files, environment variables, command-line flags) with precedence rules. Validates configuration schema at load time and provides detailed error messages for misconfigurations.

Implements comprehensive activity logging system (internal/config/config.go lines 121-125) that records all tool calls, results, and errors with full audit trails. Includes sensitive data detection that identifies and masks credentials, API keys, PII, and other sensitive information in logs before storage. Supports multiple log backends (file, syslog, structured JSON) and log levels (debug, info, warn, error). Integrates with session management to correlate logs with user/agent sessions.

Exposes HTTP API (internal/httpapi/server.go) providing REST endpoints for managing MCPProxy configuration, querying tool inventory, executing tools, and monitoring system health. Implements standard HTTP conventions (GET for queries, POST for mutations, DELETE for removal) with JSON request/response bodies. Includes authentication middleware supporting API key authentication and optional OAuth2 for multi-user deployments. API endpoints are versioned (/api/v1/) to support backward compatibility.

Provides web-based user interface (internal/ui/web/) for interactive tool discovery, execution, and MCPProxy management. Frontend is built with modern JavaScript framework (React/Vue) and communicates with HTTP API server. Includes tool search interface with real-time filtering, tool execution form builder that generates input fields based on tool schemas, and server management dashboard showing connection status and health metrics. Supports dark mode and responsive design for mobile access.