Skip to content
/ gateway Public

Multi-user MCP integration and management gateway with metrics, granular access control, and native IDE support

License

MIT license
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

hivellm/gateway

BranchesTags

Repository files navigation

@hivellm/gateway

Multi-user MCP (Model Context Protocol) integration and management gateway with metrics, granular access control, and native IDE support.

🎯 Overview

@hivellm/gateway is a complete solution for managing and exposing MCPs through a single access point, offering:

  • Multi-tenancy: Multi-user support with permission control (read, write, admin)
  • MCP Management: Register and configure MCPs with custom commands, arguments, and headers
  • Apps & Gateways: App system to configure MCPs and gateways to aggregate them
  • Security: Access key system and secure credential management (API keys, tokens)
  • Metrics: Complete monitoring with SQLite for local storage
  • Logging: Detailed logging system for auditing and debugging
  • Dashboard: Web interface for simplified management
  • Easy Integration: Native support for Cursor, WindSurf, Claude Code, and Claude Desktop
  • Protocols: Support for Streamable HTTP and SSE (Server-Sent Events)

🚀 Quick Start

# Run directly via npx
npx -y @hivellm/gateway --port 18001

# Or install globally
npm install -g @hivellm/gateway
gateway --port 18001

📋 Requirements

  • Node.js >= 18.0.0
  • npm >= 9.0.0
  • Operating System: Windows, Linux, macOS

🎮 Basic Usage

1. Start the Gateway

# Start with custom port
npx @hivellm/gateway --port 18001

# Start with custom configuration
npx @hivellm/gateway --config ./config.json

# Enable debug mode
npx @hivellm/gateway --port 18001 --debug

2. First Access

On first run, the system will:

  1. Create the SQLite database
  2. Generate a root user with random password
  3. Display credentials in console
  4. Open dashboard at http://localhost:18001
🔐 Root user credentials:
   Username: root
   Password: aB3kL9pQ2mN7xR4w
   
🌐 Dashboard: http://localhost:18001
📡 API Endpoint: http://localhost:18001/api
🔌 Gateway SSE: http://localhost:18001/sse

3. Configuration Flow

1. Create User (admin)
   ↓
2. Register MCP (context7, filesystem, etc)
   ↓
3. Create App (configure MCP with credentials)
   ↓
4. Create Gateway (select apps and tools)
   ↓
5. Generate Access Key
   ↓
6. Integrate with IDE (Cursor, WindSurf, etc)

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│              IDEs / Clients                      │
│  (Cursor, WindSurf, Claude Code, Claude)         │
└───────────────────┬─────────────────────────────┘
                    │ SSE / HTTP
┌───────────────────▼─────────────────────────────┐
│              Gateway Layer                       │
│  - Authentication (API Keys)                     │
│  - Tool Routing                                  │
│  - Metrics & Logging                             │
└───────────────────┬─────────────────────────────┘
                    │
        ┌───────────┼───────────┐
        ▼           ▼           ▼
    ┌─────┐    ┌─────┐    ┌─────┐
    │ App │    │ App │    │ App │
    │  1  │    │  2  │    │  3  │
    └──┬──┘    └──┬──┘    └──┬──┘
       │          │          │
       ▼          ▼          ▼
    ┌─────┐    ┌─────┐    ┌─────┐
    │ MCP │    │ MCP │    │ MCP │
    │  1  │    │  2  │    │  3  │
    └─────┘    └─────┘    └─────┘

📚 Core Concepts

MCPs (Model Context Protocols)

Definition of an MCP server with base configurations:

{
  "id": "mcp-context7-001",
  "name": "context7",
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@context-labs/mcp-server"],
  "env": {},
  "headers": {}
}

Apps

Configured instance of an MCP with specific credentials:

{
  "id": "app-ctx7-prod",
  "name": "Context7 Production",
  "mcp_id": "mcp-context7-001",
  "config": {
    "env": {
      "API_KEY": "sk-xxxxx",
      "BASE_URL": "https://api.context7.com"
    }
  },
  "owner_id": "user-123"
}

Gateways

App aggregator that exposes a selected set of tools:

{
  "id": "gateway-dev-001",
  "name": "Development Gateway",
  "apps": ["app-ctx7-prod", "app-fs-001"],
  "allowed_tools": ["search_files", "read_file", "query_context"],
  "protocol": "sse",
  "owner_id": "user-123"
}

Access Keys

Access keys to authenticate gateway requests:

{
  "id": "key-001",
  "gateway_id": "gateway-dev-001",
  "key": "gw_aB3kL9pQ2mN7xR4w",
  "name": "Cursor Integration",
  "created_at": "2025-10-01T10:00:00Z",
  "expires_at": null
}

🔑 Permissions

Access Levels

  • read: View MCPs, Apps, and Gateways
  • write: Create and edit Apps and Gateways
  • admin: Full access, including creating users and MCPs

Permission Matrix

Resource Read Write Admin
View MCPs ✅ ✅ ✅
Register MCPs ❌ ❌ ✅
Create Apps ❌ ✅ ✅
Create Gateways ❌ ✅ ✅
Generate Access Keys ❌ ✅ ✅
Create Users ❌ ❌ ✅
View Metrics ✅ ✅ ✅
View Logs ❌ ✅ ✅

📊 Metrics

The system automatically collects:

  • Request Metrics

    • Total requests per gateway
    • Requests per tool
    • Requests per user

  • Performance Metrics

    • Average response time
    • Peak response time
    • 95th and 99th percentile

  • Error Metrics

    • Error rate
    • Errors by type
    • Errors by gateway

Visualization

Metrics can be accessed via:

  • Web dashboard
  • REST API: GET /api/metrics?gateway_id=xxx
  • Export: SQLite dump

🔌 IDE Integration

Cursor

{
  "mcpServers": {
    "hivellm-gateway": {
      "url": "http://localhost:18001/sse/gateway-dev-001",
      "headers": {
        "Authorization": "Bearer gw_aB3kL9pQ2mN7xR4w"
      }
    }
  }
}

WindSurf

{
  "mcp": {
    "servers": {
      "hivellm-gateway": {
        "type": "sse",
        "url": "http://localhost:18001/sse/gateway-dev-001",
        "auth": "gw_aB3kL9pQ2mN7xR4w"
      }
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "hivellm-gateway": {
      "transport": {
        "type": "sse",
        "url": "http://localhost:18001/sse/gateway-dev-001",
        "headers": {
          "Authorization": "Bearer gw_aB3kL9pQ2mN7xR4w"
        }
      }
    }
  }
}

Claude Code (VS Code Extension)

{
  "mcp.servers": {
    "hivellm-gateway": {
      "type": "sse",
      "endpoint": "http://localhost:18001/sse/gateway-dev-001",
      "apiKey": "gw_aB3kL9pQ2mN7xR4w"
    }
  }
}

🛠️ CLI Commands

# Start server
gateway start --port 18001

# Create user
gateway user create --username john --role write

# List MCPs
gateway mcp list

# Register MCP
gateway mcp add --name context7 --command "npx" --args "-y,@context-labs/mcp-server"

# Create App
gateway app create --name "My Context7" --mcp context7

# Create Gateway
gateway gateway create --name "Dev Gateway" --apps app-001,app-002

# Generate Access Key
gateway key generate --gateway gateway-dev-001 --name "Cursor Key"

# View metrics
gateway metrics --gateway gateway-dev-001

# Export configuration
gateway export --output config.json

# Import configuration
gateway import --input config.json

# Health check
gateway health

🎨 Dashboard Features

The web dashboard provides:

  • User Management: Create, edit, and manage users
  • MCP Registry: Register and configure MCP servers
  • App Configuration: Create apps with secure credential storage
  • Gateway Management: Create and manage gateways
  • Access Keys: Generate and revoke access keys
  • Real-time Metrics: Live metrics and performance graphs
  • Log Viewer: Search and filter logs
  • Integration Helper: Copy-paste configurations for IDEs

Access the dashboard at: http://localhost:18001

📖 Complete Documentation

🔧 Configuration

Environment Variables

# Server
GATEWAY_PORT=18001
GATEWAY_HOST=0.0.0.0

# Database
DATABASE_PATH=./gateway.db

# Security
JWT_SECRET=your-secret-key
SESSION_SECRET=your-session-secret
ENCRYPTION_KEY=your-encryption-key

# Limits
MAX_MCP_PROCESSES=50
MAX_CONCURRENT_REQUESTS=100
REQUEST_TIMEOUT_MS=30000

# Logging
LOG_LEVEL=info
LOG_FILE=./gateway.log

Configuration File

{
  "server": {
    "port": 18001,
    "host": "0.0.0.0"
  },
  "database": {
    "path": "./gateway.db"
  },
  "security": {
    "jwtSecret": "your-secret-key",
    "sessionSecret": "your-session-secret",
    "encryptionKey": "your-encryption-key"
  },
  "limits": {
    "maxMCPProcesses": 50,
    "maxConcurrentRequests": 100,
    "requestTimeoutMs": 30000
  },
  "logging": {
    "level": "info",
    "file": "./gateway.log"
  }
}

🔒 Security Best Practices

  1. Change Root Password: Change the default root password on first login
  2. Use Strong Keys: Generate strong encryption keys for production
  3. HTTPS: Use HTTPS in production (reverse proxy recommended)
  4. Firewall: Restrict access to trusted IPs
  5. Regular Updates: Keep dependencies updated
  6. Backup: Regular backup of SQLite database
  7. Audit Logs: Review logs regularly for suspicious activity

🚀 Deployment

Docker

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --production

COPY . .

EXPOSE 18001

CMD ["node", "dist/cli/index.js", "start", "--port", "18001"]

Docker Compose

version: '3.8'

services:
  gateway:
    image: hivellm/gateway:latest
    ports:
      - "18001:18001"
    volumes:
      - ./data:/app/data
    environment:
      - DATABASE_PATH=/app/data/gateway.db
      - LOG_FILE=/app/data/gateway.log
    restart: unless-stopped

Systemd Service

[Unit]
Description=HiveLLM Gateway
After=network.target

[Service]
Type=simple
User=gateway
WorkingDirectory=/opt/hivellm-gateway
ExecStart=/usr/bin/node /opt/hivellm-gateway/dist/cli/index.js start --port 18001
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

🤝 Contributing

See CONTRIBUTING.md for details on how to contribute.

📝 License

This project is part of the HiveLLM ecosystem and follows the same license as the main project.

🔗 Useful Links

📞 Support

For questions and support:

  • Open an issue on GitHub
  • Join discussions
  • Consult the complete documentation

🎯 Roadmap

  • GraphQL API support
  • WebSocket protocol support
  • Prometheus metrics export
  • Multi-gateway clustering
  • OAuth2 authentication
  • LDAP/AD integration
  • Custom plugin system
  • Advanced rate limiting
  • Geographic routing
  • A/B testing capabilities

Built with ❤️ by the HiveLLM community

About

Multi-user MCP integration and management gateway with metrics, granular access control, and native IDE support

Resources

Readme

License

MIT license

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages