ms2-mcp-bridge

ms2-mcp-bridge# MS2 MCP Bridge

A remote MCP (Model Context Protocol) bridge that enables connecting to MCP servers over HTTP with OAuth authentication support.

Features

• HTTP Transport: Connect to remote MCP servers via HTTP
• OAuth Authentication: Automatic OAuth 2.0 flow with JWT token support
• Token Management: Secure token storage and automatic refresh
• Flexible Configuration: Support for custom headers, ports, and endpoints
• Debug Mode: Comprehensive logging for troubleshooting
• NPX Support: Run directly with npx without installation

Installation

NPX Usage (Recommended)

# Run the proxy directly with npx
npx ms2-mcp-bridge <server-url> <callback-port> [options]

# Run the client directly with npx
npx ms2-mcp-client <server-url> <callback-port> [options]

Global Installation

# Install globally
npm install -g ms2-mcp-bridge

# Use the commands
ms2-mcp-bridge <server-url> <callback-port> [options]
ms2-mcp-client <server-url> <callback-port> [options]

Build from Source

# Clone the repository
git clone https://github.com/your-org/ms2-mcp-bridge.git
cd ms2-mcp-bridge

# Install dependencies
npm install

# Build the project
npm run build

# The built executables will be at ./dist/proxy.js and ./dist/client.js

Usage

Proxy Command

The proxy creates a bidirectional connection between your local MCP client and a remote MCP server.

npx ms2-mcp-bridge <server-url> <callback-port> [options]

Client Command

The client connects directly to an MCP server for testing and exploration.

npx ms2-mcp-client <server-url> <callback-port> [options]

Command Line Options

Option	Description	Default Value	Required
server-url	URL of the MCP server	-	✅
callback-port	Port for OAuth callback	-	✅
--header	Custom HTTP headers (format: "Key:Value")	{}	❌
--transport	Transport strategy	http-first	❌
--host	Callback hostname	localhost	❌
--callback-port	OAuth callback port	Same as main port	❌
--callback-path	OAuth callback path	/oauth/callback	❌
--debug	Enable debug logging	false	❌

Transport Strategies

• http-first: Prefer HTTP, fallback to SSE
• http-only: Use only HTTP transport
• sse-first: Prefer SSE, fallback to HTTP
• sse-only: Use only SSE transport

Environment Variables

Variable	Description	Default
MCP_ACCESS_TOKEN	Pre-existing access token (optional)	-
MCP_DEBUG	Enable debug mode	false
MCP_CALLBACK_HOST	Default callback hostname	localhost

Examples

Basic Usage with NPX

# Connect to a local MCP server using the proxy
npx ms2-mcp-bridge http://localhost:8011/mcp 8012 \
  --transport http-only \
  --host localhost

# Test connection using the client
npx ms2-mcp-client http://localhost:8011/mcp 8012 \
  --transport http-only \
  --host localhost

# Connect with custom headers
npx ms2-mcp-bridge http://localhost:8011/mcp 8012 \
  --header "Authorization:Bearer your-token" \
  --header "X-Custom-Header:value" \
  --transport http-only

With OAuth Authentication

# The client will automatically open a browser for OAuth flow
npx ms2-mcp-bridge http://localhost:8011/mcp 8012 \
  --transport http-only \
  --host localhost \
  --callback-port 8012 \
  --callback-path /oauth/callback

Debug Mode

# Enable debug logging
npx ms2-mcp-bridge http://localhost:8011/mcp 8012 \
  --transport http-only \
  --debug

Authentication

OAuth Flow

1. Authorization Request: Client opens browser to authorization URL
2. User Authorization: User authorizes the application
3. Callback: Authorization code sent to callback URL
4. Token Exchange: Code exchanged for JWT access token
5. Token Storage: Tokens stored securely for future use

Token Storage

Tokens are stored in the .mcp-auth directory:

• Location: ~/.mcp-auth/mcp-remote-<version>/
• Files:
  • <server-hash>_tokens.json - Access and refresh tokens
  • <server-hash>_debug.log - Debug logs (when enabled)

Token Management

# Clear stored tokens
rm -rf ~/.mcp-auth

# View token storage location
ls -la ~/.mcp-auth/mcp-remote-*/

Configuration for MCP Clients

Claude Desktop Configuration

Create or update ~/.config/claude-desktop/config.json:

{
  "mcpServers": {
    "ms2-mcp-bridge": {
      "command": "npx",
      "args": [
        "ms2-mcp-bridge",
        "http://localhost:8011/mcp",
        "8012",
        "--transport",
        "http-only",
        "--host",
        "localhost",
        "--callback-port",
        "8012",
        "--callback-path",
        "/oauth/callback"
      ],
      "env": {
        "MCP_DEBUG": "false"
      }
    }
  }
}

Default Configuration Template

Save as default-config.json:

{
  "mcpServers": {
    "ms2-mcp-bridge": {
      "command": "npx",
      "args": [
        "ms2-mcp-bridge",
        "http://localhost:8011/mcp",
        "8012",
        "--transport",
        "http-only",
        "--host",
        "localhost",
        "--callback-port",
        "8012",
        "--callback-path",
        "/oauth/callback"
      ],
      "env": {
        "MCP_DEBUG": "false",
        "MCP_CALLBACK_HOST": "localhost"
      }
    }
  }
}

Development

Project Structure

mcp-warroom/
├── src/
│   ├── lib/
│   │   ├── utils.ts              # Connection utilities
│   │   ├── coordination.ts       # OAuth coordination
│   │   └── node-oauth-client-provider.ts  # OAuth client
│   ├── proxy.ts                  # Main proxy implementation
│   └── index.ts                  # Entry point
├── dist/                         # Built output
├── package.json
└── README.md

Building

# Development build
npm run build

# Watch mode (for development)
npm run dev

# Clean build
npm run clean && npm run build

Testing

# Test connection to MCP server
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | \
  ./dist/proxy.js http://localhost:8011/mcp 8012 \
  --transport http-only \
  --debug

# Test OAuth flow (clears tokens first)
rm -rf ~/.mcp-auth && \
  ./dist/proxy.js http://localhost:8011/mcp 8012 \
  --transport http-only \
  --debug

Troubleshooting

Common Issues

1. "Invalid authorization code" error

   • Clear stored tokens: rm -rf ~/.mcp-auth
   • Ensure callback URL matches server configuration

2. Connection refused

   • Verify MCP server is running
   • Check server URL and port

3. Authentication failures

   • Enable debug mode: --debug
   • Check server logs for authentication errors
   • Verify OAuth configuration

Debug Information

Enable debug mode to see detailed logs:

./dist/proxy.js http://localhost:8011/mcp 8012 --debug

Debug logs are stored in:

~/.mcp-auth/mcp-remote-<version>/<server-hash>_debug.log

Server Logs

Check your MCP server logs for authentication and request details:

# Example for Spring Boot server
tail -f logs/application.log | grep -i "authorization\|mcp"

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

• Check the troubleshooting section above
• Enable debug mode for detailed logs
• Review server logs for authentication issues
• Open an issue on GitHub with debug information