README - mcp-bridge by crazyrabbitltc

MCP Bridge

A Model Context Protocol (MCP) server that bridges multiple MCP servers with HTTP/SSE transport support and LLM-powered tool orchestration.

🚀 Quick Start

Prerequisites

Node.js 18+
Anthropic API key

Install & Run

npm install
npm run build

# Stdio mode (for Claude Desktop/Cursor)
ANTHROPIC_API_KEY=your-key npm start

# HTTP mode (for web apps/remote access)
TRANSPORT_TYPE=http HTTP_PORT=3001 ANTHROPIC_API_KEY=your-key npm start

📡 Transport Modes

Stdio Mode (Local Integration)

Perfect for Claude Desktop, Cursor, and other MCP clients:

# Start server
ANTHROPIC_API_KEY=your-key npm start

# Test with echo
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npm start

HTTP Mode (Network Access)

For web applications and remote clients:

# Start HTTP server
TRANSPORT_TYPE=http HTTP_PORT=3001 ANTHROPIC_API_KEY=your-key npm start

# Test health endpoint
curl http://localhost:3001/health

# Create SSE connection
curl -H "Accept: text/event-stream" http://localhost:3001/mcp/sse/my-session

# Send JSON-RPC request
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -H "x-session-id: my-session" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

🔧 MCP Client Setup

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-bridge": {
      "command": "node",
      "args": ["/path/to/mcp-bridge/dist/index.js"],
      "env": {
        "ANTHROPIC_API_KEY": "your-key"
      }
    }
  }
}

Cursor IDE

Add to your workspace settings:

{
  "mcp.servers": {
    "mcp-bridge": {
      "command": "node",
      "args": ["/path/to/mcp-bridge/dist/index.js"],
      "env": {
        "ANTHROPIC_API_KEY": "your-key"
      }
    }
  }
}

⚙️ Connecting Other MCP Servers

Configuration File

Create mcp-wrapper-config.json:

{
  "servers": [
    {
      "name": "filesystem",
      "transport": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
      }
    },
    {
      "name": "github",
      "transport": {
        "type": "stdio", 
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
        }
      }
    },
    {
      "name": "postgres",
      "transport": {
        "type": "stdio",
        "command": "npx", 
        "args": ["-y", "@modelcontextprotocol/server-postgres"],
        "env": {
          "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/db"
        }
      }
    }
  ],
  "toolGroups": {
    "development": {
      "description": "Development workflow tools",
      "servers": ["filesystem", "github"]
    },
    "data": {
      "description": "Data analysis and database operations", 
      "servers": ["postgres"]
    }
  }
}

Environment Variables

Or configure via environment:

export MCP_SERVERS='[
  {
    "name": "brave-search",
    "transport": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {"BRAVE_API_KEY": "your-key"}
    }
  }
]'

🌐 HTTP API Reference

Endpoints

GET /health - Server health status
GET /mcp/sessions - List active sessions
GET /mcp/sse/:sessionId - Server-Sent Events connection
POST /mcp - JSON-RPC requests (requires x-session-id header)
DELETE /mcp/session/:sessionId - Close session

WebSocket-style Usage

// Connect to SSE
const eventSource = new EventSource('http://localhost:3001/mcp/sse/my-session');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Response:', data);
};

// Send request
fetch('http://localhost:3001/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-session-id': 'my-session'
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: {
      name: 'list_tool_groups',
      arguments: {}
    }
  })
});

🛠️ Available Tools

list_tool_groups - Discover available tool groups
get_health_status - Server health and metrics
get_server_stats - Detailed server statistics
check_ticket - Monitor operation progress
list_tickets - View operation history
Dynamic Tool Groups - LLM-generated groups based on discovered tools

🏗️ Architecture

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Client    │    │ MCP Bridge  │    │   MCP       │
│(Claude/Web) │◄──►│   Server    │◄──►│  Servers    │
└─────────────┘    └─────────────┘    └─────────────┘
                          │
                   ┌──────┴──────┐
                   │     LLM     │
                   │Coordination │
                   └─────────────┘

Key Features

Multi-transport support - stdio, HTTP, SSE
Session management - Track context across requests
Tool orchestration - LLM-powered tool coordination
Health monitoring - Real-time status and metrics
Graceful shutdown - Clean resource management

🧪 Development

# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Run tests
npm test

# E2E tests
npm run test:e2e

📝 License

MIT License

🙏 Attribution

Developed with assistance from Claude Code (Anthropic) - an AI-powered development environment that helped architect, implement, and test this MCP bridge server.

Connect multiple MCP servers with modern transport protocols