749 reverse proxy

[crivetimihai]

Reverse Proxy Implementation PR

Closes #749

Overview

This PR implements a reverse proxy feature for MCP Gateway that enables local MCP servers to connect to remote gateways through outbound connections. This is particularly useful for servers behind firewalls or NATs that cannot accept inbound connections.

What Was Implemented

1. Core Reverse Proxy Module (mcpgateway/reverse_proxy.py)

• StdioProcess class: Manages local MCP server subprocesses via stdio

  • Starts/stops subprocess execution
  • Handles bidirectional message passing via stdin/stdout
  • Manages message handlers for stdout processing

• ReverseProxyClient class: Bridges local stdio servers to remote gateways

  • Establishes WebSocket connections to remote gateways (SSE planned but not yet implemented)
  • Handles automatic reconnection with exponential backoff
  • Maintains keepalive heartbeats
  • Forwards MCP messages bidirectionally between local server and gateway
  • Supports JWT authentication via Bearer tokens

• Connection Management:

  • Connection state tracking (disconnected, connecting, connected, reconnecting, shutting_down)
  • Message type enumeration for protocol control (register, unregister, heartbeat, error, request, response, notification)
  • Graceful shutdown handling with signal handlers (SIGINT, SIGTERM)

2. FastAPI Router (mcpgateway/routers/reverse_proxy.py)

• WebSocket endpoint (/reverse-proxy/ws): Accepts reverse proxy client connections

  • Handles session management
  • Processes registration/unregistration of proxied servers
  • Routes MCP messages between clients and proxied servers
  • Maintains heartbeat for connection health

• Session Management APIs:

  • GET /reverse-proxy/sessions: List all active reverse proxy sessions
  • DELETE /reverse-proxy/sessions/{session_id}: Disconnect a specific session
  • POST /reverse-proxy/sessions/{session_id}/request: Send MCP request to a proxied server

• SSE endpoint (/reverse-proxy/sse/{session_id}): Stream events from a session (foundation laid, full implementation pending)

3. Documentation Updates

• Added comprehensive reverse proxy documentation in docs/docs/using/reverse-proxy.md
• Included architecture overview, use cases, and deployment examples
• Security considerations and limitations documented

4. Configuration Example

• Created examples/reverse-proxy-config.yaml with sample configuration
• Shows how to configure local servers, gateway connection, and authentication

How to Test

Prerequisites

1. Ensure you have the development environment set up:

make venv
make install-dev

2. Generate a JWT token for authentication:

export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
    --username admin --exp 10080 --secret my-test-key)

Testing the Reverse Proxy Client

1. Start the MCP Gateway (acts as the remote gateway):

mcpgateway --host 0.0.0.0 --port 4444

2. Run the reverse proxy client with a local MCP server:

# Example with mcp-server-git
python3 -m mcpgateway.reverse_proxy \
    --local-stdio "uvx mcp-server-git" \
    --gateway http://localhost:4444 \
    --token $MCPGATEWAY_BEARER_TOKEN

3. Verify the connection by checking active sessions:

curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
    http://localhost:4444/reverse-proxy/sessions

Testing with Configuration File

1. Create a config file (or use the example):

gateway: http://localhost:4444
token: your-jwt-token-here
local_stdio: "uvx mcp-server-git"
reconnect_delay: 1
max_retries: 5
keepalive: 30
log_level: INFO

2. Run with config:

python3 -m mcpgateway.reverse_proxy \
    --config examples/reverse-proxy-config.yaml \
    --local-stdio "uvx mcp-server-git"

Testing WebSocket Connection

1. Connect via WebSocket using a tool like websocat:

websocat -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
    ws://localhost:4444/reverse-proxy/ws

2. Send registration message:

{
  "type": "register",
  "sessionId": "test-session",
  "server": {
    "name": "test-server",
    "description": "Test MCP Server",
    "protocol": "stdio"
  }
}

3. Verify registration succeeded by checking the response and session list.

Testing MCP Operations

1. Send an MCP request through the reverse proxy:

curl -X POST http://localhost:4444/reverse-proxy/sessions/{session_id}/request \
    -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tools/list",
      "params": {}
    }'

2. Monitor the reverse proxy client logs to see message forwarding in action.

Testing Reconnection

1. Start the reverse proxy client with max retries:

python3 -m mcpgateway.reverse_proxy \
    --local-stdio "uvx mcp-server-git" \
    --gateway http://localhost:4444 \
    --token $MCPGATEWAY_BEARER_TOKEN \
    --max-retries 3 \
    --reconnect-delay 2

2. Stop the gateway temporarily and observe the client attempting to reconnect.

3. Restart the gateway and verify the client reconnects automatically.

Unit Tests

Run the existing test suite to ensure no regressions:

make test

Integration Testing

1. Test with multiple reverse proxy clients connecting simultaneously
2. Test authentication failures by using invalid tokens
3. Test graceful shutdown using Ctrl+C on the client
4. Test with different MCP servers (mcp-server-filesystem, mcp-server-github, etc.)

Verification Checklist

• Reverse proxy client can connect to gateway via WebSocket
• Local MCP server starts and communicates via stdio
• Messages are properly forwarded bidirectionally
• Authentication with JWT tokens works correctly
• Sessions can be listed via the API
• Sessions can be disconnected via the API
• Heartbeat/keepalive maintains connection
• Automatic reconnection works on connection loss
• Graceful shutdown cleans up resources properly
• Multiple clients can connect simultaneously
• Error handling works for malformed messages
• Logging provides useful debugging information

Known Limitations

1. SSE transport is not yet implemented (WebSocket only)
2. Request correlation between gateway and local server is simplified
3. No built-in TLS/SSL for the stdio subprocess communication
4. Session persistence across gateway restarts not implemented

Future Enhancements

1. Implement SSE transport as fallback option
2. Add proper request/response correlation with ID tracking
3. Support for multiple local servers per reverse proxy client
4. Session persistence and recovery
5. Metrics and monitoring for reverse proxy connections
6. Load balancing across multiple gateway instances