MCP HTTP Bridge

A generic bridge client that enables Cursor to connect to remote MCP (Model Context Protocol) servers via HTTP with OAuth authentication support.

What It Does

This bridge converts Cursor's stdio-based MCP interface to HTTP requests, allowing you to:

• 🌐 Connect Cursor to remote MCP servers deployed anywhere
• 🔐 OAuth authentication with automatic browser-based login flow
• 🔧 Pass environment variables as HTTP headers automatically
• 🎯 Control exactly which variables get passed to remote servers
• 🔒 Keep sensitive configuration secure with proper filtering
• 📡 Support Server-Sent Events (SSE) for streaming responses
• 🐛 Debug logging for troubleshooting connections
• 🎫 Session management for stateful server interactions

Installation

Option 1: NPX (Recommended - No Installation Required)

Use npx to run the latest version automatically without installing:

{
  "mcpServers": {
    "remote-server": {
      "command": "npx",
      "args": ["mcp-http-bridge@latest"],
      "env": {
        "MCP_SERVER_URL": "https://your-mcp-server.com/mcp",
        "MCP_PASS_VARS": "API_KEY,DATABASE_URL",
        "API_KEY": "your-api-key",
        "DATABASE_URL": "your-database-url"
      }
    }
  }
}

Benefits of NPX approach:

• ✅ Always latest version - automatically downloads and runs the newest version
• ✅ No installation required - no need to install globally or manage versions
• ✅ No maintenance - automatically gets updates when available
• ✅ Clean system - doesn't clutter your global npm packages

Option 2: Global Installation

npm install -g mcp-http-bridge

Then use in Cursor configuration:

{
  "mcpServers": {
    "remote-server": {
      "command": "mcp-http-bridge",
      "env": {
        "MCP_SERVER_URL": "https://your-mcp-server.com/mcp",
        "MCP_PASS_VARS": "API_KEY,DATABASE_URL",
        "API_KEY": "your-api-key",
        "DATABASE_URL": "your-database-url"
      }
    }
  }
}

Option 3: Local Installation

npm install mcp-http-bridge

Quick Start

1. Configure Cursor (Recommended NPX Approach)

Add to your Cursor MCP configuration file (~/.cursor/mcp.json or similar):

{
  "mcpServers": {
    "remote-server": {
      "command": "npx",
      "args": ["mcp-http-bridge@latest"],
      "env": {
        "MCP_SERVER_URL": "https://your-mcp-server.com/mcp",
        "MCP_PASS_VARS": "API_KEY,DATABASE_URL",
        "API_KEY": "your-api-key",
        "DATABASE_URL": "your-database-url"
      }
    }
  }
}

2. Start Cursor

The bridge will automatically:

• Connect to your remote MCP server
• Handle OAuth authentication if required
• Pass specified environment variables as X-MCP-* headers
• Provide a stdio interface for Cursor

Configuration

Required Environment Variables

• MCP_SERVER_URL: The URL of your remote MCP server

Optional Environment Variables

• MCP_PASS_VARS: Comma-separated list of variables to pass (recommended)
• MCP_AUTH_URL: OAuth authentication URL (if authentication is required)
• MCP_TOKEN_ENDPOINT: OAuth token endpoint for retrieving and refreshing tokens
• MCP_BRIDGE_DEBUG: Enable debug logging (1 or true)
• MCP_BRIDGE_LOG_FILE: Custom debug log file path (default: ./bridge-debug.log)

Authentication

OAuth Flow

If your MCP server requires authentication, configure the OAuth settings:

{
  "mcpServers": {
    "authenticated-server": {
      "command": "npx",
      "args": ["mcp-http-bridge@latest"],
      "env": {
        "MCP_SERVER_URL": "https://secure-mcp-server.com/mcp/devops",
        "MCP_AUTH_URL": "https://auth-server.com/auth/mcp-session/devops",
        "MCP_TOKEN_ENDPOINT": "https://auth-server.com/auth/mcp-session/token/devops",
        "MCP_PASS_VARS": "API_KEY,DATABASE_URL",
        "API_KEY": "your-api-key",
        "DATABASE_URL": "your-database-url"
      }
    }
  }
}

OAuth Flow:

1. Bridge generates a unique auth session ID
2. Opens browser automatically to authentication URL
3. User completes OAuth flow in browser (or cancels with Ctrl+C)
4. Bridge polls token endpoint for access token (5-minute timeout)
5. Token is stored directly in bridge session
6. All requests include standard Authorization: Bearer <token> header
7. Automatic token refresh when token expires
8. Remote MCP servers receive the token via AUTHORIZATION_HEADER environment variable

OAuth Timeout & Cancellation:

• 5-minute timeout: Authentication automatically fails after 5 minutes
• User cancellation: Press Ctrl+C to cancel OAuth flow anytime
• Graceful cleanup: Bridge properly cleans up on cancellation or timeout
• Clear error messages: Specific errors for timeout, cancellation, or connection issues

Token Management:

• Access Token: Stored in bridge memory, used for API authentication
• Refresh Token: Used to automatically refresh expired access tokens
• Token Expiry: Automatic refresh 1 minute before expiration
• Standard Headers: Uses OAuth Authorization: Bearer <token> header

Token Passing to Remote Servers:

• The bridge automatically passes the Authorization: Bearer <token> header to remote MCP servers
• Remote servers receive this as the AUTHORIZATION_HEADER environment variable
• This enables remote servers to use the same OAuth token for their API calls
• No additional configuration required - tokens are passed transparently

Session Management

The bridge manages two types of sessions:

• Auth Session ID: Used for OAuth flow and token retrieval
• MCP Session ID: Protocol-level session assigned by the server

Authentication Headers:

• Authorization: Bearer <access_token> - Standard OAuth authentication
• mcp-session-id: <session_id> - MCP protocol session (if supported by server)

Variable Passing Modes

Explicit Mode (Recommended)

Specify exactly which variables to pass:

{
  "env": {
    "MCP_SERVER_URL": "https://server.com/mcp",
    "MCP_PASS_VARS": "SQL_SERVER,API_KEY,DATABASE_URL",
    "SQL_SERVER": "mydb.com",
    "API_KEY": "abc123",
    "DATABASE_URL": "postgres://...",
    "LOGGING_LEVEL": "debug",
    "CACHE_TTL": "3600"
  }
}

Result: Only SQL_SERVER, API_KEY, and DATABASE_URL are passed as headers.

No Variables Mode (Secure Default)

If MCP_PASS_VARS is not set, no environment variables are passed:

{
  "env": {
    "MCP_SERVER_URL": "https://server.com/mcp"
  }
}

Result: Only the bridge connects, no environment variables are passed.

Header Conversion

Environment variables are converted to HTTP headers:

• SQL_SERVER=mydb.com → X-MCP-SQL-SERVER: mydb.com
• API_KEY=abc123 → X-MCP-API-KEY: abc123
• DATABASE_URL=postgres://... → X-MCP-DATABASE-URL: postgres://...

System Variables

These variables are never passed to remote servers:

• System paths: PATH, HOME, USER, etc.
• Node.js variables: NODE_ENV, NODE_PATH, npm_*, etc.
• Windows variables: USERPROFILE, PROGRAMFILES, etc.
• Bridge variables: MCP_SERVER_URL, MCP_PASS_VARS, MCP_AUTH_URL, MCP_TOKEN_ENDPOINT

Debug Mode

Enable detailed logging for troubleshooting:

{
  "env": {
    "MCP_SERVER_URL": "https://server.com/mcp",
    "MCP_BRIDGE_DEBUG": "1"
  }
}

Debug Features:

• Console logging to stderr
• File logging to ./bridge-debug.log (or custom path via MCP_BRIDGE_LOG_FILE)
• Environment variable analysis
• HTTP request/response tracing
• Session management details
• OAuth token lifecycle logging

Examples

Simple HTTP MCP Server Example

Try the included example server to see how the bridge works:

1. Run the example server:

   cd examples
   npm install
   npm start

2. Configure Cursor:

   {
     "mcpServers": {
       "simple-example": {
         "command": "npx",
         "args": ["mcp-http-bridge@latest"],
         "env": {
           "MCP_SERVER_URL": "http://localhost:3001/mcp",
           "MCP_PASS_VARS": "API_KEY,DATABASE_URL,SERVICE_NAME",
           "API_KEY": "test-api-key-123",
           "DATABASE_URL": "postgres://localhost:5432/testdb",
           "SERVICE_NAME": "example-service"
         }
       }
     }
   }

3. Test the tools:

   • get_environment - See how headers become environment variables
   • echo_message - Test basic connectivity
   • test_api_connection - Verify authentication flow

The example demonstrates:

• ✅ Header conversion: X-MCP-API-KEY → process.env.API_KEY
• ✅ OAuth handling: Authorization: Bearer <token> → process.env.AUTHORIZATION_HEADER
• ✅ Security filtering: Sensitive variables are masked
• ✅ Standard MCP protocol: Proper JSON-RPC implementation

See examples/README.md for detailed documentation.

Azure DevOps with OAuth

{
  "mcpServers": {
    "azure-devops": {
      "command": "npx",
      "args": ["mcp-http-bridge@latest"],
      "env": {
        "MCP_SERVER_URL": "https://devops-mcp.example.com/mcp/devops",
        "MCP_AUTH_URL": "https://auth.example.com/auth/mcp-session/devops",
        "MCP_TOKEN_ENDPOINT": "https://auth.example.com/auth/mcp-session/token/devops",
        "MCP_PASS_VARS": "AZURE_DEVOPS_ORG,AZURE_DEVOPS_PROJECT",
        "AZURE_DEVOPS_ORG": "myorg",
        "AZURE_DEVOPS_PROJECT": "MyProject"
      }
    }
  }
}

SQL Server Connection

{
  "mcpServers": {
    "remote-sql": {
      "command": "npx",
      "args": ["mcp-http-bridge@latest"],
      "env": {
        "MCP_SERVER_URL": "https://sql-mcp.example.com/mcp",
        "MCP_PASS_VARS": "SQL_SERVER,SQL_DATABASE,SQL_USER,SQL_PASSWORD",
        "SQL_SERVER": "mydb.database.windows.net",
        "SQL_DATABASE": "production",
        "SQL_USER": "admin",
        "SQL_PASSWORD": "secret123"
      }
    }
  }
}

Web Search Service

{
  "mcpServers": {
    "remote-search": {
      "command": "npx",
      "args": ["mcp-http-bridge@latest"],
      "env": {
        "MCP_SERVER_URL": "https://search-mcp.example.com/mcp",
        "MCP_PASS_VARS": "GOOGLE_API_KEY,SEARCH_ENGINE_ID",
        "GOOGLE_API_KEY": "your-google-api-key",
        "SEARCH_ENGINE_ID": "your-search-engine-id"
      }
    }
  }
}

Debug Mode Example

{
  "mcpServers": {
    "debug-server": {
      "command": "npx",
      "args": ["mcp-http-bridge@latest"],
      "env": {
        "MCP_SERVER_URL": "https://server.com/mcp",
        "MCP_BRIDGE_DEBUG": "true",
        "MCP_PASS_VARS": "API_KEY",
        "API_KEY": "test-key"
      }
    }
  }
}

Server-Sent Events Support

The bridge automatically handles both response types:

• JSON responses: Standard MCP JSON-RPC responses
• SSE responses: Server-Sent Events for streaming data

SSE responses are parsed automatically:

event: message
data: {"jsonrpc": "2.0", "result": {...}}

Troubleshooting

Connection Issues

# Check if the remote server is accessible
curl -X POST https://your-mcp-server.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

Authentication Issues

1. Check OAuth URL: Verify MCP_AUTH_URL is correct
2. Token Endpoint: Ensure MCP_TOKEN_ENDPOINT is accessible
3. Browser Access: Check if browser opens automatically
4. Session Timeout: OAuth flow times out after 5 minutes
5. Token Refresh: Automatic refresh handles expired tokens

Debug Mode

Enable debug logging to see detailed information:

{
  "env": {
    "MCP_BRIDGE_DEBUG": "1"
  }
}

Debug Output:

🔥 BRIDGE DEBUG: Bridge starting up...
🔍 Environment variables check:
🌉 Starting Cursor-HTTP bridge to: https://server.com/mcp
🔐 Authentication required. Auth Session ID: mcp-bridge-1234567890-abc123
🌐 Opening browser for authentication...
🎫 Access token retrieved successfully
🎫 Token expires at: 2024-01-15T14:30:00.000Z
🔄 Refresh token available: true
✅ Authentication completed successfully!
🔐 Using OAuth Bearer token
🔧 Passing 2 environment variables as headers
🔌 Bridge ready - Cursor can now connect via stdio

Common Issues

1. "MCP_SERVER_URL is required"

   • Set the MCP_SERVER_URL environment variable

2. "Failed to connect to remote server"

   • Check that the server URL is correct and accessible
   • Verify the server is running and accepting connections

3. "Authentication timeout"

   • Complete OAuth flow within 5 minutes
   • Check MCP_TOKEN_ENDPOINT is accessible
   • Press Ctrl+C to cancel and retry if stuck

4. "MCP_TOKEN_ENDPOINT required for authentication"

   • Set the MCP_TOKEN_ENDPOINT environment variable for OAuth

5. "No tools/resources available"

   • Check that required environment variables are being passed
   • Verify the remote server has the expected configuration

6. SSE parsing errors

   • Server may be sending malformed SSE responses
   • Enable debug mode to see raw response content

7. Token refresh failures

   • Bridge automatically retries with refreshed tokens
   • Check debug logs for token refresh attempts

8. "Continuous token polling in logs"

   • Old bridge processes may still be running in background
   • Kill all Node.js processes: taskkill /f /im node.exe (Windows)
   • Or restart Cursor to clean up all MCP processes
   • Check for leftover mcp-bridge-* session IDs in logs

Security Considerations

• Never hardcode credentials in configuration files
• Use environment variables for sensitive data
• Use MCP_PASS_VARS to control exactly what gets sent
• Deploy remote servers with HTTPS in production
• Implement OAuth authentication for production servers
• Token storage is in-memory only (not persisted to disk)
• Session management prevents unauthorized access
• Standard OAuth headers for better security compliance

Requirements

• Node.js 18.0.0 or higher
• Remote MCP server supporting Streamable HTTP transport
• Modern browser for OAuth authentication (if required)
• OAuth token endpoint supporting authorization_code and refresh_token grants

Architecture

Cursor (stdio) ←→ MCP HTTP Bridge ←→ Remote MCP Server (HTTP/SSE)
                       ↓                        ↑
                  OAuth Provider         Authorization: Bearer <token>
                       ↓
                  Token Endpoint

Components:

• Cursor Interface: stdio-based MCP client
• HTTP Bridge: Converts stdio ↔ HTTP with OAuth authentication
• Remote Server: HTTP-based MCP server expecting Bearer tokens
• OAuth Provider: Handles authentication flow
• Token Endpoint: Issues and refreshes OAuth tokens

Authentication Flow:

1. User authenticates via OAuth provider
2. Bridge retrieves tokens from token endpoint
3. Bridge stores tokens in memory
4. All requests include Authorization: Bearer <token> header
5. Bridge automatically refreshes expired tokens
6. Remote MCP servers receive the token via AUTHORIZATION_HEADER environment variable

License

MIT

Contributing

Issues and pull requests welcome at: https://github.com/your-username/mcp-http-bridge