DOCSEARCHbyAlgolia
Submit Docs

MCPProxy

repository·main·Indexed 43 days ago

https://github.com/smart-mcp-proxy/mcpproxy-go

A security-focused proxy for Model Context Protocol (MCP) servers that federates multiple servers into a single endpoint. It provides advanced security features including automatic quarantine, pluggable scanners, and Docker isolation to bypass tool limits in AI tools like Cursor and OpenAI.

Tokens
349.6K
Snippets
822
Records
1.7K
Agent score
57%

What's inside MCPProxy

  1. What is MCPProxy?

    main

    MCPProxy is a Go-based intelligent proxy that sits between AI clients (such as Cursor, Claude Desktop, or VS Code Copilot) and MCP servers. It is designed to optimize the interaction between AI agents and tools by providing intelligent discovery, security features, and isolation.

    Core Capabilities:

    • Intelligent Tool Discovery: Uses BM25 search indexing to provide only relevant tools to the AI client, preventing context bloat and reducing token usage.
    • Security Quarantine: Protects against Tool Poisoning Attacks (TPA) by requiring manual approval for new MCP servers.
    • Docker Isolation: Runs upstream MCP servers within Docker containers for enhanced security, supporting automatic runtime detection (Python/Node.js) and environment variable management.
    • Audit & Transparency: Provides full logging of tool calls and automatic detection of sensitive data (API keys, PII, credentials) for compliance monitoring.

  2. Overview of the MCPProxy Windows Tray Application

    main

    The MCPProxy Windows Tray Application is a native Windows system tray application built using C# and WPF. It is designed to provide a platform-native experience for managing the mcpproxy server lifecycle.

    Note: This specific native implementation is currently a placeholder. The existing tray application is located at cmd/mcpproxy-tray/ and is built with Go and systray.

  3. Overview of OAuth E2E Testing Infrastructure

    main

    The mcpproxy project includes a comprehensive OAuth E2E (End-to-End) testing infrastructure designed to validate OAuth 2.1 flows, error handling, and observability. This infrastructure consists of a local test server, Go integration tests, and browser-based Playwright tests.

    Key components include:

    • Local OAuth Test Server: A Go package in tests/oauthserver/ that simulates a complete OAuth 2.1 provider.
    • Go Integration Tests: Validates OAuth detection, grant types, resource indicators (RFC 8707), and token refresh.
    • E2E Scripts: Orchestration via scripts/run-oauth-e2e.sh and browser-based Playwright tests in e2e/playwright/.
    • Observability: Enhanced CLI output for auth status, auth login, and OAuth health checks via the doctor command.

  4. Overview of Security Scanner Commands

    main

    The mcpproxy security command group manages the Security Scanner Plugin System. It handles three main areas:

    1. Scanner lifecycle: Listing, enabling, disabling, and configuring Docker-based scanner plugins.
    2. Scan operations: Running scanners against quarantined upstream servers, tracking progress, and viewing reports.
    3. Approval workflow: Approving a server (unquarantining it and indexing its tools) or rejecting it and cleaning up artifacts.

    All subcommands support global flags: --config / -c, --data-dir / -d, --output / -o, --json, --log-level, --log-to-file, and --log-dir.

  5. Overview of the Security Scanner Plugin System

    main

    The Security Scanner Plugin System (Spec 039) provides a pluggable architecture for running Docker-based security scanners against quarantined MCP servers before they are approved for use.

    Key capabilities include:

    • Scanner Registry Management: Manage bundled scanners or register custom ones via JSON.
    • Parallel Execution: Orchestrates multiple scanners in parallel with timeout handling.
    • SARIF Normalization: Converts various scanner outputs into a normalized SARIF 2.1.0 format for consistent reporting and risk scoring.
    • Approval Workflow: Supports an approve/reject/rescan lifecycle for servers.
    • Integrity Verification: Uses integrity baselines to ensure runtime security.

  6. Overview of the Activity Log Backend

    main

    The Activity Log Backend is a system within MCPProxy designed to record and audit all tool calls, policy decisions, and quarantine events. It provides a way to monitor proxy activity through REST API endpoints for historical querying and Server-Sent Events (SSE) for real-time updates in the UI.

    Key features include:

    • Historical Querying: REST API with filtering and pagination.
    • Real-time Monitoring: SSE events for live UI updates.
    • Compliance Support: Export capabilities for activity history.
    • Automatic Management: Configurable retention policies (default 90 days or 100,000 records) with automatic pruning.

  7. Overview of Discovery-profiler datasets

    main

    The Discovery-profiler datasets (Spec 083) consist of versioned, immutable fixtures used for benchmarking the discovery-effectiveness profiler (bench/). These datasets are frozen once committed; any updates require creating a new version (e.g., *_v3.*) rather than editing existing files (e.g., *_v2.*).

    Key components include:

    • corpus_v2.tools.json: A frozen corpus of 45 tools from 7 reference servers, including full JSON input schemas.
    • result_fixtures_v1.json: Deterministic tool-call outputs used for the TOON-results arm.
    • fetch_fixture.html: A frozen HTML document used to provide deterministic input for the fetch:fetch tool.
    • livemcptool_snapshot/: A planned corpus for token/scale measurement.

    Note: ToolRet is not committed and is fetched at runtime into bench/results/cache/ via scripts/fetch-toolret.sh.

  8. Overview of the Native macOS Swift Tray App

    main

    The Native macOS Swift Tray App is a specialized interface for MCPProxy designed for macOS 13+ (Ventura) users. It provides a lightweight presence in the macOS Menu Bar (using MenuBarExtra) to monitor and control MCPProxy without a full application window.

    Key features include:

    • Core Process Management: Managing the MCPProxy lifecycle.
    • System Notifications: Receiving security and status alerts.
    • Auto-Updates: Managed via Sparkle using the appcast at https://mcpproxy.app/appcast.xml.
    • Tray Icon Badges: Visual indicators for service health.
    • Symlink Support: Attempts to create a symlink at /usr/local/bin/mcpproxy for CLI access (requires macOS authorization).
    • OAuth Integration: Triggers OAuth flows by calling the MCPProxy REST API, which opens the user's default web browser.

    Note: This app does not use a Dock icon (LSUIElement=true) and prefers its bundled binary located at Contents/Resources/bin/mcpproxy over external binaries on the system PATH.

  9. Overview of the Discovery Effectiveness Profiler (mcp-discovery-bench)

    main

    The Discovery Effectiveness Profiler is an extension of the existing bench/ harness designed to measure how effectively MCP servers provide tool discovery information. It provides three primary capabilities:

    1. Live Response Cost Measurement: Measures the token cost of retrieve_tools responses over real MCP protocols, including per-query costs, percentiles, component breakdowns, and break-even analysis.
    2. Deterministic Encoding Arms: Compares different tool encoding strategies (arms) against a schema-bearing frozen corpus. Supported arms include:
      • baseline: Full-JSON schema rendering with deterministic key order.
      • compact: A compact signature format: name(param:type, opt?:type)|description.
      • toon: Uses the toon-go implementation.
      • tscg: Invokes the @tscg/core subprocess via a Node.js shim.
      • tron: Optional TRON-style named-class deduplication.
    3. Public Corpus Loaders: Loads datasets for testing, including ToolRet (runtime-fetch for retrieval quality) and LiveMCPTool (committed snapshot for token/scale testing).

    This tool is intended for benchmarking and research, not for production proxy behavior.

  10. Summary of Management Service Refactoring Decisions

    main

    The management service is being refactored to improve testability, observability, and compatibility. Key architectural decisions include:

    • OpenAPI Generation: Uses swaggo/swag for Chi-compatible, annotation-based OpenAPI 3.x documentation.
    • Service Interface: Implements a Go interface + struct pattern to support testability and dependency injection.
    • Diagnostics: Centralizes health and status reporting through a single Doctor() method.
    • CLI Compatibility: Ensures no breaking changes by preserving all existing flags and commands.
    • Event System: Leverages the existing event bus to support SSE (Server-Sent Events) integration and decoupling.
    • Bulk Operations: Implements operations sequentially with support for partial failure to ensure safety and transparency.
    • Logging: Enhances visibility by including HTTP metadata, OAuth details, and Docker stderr.

  11. Understand the Spec 065 Evaluation Datasets structure

    main

    Spec 065 provides versioned, frozen evaluation artifacts for tool-retrieval (D1) and security (D2) benchmarks.

    Crucial Rule: Artifacts are immutable once committed. To refresh a dataset, you must create a new version (e.g., *_v2.*) rather than editing an existing *_v1.* file.

    File Types Cheat Sheet

    FilePurposeServable via serve --config?
    snapshot-servers.config.jsonA real mcpproxy config containing 7 no-auth reference servers used to freeze the corpus.Yes
    corpus_v1.tools.jsonA frozen snapshot of 45 tools (the D1 universe).No (Dataset)
    retrieval_golden_v1.json47 graded queries used for retrieval scoring.No (Dataset)
    baseline_v1.jsonReference metrics (Recall@k, MRR, etc.) used as a CI regression anchor.No (Dataset)
    security_corpus_v1.jsonLabeled security regression corpus for D2 detection scoring.No (Dataset)
    detect_corpus_v1.jsonLabeled corpus for the offline detect.Engine gate.No (Dataset)

  12. Understand the Tray Auto-Update Failure UX and Telemetry implementation

    main

    This implementation plan describes how MCPProxy handles auto-update failures on macOS. It replaces the default Sparkle 'Update Error!' alert with a custom recovery dialog offering options to Try Again, Download from Website, or Cancel.

    Failures are tracked via telemetry using four specific diagnostic codes: MCPX_UPDATE_APPCAST_FAILED, MCPX_UPDATE_DOWNLOAD_FAILED, MCPX_UPDATE_INSTALL_FAILED, and MCPX_UPDATE_OTHER_FAILED. These are reported from the macOS tray app to the Go core via a dedicated REST endpoint and persisted in a BBolt database with a 24-hour decay window.