mcp-http-bridge/README.md

Generic bridge client for connecting MCP clients to remote MCP servers via HTTP supporting session based environment variables

# MCP HTTP Bridge

A generic bridge client that enables [Cursor](https://cursor.sh) to connect to remote MCP (Model Context Protocol) servers via HTTP.

## 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
- 🔧 Pass **environment variables** as HTTP headers automatically  
- 🎯 Control **exactly which variables** get passed to remote servers
- 🔒 Keep **sensitive configuration** secure with proper filtering

## Installation

### Option 1: Global Installation (Recommended)

```bash
npm install -g mcp-http-bridge
```

### Option 2: Local Installation

```bash
npm install mcp-http-bridge
```

## Quick Start

### 1. Configure Cursor

Add to your Cursor MCP configuration file:

```json
{
  "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"
      }
    }
  }
}
```

### 2. Start Cursor

The bridge will automatically:
- Connect to your remote MCP server
- 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)

## Variable Passing Modes

### Explicit Mode (Recommended)

Specify exactly which variables to pass:

```json
{
  "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.

### Auto-Detection Mode (Fallback)

If `MCP_PASS_VARS` is not set, automatically passes all non-system variables:

```json
{
  "env": {
    "MCP_SERVER_URL": "https://server.com/mcp",
    "API_KEY": "abc123"
  }
}
```

**Result**: `API_KEY` is automatically detected and 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`

## Examples

### SQL Server Connection

```json
{
  "mcpServers": {
    "remote-sql": {
      "command": "mcp-http-bridge",
      "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

```json
{
  "mcpServers": {
    "remote-search": {
      "command": "mcp-http-bridge", 
      "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"
      }
    }
  }
}
```

### Multiple Variables with Filtering

```json
{
  "mcpServers": {
    "complex-server": {
      "command": "mcp-http-bridge",
      "env": {
        "MCP_SERVER_URL": "https://complex-mcp.example.com/mcp",
        "MCP_PASS_VARS": "API_KEY,DATABASE_URL",
        "API_KEY": "server-needs-this",
        "DATABASE_URL": "server-needs-this-too", 
        "LOGGING_LEVEL": "debug",
        "CACHE_TTL": "3600",
        "FEATURE_FLAGS": "a,b,c",
        "ANALYTICS_KEY": "local-only"
      }
    }
  }
}
```

Only `API_KEY` and `DATABASE_URL` are passed to the server.

## Troubleshooting

### Connection Issues

```bash
# 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"}'
```

### Debug Mode

The bridge outputs helpful debug information to stderr:

```
🌉 Starting Cursor-HTTP bridge to: https://server.com/mcp
🎯 Using explicit variable list: API_KEY,DATABASE_URL
🔧 Passing 2 environment variables as headers
✅ Connected to remote MCP server
🔌 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. **"No tools/resources available"**
   - Check that required environment variables are being passed
   - Verify the remote server has the expected configuration

## 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 **authentication** on your remote MCP servers

## Requirements

- Node.js 18.0.0 or higher
- Remote MCP server supporting Streamable HTTP transport

## License

MIT

## Contributing

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