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 I am tiing together.

• This is the think that gives any kind of tool to the Agent. Model Context Protocol Specification
• Converts stdio MCP servers to SSE and each server can run in its own container. I will see how this scales 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 any MCP server 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

1. A running LibreChat installation
2. Docker and Docker Compose
3. 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

# The command runs supergateway as a bridge between your stdio MCP server and SSE
# --stdio: The command to run your MCP server
# --port: The port supergateway will listen on
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

1. Stdio to SSE Bridge:

   • Your MCP server communicates via stdio
   • Supergateway acts as a bridge, converting stdio to SSE
   • LibreChat connects to the SSE endpoint

2. Docker Networking:

   • All services run on the librechat_default network
   • Services can communicate using their service names as hostnames
   • Only necessary ports are exposed

3. Configuration Flow:

   • LibreChat reads mcpServers config from librechat.yaml
   • Connects to Supergateway's SSE endpoint
   • Supergateway forwards requests to your MCP server

Common Configurations

1. Basic MCP Server

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

2. 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"

3. 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

1. Connection Issues:

   • Verify network configuration
   • Check container logs: docker compose logs mcp-server-name
   • Ensure ports are not conflicting

2. Server Not Starting:

   • Verify package installation in Dockerfile
   • Check for environment variables
   • Review server logs

3. Communication Problems:

   • Verify service names match in all configurations
   • Check network connectivity between containers
   • Ensure SSE endpoint is correct

Best Practices

1. Security:

   • Never commit API keys or sensitive data
   • Use environment variables for secrets
   • Limit container permissions

2. Networking:

   • Only expose necessary ports
   • Use internal Docker networking when possible
   • Follow least privilege principle

3. Configuration:

   • Keep configurations modular
   • Document environment variables
   • Use version control for configurations

4. Monitoring:

   • Log important events
   • Monitor resource usage
   • Set up health checks

Example: Complete Setup

Here's a complete example of adding a new MCP server:

1. Directory Structure:

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

2. 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"]

3. docker-compose.override.yml:

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

4. librechat.yaml:

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

References

• Model Context Protocol Specification
• Supergateway Documentation
• LibreChat Documentation