# sparfenyuk/mcp-proxy architecture

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

- Interactive diagram: https://gitdiagram.com/sparfenyuk/mcp-proxy
- Repository: https://github.com/sparfenyuk/mcp-proxy

## Overview

##### Main Components
- mcp-proxy Application (the core component found in the src/mcp_proxy directory)
- Two Modes of Operation:
– “stdio to SSE” mode: Acts as an intermediary between a local stdio client (e.g., Claude Desktop) and a remote MCP server that only supports SSE.
– “SSE to stdio” mode: Exposes an SSE server that accepts remote connections and, in turn, spawns a local MCP stdio-server process.
- External Entities:
– For stdio to SSE: Claude Desktop (or similar clients) and an external MCP Server.
– For SSE to stdio: LLM Client (or other remote connections) and a local MCP Server process.
- Configuration and Environment:
– Command-line arguments, environment variable passing, and header configuration (all described in the README).
- Supporting Infrastructure:
– Docker (via Dockerfile and Docker Compose YAML).
– GitHub workflows and code quality/testing integrations (contained in .github and tests directories).

##### Relationships and Interactions
- In “stdio to SSE” mode:
- The client (e.g., Claude Desktop) sends/receives data over stdio.
- mcp-proxy translates this communication to SSE and forwards it to the External MCP Server.
- In “SSE to stdio” mode:
- A remote client (LLM client) connects via SSE to mcp-proxy.
- mcp-proxy spawns a local stdio server process (i.e., the MCP server) and translates SSE data to local stdio.
- Additionally, illustrate configuration flow where command-line arguments and environment variables configure the behavior of mcp-proxy.

##### Architectural Patterns and Design Principles
- Clear separation between client communication and local processing.
- Use of proxy pattern: mcp-proxy acts as an intermediary converting data protocols.
- Configuration-driven behavior (with modes defined by the presence of a URL versus a command).
- Extensibility via containerization: The Dockerfile allows extending the container image to include additional executables (like uv).
- Testing and continuous integration via GitHub workflows indicate a focus on automated quality control.

##### Relevant Technologies, Frameworks, and Libraries
- Python (source directory and py.typed hints at type checking).
- Docker and Docker Compose for deployment.
- GitHub Actions for CI/CD.
- UV (a tool referenced in installation and command usage).
- SSE (Server-Sent Events) as a communication protocol.

##### Elements
- Components:
- Client (Claude Desktop or LLM Client) with appropriate labels.
- mcp-proxy (central component) with dual modes.
- External MCP Server (for stdio to SSE) and Local MCP Server (for SSE to stdio).
- Optional: Docker/Container environments and configuration repositories (GitHub workflows, Docker Compose service).
- Annotations for configuration:
- Optionally, denote how command line arguments and environment variables influence the scaling or behavior of the proxies.

This approach will not only clarify the function of mcp-proxy in proxying between different protocols but also make the deployment and extension (via containerization and CI/CD) visible in the system design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Config["CLI & Env Config (using command-line & env vars)"]:::config
    mcpApp["mcp-proxy Application"]:::proxy
    ProxyCore["Proxy Server Core Logic"]:::proxy

    Config --> mcpApp
    mcpApp --> ProxyCore

    %% Mode 1: stdio to SSE
    subgraph "Mode 1: stdio to SSE"
        clientSTD["Claude Desktop (stdio client)"]:::client
        stdioSSE["stdio to SSE Mode"]:::proxy
        extServer["External MCP Server (SSE)"]:::server

        clientSTD -- "stdio"--> stdioSSE
        stdioSSE -- "stdio"--> clientSTD
        stdioSSE -- "SSE"--> extServer
    end

    %% Mode 2: SSE to stdio
    subgraph "Mode 2: SSE to stdio"
        llmClient["LLM Client (SSE client)"]:::client
        sseStdio["SSE to stdio Mode"]:::proxy
        localServer["Local MCP Server (stdio)"]:::server

        llmClient -- "SSE"--> sseStdio
        sseStdio -- "stdio"--> localServer
    end

    %% Connect core proxy logic to each mode's implementation
    ProxyCore --> stdioSSE
    ProxyCore --> sseStdio

    %% Supporting Infrastructure
    Deploy["Containerization & Deployment"]:::deploy
    CICD["CI/CD Infrastructure"]:::cicd
    Testing["Testing Suite"]:::test

    ProxyCore --> Deploy
    Deploy --> CICD
    CICD --> Testing

    %% Click Events
    click Config "https://github.com/sparfenyuk/mcp-proxy/blob/main/src/mcp_proxy/__main__.py"
    click mcpApp "https://github.com/sparfenyuk/mcp-proxy/tree/main/src/mcp_proxy"
    click stdioSSE "https://github.com/sparfenyuk/mcp-proxy/blob/main/src/mcp_proxy/sse_client.py"
    click sseStdio "https://github.com/sparfenyuk/mcp-proxy/blob/main/src/mcp_proxy/sse_server.py"
    click ProxyCore "https://github.com/sparfenyuk/mcp-proxy/blob/main/src/mcp_proxy/proxy_server.py"
    click Deploy "https://github.com/sparfenyuk/mcp-proxy/tree/main/Dockerfile"
    click CICD "https://github.com/sparfenyuk/mcp-proxy/blob/main/.github"
    click Testing "https://github.com/sparfenyuk/mcp-proxy/tree/main/tests"

    %% Styles
    classDef config fill:#a2d5c6,stroke:#333,stroke-width:2px;
    classDef proxy fill:#ffebcd,stroke:#333,stroke-width:2px;
    classDef client fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef server fill:#f08080,stroke:#333,stroke-width:2px;
    classDef deploy fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef cicd fill:#ffe4c4,stroke:#333,stroke-width:2px;
    classDef test fill:#e6e6fa,stroke:#333,stroke-width:2px;
```
