Deploy your first LoxiLB MCP server

This guide will show you how to deploy your own remote MCP server with LoxiLB integration, with two deployment options:

• Local deployment — Run on the same host as your MCP client (e.g., Claude Desktop) for development and testing.
• Remote deployment — Run on a separate server for production environments with HTTPS support.

The LoxiLB SSE Remote Server is a Model Context Protocol (MCP) server implementation that uses Server-Sent Events (SSE) for real-time communication. This project provides a comprehensive set of tools for interacting with various services including GitHub, Slack, the filesystem, and LoxiLB load balancer management.

Quick start

Get up and running in 5 minutes:

1. Clone and configure

   hljs language-bash

   Copy

   git clone https://github.com/loxilb-io/loxilb-mcp.git
   cd loxilb-mcp
   cp .env.example .env
   # Edit .env with your LoxiLB URL and tokens
   

2. Start the server

   hljs language-bash

   Copy

   docker-compose up -d
   

   Your MCP server is now running on http://localhost:8787/sse

   In a new terminal, run the MCP inspector. The MCP inspector is an interactive MCP client that allows you to connect to your MCP server and invoke tools from a web browser.

3. Test with MCP Inspector

   hljs language-bash

   Copy

   npx @modelcontextprotocol/inspector@latest
   

   Open the MCP inspector in your web browser

   In the inspector, set the trasport type to SSE, enter the URL of your MCP server, http://localhost:8787/sse, enter the authentication's header name as Authorization, and Bearer Token as admin-token, and click Connect. You should see the "List Tools" button, which will list the tools that your MCP server exposes.

   

4. Connect Claude Desktop Add the server configuration to your claude_desktop_config.json

   hljs language-bash

   Copy

   {
      "mcpServers": {
        "netlox": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "http://localhost:8788/sse",
            "--header",
            "Authorization: Bearer ${AUTH_TOKEN}"
          ],
          "env": {
            "AUTH_TOKEN": "admin-key"
          }
        }
      }
    }
   

   

Architecture

The server is built using FastMCP, a framework for implementing MCP servers. It uses Server-Sent Events (SSE) for real-time communication and implements authentication with different access levels (admin, user, read-only).

SSL deployment options

For production deployments, the LoxiLB SSE Server supports multiple SSL certificate options:

• Self-signed certificates — Quick setup for development and testing
• Let's Encrypt certificates — Free automated SSL certificates for production
• Traditional CA certificates — Enterprise-grade certificates from certificate authorities

📋 Note: For detailed SSL setup instructions, certificate generation, and troubleshooting, see the SSL Setup Guide.

Quick SSL setup

Use the included SSL automation scripts to generate certificates:

chmod +x ./scripts/generate-ssl.sh
chmod +x ./scripts/certbot-ssl.sh
chmod +x ./scripts/generate-ssl-certs.sh

# For development (self-signed certificates)
./generate-ssl.sh dev

# For production with Let's Encrypt
# Setup Certbot environment
./generate-ssl.sh certbot setup

# Obtain certificate
./generate-ssl.sh certbot obtain -d yourdomain.com

SSL certificate management

The project includes comprehensive SSL management tools:

• Automated certificate generation with OpenSSL
• Let's Encrypt integration with Certbot
• Automatic renewal setup for Let's Encrypt certificates
• Certificate validation and monitoring
• Docker volume management for SSL files

Configuration

The server requires two configuration files: .env and tool-providers.config.json.

Quick Setup

1. Create .env file with your settings:

# Server settings
PORT=8788
HOST=0.0.0.0
ENDPOINT=sse
ENABLE_AUTH=true

# Required
LOXILB_BASE_URL=http://your.loxilb.api.url/netlox/v1

# Optional (only if respective tools are enabled)
GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
SLACK_BOT_TOKEN=your_slack_token_here

NODE_ENV=production

2. Create tool-providers.config.json file:

{
  "filesystem": {
    "enabled": true,
    "allowedDirectories": [
      "/workspace/sse-remote-server/loxilb",
      "/workspace/sse-remote-server/loxilb-epbf",
      "/workspace/sse-remote-server/loxicmd",
      "/workspace/sse-remote-server/loxilbdocs"
    ]
  },
  "github": {
    "enabled": true
  },  
  "slack": { 
    "enabled": true 
  },
  "loxilb": {
    "enabled": true
  }
}

Disabling Tools You Don't Need

To disable GitHub and/or Slack integration:

1. Set "enabled": false for the tools you don't need in tool-providers.config.json
2. Skip providing the corresponding tokens in your .env file

Example:

{
  "github": { "enabled": false },
  "slack": { "enabled": false }
}

This reduces dependencies and simplifies setup.

Available tool providers

The server provides several specialized tool providers for different services and operations.

LoxiLB tools

Comprehensive tools for managing LoxiLB load balancer operations:

GET Operations (llb-allget-tools.ts)

• Version information, network interfaces, route details
• Load balancer configurations and statistics
• System status and performance metrics

POST Operations (llb-post-tools.ts)

• Load balancer configuration and policies
• Network setup and VLAN configuration
• BGP routing and service management

Example tools:

• loxilb_version_get — Get LoxiLB version information
• loxilb_lb_post — Create or update load balancer configurations
• loxilb_lb_stats_get — Get performance metrics and statistics

GitHub tools

Full GitHub API integration for repository and development operations:

Repository Operations

• Search, create, update, and delete repositories
• Branch and tag management
• Repository configuration and settings

Issue Management

• Create, update, and list issues
• Comment management and labeling
• Issue assignment and tracking

Pull Request Operations

• Create and manage pull requests
• Review and merge operations
• Status checks and approvals

File Operations

• Read, write, and delete files
• Commit operations and history
• Content management across branches

Example tools:

• search_repositories — Search GitHub repositories
• get_issue — Get specific GitHub issue details
• create_pull_request — Create new pull request

Slack tools

Slack workspace integration for communication and collaboration:

Channel Operations

• List channels and get channel history
• Channel information and metadata
• Channel member management

Message Operations

• Send, update, and delete messages
• Message formatting and attachments
• Thread management and replies

User Operations

• List users and get user information
• User profile details and status
• Presence and activity tracking

File Operations

• Upload files to Slack channels
• List and manage uploaded files
• File sharing and permissions

Example tools:

• slack_list_channels — List available Slack channels
• slack_send_message — Send message to a Slack channel
• slack_upload_file — Upload file to Slack

Filesystem tools

Secure filesystem operations within configured directories:

File Operations

• Read, write, and delete files
• File content management and editing
• File metadata and permissions

Directory Operations

• List directory contents and structure
• Create and delete directories
• Directory navigation and management

Search Operations

• File and content search capabilities
• Pattern matching and filtering
• Recursive directory operations

Security features:

• Operations restricted to allowed directories only
• Path traversal protection
• File type and size validation

Example tools:

• read_file — Read file content safely
• write_file — Write content to file
• list_directory — List directory contents

Setup required third-party tokens

Before deploying the server, you'll need to obtain API tokens for the services you want to integrate.

📋 Note: You can disable any tool provider you don't need by setting "enabled": false in your tool-providers.config.json file.

GitHub Personal Access Token

1. Navigate to GitHub settings

   • Go to Personal access tokens (Settings > Developer settings)

2. Create new token

   • Click "Generate new token" > "Generate new token (classic)"
   • Select repository access scope (Public, All, or Selected repositories)

3. Configure permissions

   • For private repositories: Select repo scope ("Full control of private repositories")
   • For public repositories only: Select public_repo scope

4. Save the token

   • Copy the generated token and add it to your .env file as GITHUB_PERSONAL_ACCESS_TOKEN

Slack Bot Token

1. Create Slack App

   • Visit the Slack Apps page
   • Click "Create New App" > "From scratch"
   • Name your app and select your workspace

2. Configure OAuth scopes Navigate to "OAuth & Permissions" and add these Bot Token Scopes:

   • channels:history — View messages in public channels
   • channels:read — View basic channel information
   • chat:write — Send messages as the app
   • reactions:write — Add emoji reactions to messages
   • users:read — View users and basic information
   • users.profile:read — View detailed user profiles

3. Install to workspace

   • Click "Install to Workspace" and authorize the app
   • Save the "Bot User OAuth Token" (starts with xoxb-)

4. Get Team ID

   • Find your Team ID (starts with T) using this guide

Install LoxiLB SSE Server

Choose your deployment method based on your requirements:

Docker deployment (Recommended)

The recommended way to deploy the LoxiLB SSE Server is using Docker containers.

Prerequisites:

• Docker and Docker Compose installed
• Configuration files (.env and tool-providers.config.json) prepared

Quick start:

# Clone or download the project
git clone https://github.com/loxilb-io/loxilb-mcp.git
cd loxilb-mcp

# Create your configuration files
cp .env.example .env
# Edit .env with your settings

# Start the server
docker-compose up -d

Port configuration:

⚠️ Warning: Ensure the port mapping in your Docker command matches the PORT defined in your .env file.

# If PORT=8788 in .env
docker run -p 8788:8788 --env-file .env \
  -v $(pwd)/tool-providers.config.json:/workspace/sse-remote-server/tool-providers.config.json:ro \
  loxilbmcp-sse-server:v0.9.8

# If you change PORT=9000 in .env, update the mapping
docker run -p 9000:9000 --env-file .env \
  -v $(pwd)/tool-providers.config.json:/workspace/sse-remote-server/tool-providers.config.json:ro \
  loxilbmcp-sse-server:v0.9.8

Deployment considerations

Local deployment

• Ideal for development and testing
• Simplified configuration with localhost connections
• Minimal network latency

Remote deployment

• Better for production environments
• Supports multiple client connections
• Centralized LoxiLB resource management
• Requires HTTPS for secure connections

Server connectivity

Connect to your LoxiLB SSE Server using the appropriate URL format:

Deployment types:

• Local deployment

  • URL: http://localhost:<PORT>/sse
  • Port must match your .env configuration
  • No SSL required for localhost connections

• Remote deployment

  • URL: https://<server_hostname>:<PORT>/sse
  • HTTPS required for remote connections
  • Valid SSL certificate needed

⚠️ Warning: Ensure firewall configurations allow connections to the specified port.

Authentication

The server implements role-based authentication with predefined access keys:

Access levels:

• admin-key

  • Access Level: Administrator
  • Permissions: read, write, delete, admin operations
  • Use for: Full system management and configuration

• user-key

  • Access Level: Regular User
  • Permissions: read, write operations
  • Use for: Standard tool operations and data access

• readonly-key

  • Access Level: Guest
  • Permissions: read-only access
  • Use for: Monitoring and information retrieval

Authentication header format:

Authorization: Bearer <access-key>

📋 Note: These predefined keys are intended for initial setup and testing. For production environments, implement a more secure authentication system with user-specific tokens.

Test with MCP Inspector

The MCP Inspector is a powerful debugging tool that allows you to test your LoxiLB SSE Server before connecting it to Claude Desktop. It provides a web interface to explore available tools and test their functionality.

Install MCP Inspector

npm install -g @modelcontextprotocol/inspector

Test your server

1. Start your LoxiLB SSE Server:

   hljs language-bash

   Copy

   # Using Docker
   docker run -p 8788:8788 --env-file .env \
     -v $(pwd)/tool-providers.config.json:/workspace/sse-remote-server/tool-providers.config.json:ro \
     loxilbmcp-sse-server:v0.9.8
   

2. Launch MCP Inspector:

   hljs language-bash

   Copy

   npx @modelcontextprotocol/inspector@latest
   

3. Test functionality:

   • Browse available tools in the Inspector interface
   • Test LoxiLB API operations (GET/POST endpoints)
   • Verify GitHub and Slack integrations (if enabled)
   • Test filesystem operations within allowed directories
   • Validate authentication with different access levels

Inspector features

The MCP Inspector provides:

• Tool discovery — See all available tools and their schemas
• Interactive testing — Execute tools with custom parameters
• Response validation — View detailed responses and error messages
• Authentication testing — Test different auth tokens and access levels
• Real-time monitoring — Monitor SSE connections and events

💡 Tip: Use the Inspector to validate your configuration before connecting to Claude Desktop. This helps identify configuration issues early and ensures smooth operation.

Usage with Claude Desktop (MCP Client)

To use this with Claude Desktop, add the following to your claude_desktop_config.json:

Configuration based on deployment type

You need to adjust the URL in the configuration based on where your LoxiLB SSE Server is running:

⚠️ Important: When connecting to a remote LoxiLB SSE Server from Claude Desktop, you must use HTTPS (not HTTP). Only localhost connections can use HTTP.

Local deployment Use http://localhost:<PORT>/sse where PORT matches your .env file.

Remote deployment Use https://<server_ip_or_hostname>:<PORT>/sse with HTTPS for secure connections.

Make sure to replace <PORT> with the actual port number from your .env file (default: 8788) and <server_ip_or_hostname> with the actual IP address or hostname of your remote server.

Example Configuration

{
  "mcpServers": {
    "loxilb": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8788/sse",  // Change this URL based on your deployment
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "admin-key"  // This must match the authentication credentials on your server
      }
    }
  }
}

Remote deployment example

⚠️ HTTPS required: When connecting to a remote LoxiLB SSE Server from Claude Desktop, you must use HTTPS (not HTTP). Only localhost connections can use HTTP. See the SSL deployment options for setting up HTTPS.

{
  "mcpServers": {
    "loxilb": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-server-domain.com/sse",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "admin-key"
      }
    }
  }
}

Troubleshooting

Connection issues

If you experience connection issues with the MCP client (e.g., Claude Desktop), it may be due to previous session cookies causing conflicts.

💡 Quick fix: Clear the MCP authentication cache by running rm -rf ~/.mcp-auth and restart Claude Desktop.

Steps to resolve:

1. Clear the MCP authentication cache:

   hljs language-bash

   Copy

   rm -rf ~/.mcp-auth
   

2. Restart your Claude Desktop application

3. The connection should now work properly with the LoxiLB SSE Server

This is particularly helpful when switching between different MCP servers or when authentication credentials have changed.

Server not reachable

If the server is not reachable, check the following:

Common issues:

• Server status

  • Verify that the LoxiLB SSE Server is running
  • Check container logs: docker logs loxilbmcp-sse-server

• Port configuration

  • Ensure the port in your .env file matches the Docker run command
  • Verify firewall settings allow connections to the specified port

• Network connectivity

  • Test direct connection: curl http://localhost:8788/sse (adjust port as needed)
  • For remote servers, verify DNS resolution and network routing

• LoxiLB connectivity

  • Verify the LOXILB_BASE_URL in your .env file is correct and reachable
  • Test LoxiLB API: curl ${LOXILB_BASE_URL}/netlox/v1/status

HTTPS support

The LoxiLB SSE Server supports HTTP directly. For HTTPS support in production, use Nginx as a reverse proxy with SSL termination.

📋 Note: The project includes automated SSL certificate generation and Nginx configuration. See the SSL Setup Guide for complete setup instructions.

Quick HTTPS setup:

1. Generate SSL certificates:

   hljs language-bash

   Copy

   # Let's Encrypt (recommended for production)
   make ssl-certbot-setup DOMAIN=yourdomain.com EMAIL=your@email.com
   make ssl-certbot-obtain DOMAIN=yourdomain.com
   
   # Or self-signed for development
   make ssl-dev DOMAIN=localhost
   

2. Start with Docker Compose:

   hljs language-bash

   Copy

   docker-compose up -d
   

This automatically configures:

• Nginx reverse proxy with SSL termination
• Automatic HTTP to HTTPS redirect
• Security headers and rate limiting
• Certificate management with volume mounts

Example Nginx configuration:

events {
    worker_connections 1024;
}

http {
    upstream loxilbmcp-sse-server {
        server loxilbmcp-sse-server:8788;
        keepalive 32;
    }

    # Rate limiting
    limit_req_zone $binary_remote_addr zone=sse_limit:10m rate=10r/s;
    limit_conn_zone $binary_remote_addr zone=conn_limit:10m;

    server {
        listen 80;
        server_name _;
        return 301 https://$host$request_uri;
    }

    server {
        listen 443 ssl;
        server_name oam.loxilb.io;                     # change me

        ssl_certificate /path/to/your/certificate.crt;  # change me
        ssl_certificate_key /path/to/your/private.key;  # change me

        location / {
            proxy_pass http://loxilbmcp-sse-server;  # change me
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_buffering off;
            proxy_cache off;
            proxy_http_version 1.1;
            chunked_transfer_encoding off;
            proxy_read_timeout 3600s;
            proxy_send_timeout 3600s;
        }
    }
}

With this setup, clients can connect securely via HTTPS while the LoxiLB SSE Server continues to run with HTTP.

Using Docker Compose for HTTPS Setup

For your convenience, we've prepared a docker-compose.yml file that sets up both the LoxiLB SSE Server and Nginx proxy together, enabling HTTPS for remote connections:

version: '3.8'

services:
  loxilbmcp-sse-server:
    image: ${REGISTRY:-kongseokhwan}/${IMAGE_NAME:-loxilbmcp-sse-server}:${IMAGE_TAG:-v0.9.8} # change me
    container_name: loxilbmcp-sse-server
    ports:
      - "${PORT:-8788}:${PORT:-8788}"
    environment:
      # Server configuration
      - PORT=${PORT:-8788}
      - HOST=${HOST:-0.0.0.0}
      - ENDPOINT=${ENDPOINT:-sse}
      
      # Authentication
      - ENABLE_AUTH=${ENABLE_AUTH:-true}
      
      # Tool provider tokens
      - GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN:-your_access_token} # your github personal access token
      - SLACK_BOT_TOKEN=${SLACK_BOT_TOKEN:-your_slack_token} # your slack bot token
      - SLACK_TEAM_ID=${SLACK_TEAM_ID:-your_slack_team_id} # your slack team id
      - LOXILB_BASE_URL=${LOXILB_BASE_URL:-your_loxilb_base_url} # your loxilb base url
      
      # Node.js settings
      - NODE_ENV=production
    volumes:
      - ./tool-providers.config.json:/app/tool-providers.config.json:ro
    restart: unless-stopped    
    networks:
      - loxilbmcp-network

  # Nginx reverse proxy for SSL termination
  nginx:
    image: nginx:alpine
    container_name: loxilbmcp-nginx
    ports:
      - "443:443"
      - "80:80"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/ssl:/etc/nginx/ssl:ro
    depends_on:
      - loxilbmcp-sse-server
    restart: unless-stopped
    networks:
      - loxilbmcp-network

networks:
  loxilbmcp-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

Setup Instructions

1. Prepare SSL Certificates:

   • Create an nginx/ssl directory
   • Place your SSL certificate and key in this directory
   • Update the paths in nginx/nginx.conf to match your certificate filenames

2. Configure Environment Variables:

   • Create a .env file with your configuration
   • Set your GitHub, Slack, and LoxiLB credentials

3. Start the Services:

   hljs language-bash

   Copy

   docker-compose up -d
   

Related resources

Documentation

• SSL Setup Guide — Comprehensive guide for SSL certificate generation, Let's Encrypt automation, and HTTPS configuration.

Configuration files

• Docker Compose — Complete Docker Compose configuration with Nginx reverse proxy and SSL volume management.

External resources

• Model Context Protocol — Official MCP documentation and specifications.
• FastMCP Framework — Framework used for building this MCP server implementation.

Support

For issues and questions:

• Documentation: Check the SSL Setup Guide for detailed configuration help
• Issues: Report bugs and feature requests on the project repository
• Community: Join the LoxiLB community discussions