MCP HubMCP Hub
wally-kroeker

LibreChatMCPServers

by: wally-kroeker

Instructions for setting up SuperGateway MCP servers in docker containers for docker deployments of LibreChat

9created 07/02/2025
Visit
docker
LibreChat

📌Overview

Purpose: To enable seamless integration of Model Context Protocol (MCP) servers with LibreChat using the Supergateway bridge.

Overview: This framework facilitates the operation of stdio-based MCP servers over Server-Sent Events (SSE) in a Docker environment, enhancing LibreChat's capabilities.

Key Features:

  • Stdio to SSE Bridge: Converts stdio communication from MCP servers to SSE, allowing compatibility with LibreChat and improving flexibility in server communication.

  • Docker Integration: Each MCP server runs in its own Docker container with specified network configurations, ensuring isolated environments and easy scalability.

LibreChat MCP Servers

This directory contains Model Context Protocol (MCP) server implementations that extend LibreChat's capabilities through the Supergateway bridge.

These are the projects integrated together:

  • The protocol providing tools to the Agent: Model Context Protocol Specification
  • Converts stdio MCP servers to SSE allowing each server to run in its own container: Supergateway Documentation
  • Multi-LLM agent and MCP client: LibreChat Documentation

Directory Structure

mcp/
├── brave-search/          # Brave Search API integration
│   ├── Dockerfile
│   └── README.md
├── future-server/         # Template for future MCP servers
│   ├── Dockerfile
│   └── README.md
└── README.md              # This file

Adding New MCP Servers

  1. Create a new directory under mcp/ for your server
  2. Add required files:
    • Dockerfile - Server build configuration
    • README.md - Server-specific documentation
  3. Update docker-compose.override.yml to add your service
  4. Update librechat.yaml to configure the MCP server

Common Configuration

Each MCP server should:

  1. Use Supergateway as a bridge (stdio to SSE)
  2. Follow consistent port numbering (8003+)
  3. Connect to the librechat_default network
  4. Use environment variables for sensitive data

Port Assignments

  • 8003: Brave Search
  • 8004-8099: Reserved for future MCP servers

Security Best Practices

  1. Never commit API keys or sensitive data
  2. Use environment variables for secrets
  3. Follow least privilege principle
  4. Keep services isolated
  5. Regularly update dependencies

Adding MCP Servers to LibreChat with Supergateway

This guide provides step-by-step instructions for adding MCP servers to LibreChat using Supergateway as a bridge.

Overview

Supergateway allows you to run stdio-based MCP servers over SSE (Server-Sent Events), making it ideal for integrating MCP servers with LibreChat in a Docker environment.

Prerequisites

  • A running LibreChat installation
  • Docker and Docker Compose
  • The MCP server package you want to integrate

Implementation Steps

1. Create Server Directory

Create a directory for your MCP server:

mkdir mcp-server-name

2. Create Dockerfile

Create mcp-server-name/Dockerfile:

FROM node:18

WORKDIR /app

# Install both supergateway and your MCP server package
RUN npm install -g supergateway @organization/mcp-server-package

# Run supergateway as a bridge between your stdio MCP server and SSE
CMD ["npx", "-y", "supergateway", "--stdio", "npx -y @organization/mcp-server-package", "--port", "8002"]

3. Update docker-compose.override.yml

Add your MCP server service:

services:
  mcp-server-name:
    build:
      context: ./mcp-server-name
    ports:
      - "8002:8002"  # Adjust port as needed
    networks:
      - librechat_default
    environment:
      - API_KEY=${YOUR_API_KEY}  # If your server needs API keys
    volumes:
      - ./mcp-server-name:/app  # If your server needs access to local files

4. Update librechat.yaml

Add your MCP server configuration:

mcpServers:
  server-name:
    type: sse
    url: "http://mcp-server-name:8002/sse"

Understanding the Architecture

  • Your MCP server communicates via stdio.
  • Supergateway acts as a bridge, converting stdio to SSE.
  • LibreChat connects to the SSE endpoint exposed by Supergateway.
  • All services run on the librechat_default Docker network and can communicate using service names as hostnames.
  • Only necessary ports are exposed externally.

Common Configurations

Basic MCP Server

mcpServers:
  basic-server:
    type: sse
    url: "http://basic-server:8002/sse"

MCP Server with API Key

# docker-compose.override.yml
services:
  api-server:
    environment:
      - API_KEY=${API_KEY}

# librechat.yaml
mcpServers:
  api-server:
    type: sse
    url: "http://api-server:8002/sse"

MCP Server with File Access

# docker-compose.override.yml
services:
  file-server:
    volumes:
      - ./data:/app/data

# librechat.yaml
mcpServers:
  file-server:
    type: sse
    url: "http://file-server:8002/sse"

Troubleshooting

  • Verify network configuration if connection issues occur.
  • Check container logs with docker compose logs mcp-server-name.
  • Ensure ports are not conflicting.
  • Verify package installation in Dockerfile and environment variables.
  • Review server logs for errors.
  • Confirm service names match in all configurations.
  • Check network connectivity between containers.
  • Make sure SSE endpoint URL is correct.

Best Practices

  • Never commit API keys or sensitive data; use environment variables for secrets.
  • Limit container permissions and expose only necessary ports.
  • Use internal Docker networking when possible and follow least privilege principle.
  • Keep configurations modular and document environment variables.
  • Use version control for configuration files.
  • Log important events, monitor resource usage, and configure health checks.

Example: Complete Setup

Directory Structure

librechat/
├── mcp-server/
│   └── Dockerfile
├── docker-compose.override.yml
└── librechat.yaml

Dockerfile

FROM node:18
WORKDIR /app
RUN npm install -g supergateway @org/mcp-server
CMD ["npx", "-y", "supergateway", "--stdio", "npx -y @org/mcp-server", "--port", "8002"]

docker-compose.override.yml

services:
  mcp-server:
    build:
      context: ./mcp-server
    ports:
      - "8002:8002"
    networks:
      - librechat_default
    environment:
      - API_KEY=${MCP_API_KEY}

librechat.yaml

mcpServers:
  mcp-server:
    type: sse
    url: "http://mcp-server:8002/sse"

References