mcp-http-bridge/docs/INSTALL.md

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

# Testing the MCP HTTP Bridge Package

## Quick Test Setup

### 1. Start Your Local MCP Server

First, make sure your local MCP server is running:

```bash
# In the main project directory
cd ..
npm run dev
```

This starts the server at `http://localhost:3000`

### 2. Install the Bridge Package

From this directory:

```bash
# Option A: Install globally (recommended)
npm install -g .

# Option B: Use directly with node
# (already set up - just use the config below)
```

### 3. Configure Cursor

Copy the configuration from `cursor-test-config.json` to your Cursor MCP settings:

**For Global Installation:**
```json
{
  "mcpServers": {
    "remote-websearch": {
      "command": "mcp-http-bridge",
      "env": {
        "MCP_SERVER_URL": "http://localhost:3000/websearch/mcp",
        "MCP_PASS_VARS": "GOOGLE_API_KEY,GOOGLE_SEARCH_ENGINE_ID",
        "GOOGLE_API_KEY": "your-actual-api-key",
        "GOOGLE_SEARCH_ENGINE_ID": "your-actual-search-engine-id"
      }
    }
  }
}
```

**For Local Testing:**
```json
{
  "mcpServers": {
    "test-bridge": {
      "command": "node",
      "args": ["C:/path/to/mcp-http-bridge-package/index.js"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:3000/websearch/mcp",
        "MCP_PASS_VARS": "GOOGLE_API_KEY,GOOGLE_SEARCH_ENGINE_ID",
        "GOOGLE_API_KEY": "your-actual-api-key",
        "GOOGLE_SEARCH_ENGINE_ID": "your-actual-search-engine-id"
      }
    }
  }
}
```

### 4. Test the Bridge

You can test the bridge manually:

```bash
# Set environment variables
$env:MCP_SERVER_URL = "http://localhost:3000/websearch/mcp"
$env:MCP_PASS_VARS = "GOOGLE_API_KEY"
$env:GOOGLE_API_KEY = "test-key"

# Run the bridge
node index.js
```

Expected output:
```
🌉 Starting MCP-HTTP bridge to: http://localhost:3000/websearch/mcp
🎯 Using explicit variable list: GOOGLE_API_KEY
🔧 Passing 1 environment variables as headers
✅ Connected to remote MCP server
🔌 Bridge ready - Cursor can now connect via stdio
```

### 5. Verify in Cursor

1. Restart Cursor
2. Open the MCP panel
3. You should see your bridge-connected server
4. Try using the web search tools

## Troubleshooting

### Bridge Connection Issues

1. **"MCP_SERVER_URL is required"**
   - Make sure the environment variable is set in your Cursor config

2. **"Failed to connect to remote server"**
   - Ensure your local server is running (`npm run dev`)
   - Check that `http://localhost:3000/websearch/mcp` is accessible

3. **"No tools available"**
   - Check that your API keys are correctly set
   - Verify the `MCP_PASS_VARS` includes the required variables

### Debug Mode

The bridge outputs helpful information to stderr. In Cursor, you can see this in the MCP logs.

## What This Tests

✅ **Bridge Functionality**: Stdio to HTTP conversion  
✅ **Variable Passing**: Environment variables → HTTP headers  
✅ **Explicit Control**: Only specified variables are passed  
✅ **Remote Server**: Connection to HTTP-deployed MCP servers  
✅ **Cursor Integration**: Full MCP protocol support  

## Next Steps

Once this works locally, you can:

1. **Deploy your MCP server** to a cloud provider
2. **Update the MCP_SERVER_URL** to point to your remote server
3. **Use the bridge** to connect Cursor to any remote MCP server
4. **Publish the package** to npm for others to use