# geelen/mcp-remote architecture

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

- Interactive diagram: https://gitdiagram.com/geelen/mcp-remote
- Repository: https://github.com/geelen/mcp-remote

## Overview

##### Project type and purpose
- This is a Node-based command-line proxy tool (`mcp-remote`) that bridges a local MCP client (stdio-only) to a remote MCP server over HTTP/SSE, handling OAuth authorization under the hood.
- It’s not a full-stack web app but a CLI agent performing network proxying, authentication, and message shuffling.

##### File structure
- Top-level “src” with two entry points:
- client.ts – parses CLI args, starts the tool
- proxy.ts – houses the core proxy logic (spawns HTTP server, coordinates streams)
- “src/lib” modules:
- coordination.ts – orchestrates HTTP vs SSE transport selection and message routing
- mcp-auth-config.ts – reads/writes local auth config (`~/.mcp-auth`)
- node-oauth-client-provider.ts – implements the OAuth flows (dynamic/static)
- utils.ts, types.ts – shared helpers and type definitions
- Configuration / build: tsconfig.json, package.json, lockfile.

##### README for additional insights
- Describes OAuth redirect listener (default port 3334), headers injection, debug logs, fallback transport strategies (http-first, sse-first, etc.).
- Mentions local state directory (`~/.mcp-auth`), dynamic vs static OAuth metadata.

1. MCP-Client (stdio-only desktop app)
2. mcp-remote CLI Process
– CLI parser (client.ts)
– Proxy engine (proxy.ts + coordination)
– OAuth Client Provider (node-oauth-client-provider)
– Local HTTP server (OAuth callback listener)
– Local state store (`~/.mcp-auth`)
3. Remote MCP Server (HTTP/SSE endpoint)
4. Remote OAuth Authorization Server (token endpoint, auth page)
- MCP-Client ⇄ mcp-remote via stdio streams
- mcp-remote → Remote MCP Server (HTTP/SSE requests carrying OAuth access tokens) → responses back
- mcp-remote ↔ OAuth Server:
- Browser redirect flow (opens URL in user’s browser)
- Local HTTP callback receives authorization code
- Token exchange back to OAuth server → stores tokens in `~/.mcp-auth`
- mcp-remote reads/writes to local FS for credential caching
c. Architectural patterns & principles
- Proxy pattern: the CLI sits in the middle, proxying messages between client and server
- Strategy pattern: transport strategy module tries HTTP vs SSE according to flags
- Configuration abstraction: supports dynamic vs static OAuth metadata injection
- Resilience: fallback logic, random open port selection, debug logging
d. Key technologies & libraries
- Node.js, TypeScript
- Standard `http` module for local server and HTTP transport
- EventSource or SSE polyfill for SSE transport
- OAuth client logic (RFC-compliant dynamic registration + manual config)

##### Detail guidance
- Don’t collapse the coordination module — show “Transport Strategy” as a distinct internal component.
- OAuth-related code under an “Auth” sub-component.
- Fallback logic: if HTTP transport 404 → switch to SSE, etc.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Processes
    MCPClient["MCP-Client\n(stdio-only)"]:::process
    subgraph "mcp-remote CLI Process"
        direction TB
        CLIParser["CLI Parser\n(client.ts)"]:::process
        ProxyEngine["Proxy Engine\n(proxy.ts)"]:::process
        subgraph "Transport Strategy"
            direction TB
            Coordination["Coordination Module\n(coordination.ts)"]:::process
        end
        subgraph "Auth"
            direction TB
            OAuthProvider["OAuth Client Provider\n(node-oauth-client-provider.ts)"]:::process
            CallbackListener["Local HTTP Listener\n(port 3334)"]:::process
            TokenStore["Token Store\n(~/.mcp-auth)"]:::storage
        end
    end
    RemoteMCP["Remote MCP Server\n(HTTP/SSE)"]:::external
    OAuthServer["OAuth Authorization Server\n(auth & token endpoints)"]:::external
    Browser["User Browser"]:::external

    %% Utilities (optional)
    Utils["Shared Utils\n(utils.ts)"]:::process
    Types["Type Definitions\n(types.ts)"]:::process

    %% Data Flows
    MCPClient -->|"stdio in"| CLIParser
    CLIParser -->|"startup args"| ProxyEngine
    ProxyEngine -->|"invoke"| Coordination
    Coordination -->|"HTTP/SSE requests\nwith OAuth token"| RemoteMCP
    RemoteMCP -->|"responses"| Coordination
    Coordination -->|"to stdio"| ProxyEngine
    ProxyEngine -->|"stdio out"| MCPClient

    %% OAuth Flow (control)
    ProxyEngine -.->|"trigger auth"| OAuthProvider
    OAuthProvider -->|"opens URL"| Browser
    Browser -->|"redirect to callback"| CallbackListener
    CallbackListener -->|"auth code"| OAuthProvider
    OAuthProvider -->|"token exchange"| OAuthServer
    OAuthServer -->|"access/refresh tokens"| OAuthProvider
    OAuthProvider -->|"store tokens"| TokenStore
    TokenStore -->|"read/write"| ProxyEngine

    %% Styles and Clicks
    classDef process fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef external fill:#d4edda,stroke:#333,stroke-width:1px
    classDef storage fill:#fff3cd,stroke:#333,stroke-width:1px

    click CLIParser "https://github.com/geelen/mcp-remote/blob/main/src/client.ts"
    click ProxyEngine "https://github.com/geelen/mcp-remote/blob/main/src/proxy.ts"
    click Coordination "https://github.com/geelen/mcp-remote/blob/main/src/lib/coordination.ts"
    click OAuthProvider "https://github.com/geelen/mcp-remote/blob/main/src/lib/node-oauth-client-provider.ts"
    click TokenStore "https://github.com/geelen/mcp-remote/blob/main/src/lib/mcp-auth-config.ts"
    click Utils "https://github.com/geelen/mcp-remote/blob/main/src/lib/utils.ts"
    click Types "https://github.com/geelen/mcp-remote/blob/main/src/lib/types.ts"
```
