[Feature Request]: MCP Reverse Proxy - Bridge Local Servers to Remote Gateways

[crivetimihai]

🧭 Epic — MCP Reverse Proxy for Local-to-Remote Server Bridging

Field	Value
Title	Reverse Proxy Bridge for Exposing Local MCP Servers to Remote Gateways
Goal	Enable local MCP servers to be accessible through remote gateways without requiring inbound network access, similar to SSH reverse tunneling or ngrok
Why now	Organizations need to share MCP servers across firewalls/NATs without exposing local infrastructure. Developers want to test local servers with cloud-hosted gateways. Edge deployments need centralized management.
Depends on	Existing mcpgateway.wrapper and mcpgateway.translate modules, WebSocket/SSE transports, authentication framework

---

🧭 Type of Feature

• New feature or capability
• Enhancement to existing functionality
• New MCP-compliant server
• New component or integration
• Developer tooling or test improvement
• Packaging, automation and deployment
• Other

---

🙋‍♂️ User Story 1: Establish Reverse Proxy Connection

As a: Developer with a local MCP server
I want: To connect my local server to a remote gateway without opening firewall ports
So that: I can share my server capabilities with remote teams and clients securely

✅ Acceptance Criteria

Scenario: Connect local server to remote gateway
  Given I have a local MCP server running via stdio
  And I have credentials for a remote gateway
  When I run "python -m mcpgateway.reverse_proxy --local-stdio 'uvx mcp-server-git' --gateway https://gateway.example.com --token TOKEN"
  Then a persistent connection is established to the remote gateway
  And the local server appears as available in the remote gateway's catalog
  And the connection automatically reconnects on network failures

Scenario: Authentication and authorization
  Given I attempt to connect to a remote gateway
  When I provide invalid credentials
  Then the connection is rejected with 401 Unauthorized
  And clear error message explains the authentication failure

Scenario: Connection resilience
  Given an established reverse proxy connection
  When the network connection drops temporarily
  Then the client automatically attempts reconnection with exponential backoff
  And queued requests are preserved during reconnection
  And connection resumes without manual intervention

---

🙋‍♂️ User Story 2: Bidirectional Message Flow

As a: Remote gateway
I want: To invoke tools on the proxied local server and receive responses
So that: The local server appears as a first-class citizen in my server catalog

✅ Acceptance Criteria

Scenario: Tool invocation from remote to local
  Given a reverse proxy connection is established
  And the local server has registered tools
  When a remote client invokes a tool via the gateway
  Then the request is forwarded to the local server
  And the response is returned to the remote client
  And latency metrics are tracked for monitoring

Scenario: Resource and prompt handling
  Given a local server with resources and prompts
  When the gateway requests resource listing or prompt templates
  Then the local server responds with the appropriate data
  And large resources are streamed efficiently
  And caching headers are properly handled

Scenario: Error propagation
  Given a tool invocation that fails on the local server
  When the error response is generated
  Then the error is properly formatted and forwarded to the gateway
  And the connection remains stable
  And error metrics are recorded

---

🙋‍♂️ User Story 3: Management and Monitoring

As a: System Administrator
I want: To monitor and manage reverse proxy connections
So that: I can ensure reliable service and troubleshoot issues

✅ Acceptance Criteria

Scenario: Connection status visibility
  Given multiple reverse proxy connections
  When I access the gateway admin UI
  Then I see all active reverse proxy connections
  And each shows connection duration, data transferred, and last activity
  And I can filter by connection state and client identifier

Scenario: Connection management
  Given an active reverse proxy connection
  When I click "Disconnect" in the admin UI
  Then the connection is gracefully terminated
  And the client receives a disconnect notification
  And resources are properly cleaned up

Scenario: Metrics and logging
  Given active reverse proxy connections
  When I view metrics dashboards
  Then I see connection count, bandwidth usage, and error rates
  And detailed logs show connection lifecycle events
  And performance metrics help identify bottlenecks

---

🙋‍♂️ User Story 4: Configuration and Deployment

As a: DevOps Engineer
I want: To configure reverse proxy connections via environment variables and config files
So that: I can automate deployments and manage fleets of edge servers

✅ Acceptance Criteria

Scenario: Configuration file support
  Given a YAML configuration file with connection details
  When I run "python -m mcpgateway.reverse_proxy --config reverse-proxy.yaml"
  Then connections are established based on the configuration
  And multiple local servers can be proxied simultaneously
  And configuration hot-reload is supported

Scenario: Docker deployment
  Given a Docker container with local MCP servers
  When I set REVERSE_PROXY_GATEWAY and REVERSE_PROXY_TOKEN env vars
  Then the container automatically establishes reverse proxy on startup
  And health checks verify connection status
  And container logs show connection details

Scenario: Kubernetes deployment
  Given a Kubernetes deployment with reverse proxy configured
  When pods are scaled up or down
  Then each pod maintains its own reverse proxy connection
  And connections are labeled with pod metadata
  And service discovery works correctly

---

📐 Design Sketch

sequenceDiagram
    participant Local as Local MCP Server
    participant Proxy as Reverse Proxy Client
    participant Gateway as Remote Gateway
    participant Remote as Remote Client

    Note over Proxy,Gateway: Initial Connection
    Proxy->>Gateway: WebSocket/SSE Connect + Auth
    Gateway-->>Proxy: Connection Accepted
    Proxy->>Gateway: Register Local Server Metadata
    Gateway-->>Proxy: Registration Confirmed

    Note over Local,Remote: Tool Invocation Flow
    Remote->>Gateway: Tool Request
    Gateway->>Proxy: Forward Request (via WebSocket/SSE)
    Proxy->>Local: Execute via stdio
    Local-->>Proxy: Tool Response
    Proxy-->>Gateway: Forward Response
    Gateway-->>Remote: Tool Result

    Note over Proxy,Gateway: Keep-Alive & Reconnection
    loop Every 30s
        Proxy->>Gateway: Ping/Heartbeat
        Gateway-->>Proxy: Pong
    end

    Note over Proxy,Gateway: Connection Loss
    Gateway-xProxy: Network Failure
    loop Exponential Backoff
        Proxy->>Gateway: Reconnection Attempt
    end
    Proxy->>Gateway: Connection Restored
    Gateway-->>Proxy: State Synchronized

Loading

flowchart TD
    subgraph Local Environment
        LS[Local MCP Server<br/>stdio] 
        RP[Reverse Proxy Client]
        LS <-->|stdio| RP
    end

    subgraph Remote Gateway
        WS[WebSocket/SSE<br/>Endpoint]
        VS[Virtual Server<br/>Registry]
        API[Gateway API]
        WS --> VS
        VS --> API
    end

    subgraph Remote Clients
        RC1[MCP Client 1]
        RC2[MCP Client 2]
        RC1 --> API
        RC2 --> API
    end

    RP <-->|WebSocket/SSE<br/>+ Auth| WS
    
    style LS fill:#e1f5fe
    style RP fill:#fff3e0
    style WS fill:#f3e5f5
    style VS fill:#e8f5e9

Loading

---

🔧 Implementation Tasks

1. Core Reverse Proxy Module

   • Create mcpgateway/reverse_proxy.py main module
   • Implement WebSocket client for persistent connection to gateway
   • Add SSE fallback for environments without WebSocket support
   • Handle bidirectional message routing between stdio and network
   • Implement automatic reconnection with exponential backoff
   • Add connection state management and health monitoring

2. Authentication & Security

   • Support bearer token authentication
   • Implement mutual TLS option for enhanced security
   • Add connection encryption and message signing
   • Support API key rotation without disconnect
   • Implement rate limiting and abuse prevention

3. Gateway-Side Integration

   • Add reverse proxy connection handler endpoint
   • Extend virtual server registry for reverse-proxied servers
   • Implement connection pooling and management
   • Add reverse proxy connection to admin UI
   • Create metrics collection for proxied connections

4. Message Protocol

   • Define control message format (register, heartbeat, disconnect)
   • Implement request/response correlation for concurrent calls
   • Add streaming support for large resources
   • Handle binary data encoding for file transfers
   • Implement compression for bandwidth optimization

5. CLI Interface

   • --local-stdio flag for stdio server command
   • --gateway flag for remote gateway URL
   • --token flag for authentication
   • --config flag for configuration file
   • --reconnect-delay flag for retry configuration
   • --verbose flag for debug logging

6. Configuration Management

   • YAML/JSON configuration file support
   • Environment variable configuration
   • Support multiple simultaneous connections
   • Connection profiles for different environments
   • Hot-reload configuration changes

7. Monitoring & Observability

   • Connection status metrics (connected, reconnecting, failed)
   • Bandwidth and message count metrics
   • Latency tracking for request/response
   • Error rate and error type tracking
   • OpenTelemetry integration for distributed tracing

8. Testing

   • Unit tests for message routing logic
   • Integration tests with mock gateway
   • End-to-end tests with real stdio servers
   • Network failure simulation tests
   • Performance tests for throughput and latency
   • Security tests for authentication and encryption

9. Documentation

   • Architecture overview and design decisions
   • Quick start guide for developers
   • Configuration reference
   • Deployment guides (Docker, Kubernetes)
   • Troubleshooting guide
   • Security best practices

10. Container Support

    • Dockerfile with reverse proxy support
    • Docker Compose example with local servers
    • Kubernetes manifests with ConfigMaps
    • Helm chart for production deployments
    • Init container for connection validation

---

🔄 Alternatives Considered

Option	Pros	Cons	Decision
SSH Tunnel	Standard, well-understood	Not HTTP-native, requires SSH access	❌
VPN Connection	Full network access	Complex setup, overly broad access	❌
ngrok/localtunnel	Proven solutions	Third-party dependency, not MCP-aware	❌
Custom WebSocket/SSE	MCP-native, full control	More implementation work	✅
gRPC Bidirectional Stream	Efficient, built-in streaming	Additional protocol complexity	❌

---

📓 Additional Context

Architecture Decisions:

• WebSocket preferred for lower latency and true bidirectional communication
• SSE fallback for restrictive network environments
• Stdio subprocess management reuses existing mcpgateway.wrapper patterns
• Connection state machine inspired by mcpgateway.translate module

Security Considerations:

• All connections require authentication (no anonymous reverse proxies)
• Optional client certificate validation for high-security environments
• Connection metadata includes source IP and client identifier for audit logs
• Rate limiting prevents resource exhaustion attacks

Performance Goals:

• <100ms additional latency for tool invocations
• Support 100+ simultaneous reverse proxy connections per gateway
• Automatic compression for payloads >1KB
• Connection memory footprint <10MB per proxied server

Future Enhancements:

• Multi-gateway failover (connect to backup gateways)
• Connection migration (move connection between gateways)
• Reverse proxy federation (chain multiple reverse proxies)
• Built-in tunnel through corporate proxies
• P2P mode for direct client-to-server connections

---

Success Metrics:

• 50% reduction in firewall change requests
• 90% of disconnections automatically recovered
• <2% message loss during network interruptions
• 80% of edge deployments using reverse proxy