How geelen/mcp-remote works
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.