📌Overview

Purpose: The MCP Gateway is designed to enable HTTP+SSE capable clients to interact with MCP servers running on remote machines, facilitating multi-instance and cross-server communication.

Overview: MCP Gateway functions as a flexible gateway server that connects Model Context Protocol (MCP) STDIO servers to HTTP+SSE and REST APIs, allowing seamless access to multiple MCP server instances over HTTP. This enhances the deployment capabilities for MCP servers in various environments, such as containerized systems.

Key Features:

Multi-instance Support: Run and manage multiple instances of the same MCP server type, allowing for better resource utilization and isolation.
REST API Integration: Provides a REST API interface, enabling integration with any HTTP client and supporting OpenAPI/Swagger specifications for ease of use.
Session Management: Automatically manages sessions for users, ensuring a clean separation of server instances using unique session IDs and automatic resource cleanup on disconnection.
YAML Configuration: Simple configuration via YAML allows for flexible setup of multiple server types, authentication methods, and network settings.
Authentication Options: Supports both Basic and Bearer token authentication methods to secure access to the gateway.

MCP Gateway

A flexible gateway server that bridges Model Context Protocol (MCP) STDIO servers to MCP HTTP+SSE and REST API, enabling multi-instance MCP servers to be exposed over HTTP.

Features

Run multiple instances of the same MCP server type
Configure multiple different MCP server types
Flexible network binding configuration
Clean separation between server instances using session IDs
Automatic cleanup of server resources on connection close
YAML-based configuration
Optional Basic and Bearer token authentication
Configurable debug logging levels
REST API Support

REST API Support

MCP Gateway provides a REST API interface to MCP servers, accessible to any HTTP client that supports OpenAPI/Swagger specifications. This is useful for integrating with OpenAI's custom GPTs and other REST API clients.

REST API Endpoints

To make tool calls, first get a session ID:

curl "http://localhost:3000/api/sessionid"
# Returns: {"sessionId": "<generated-id>"}

Each tool exposed by an MCP server is available at:

POST /api/{serverName}/{toolName}?sessionId={session-id}

The sessionId query parameter is required for all tool calls.

Example calling the directory_tree tool on a filesystem MCP server:

# Get a session ID
SESSION_ID=$(curl -s "http://localhost:3000/api/sessionid" | jq -r .sessionId)

# Make the tool call
curl -X POST "http://localhost:3000/api/filesystem/directory_tree?sessionId=$SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"path": "/some/path"}'

OpenAPI Schema Generation

Generate OpenAPI schemas for all configured tools to integrate with OpenAPI-compatible clients:

# Generate YAML format (default)
npm start -- --schemaDump

# Generate JSON format
npm start -- --schemaDump --schemaFormat json

The generated schema includes:

All available endpoints for each configured server
Tool descriptions and parameter schemas
Request/response formats
Authentication requirements

Purpose

Most MCP servers are designed for local execution. MCP Gateway enables HTTP+SSE capable clients to interact with MCP servers running on remote machines. This supports deployment scenarios such as running LibreChat in containerized environments where some MCP servers may have limited functionality. MCP Gateway allows distributing MCP servers across multiple machines while maintaining seamless connectivity.

Security Features

MCP Gateway supports two authentication methods, which can be enabled independently or together:

Basic Authentication: Username/password pairs
Bearer Token Authentication: Token-based authentication

Any valid authentication grants access.

Authentication Configuration

Add authentication settings to your config.yaml:

auth:
  basic:
    enabled: true
    credentials:
      - username: "admin"
        password: "your-secure-password"
  bearer:
    enabled: true
    tokens:
      - "your-secure-token"

Using Authentication

Basic Authentication

curl -u username:password http://localhost:3000/serverName

Bearer Token Authentication

curl -H "Authorization: Bearer your-secure-token" http://localhost:3000/serverName

Installation

npm install

Configuration

The gateway uses a YAML configuration file (config.yaml by default). To specify a different path, use the CONFIG_PATH environment variable.

Debug Configuration

Logging is managed by Winston, with multiple log levels:

debug:
  level: "info"  # Options: error, warn, info, debug, verbose

Log level descriptions:

error: Show errors only
warn: Show warnings and errors
info: Show general info, warnings, and errors (default)
debug: Show debug info and above
verbose: Show all logs

Logs include timestamps and are color-coded in terminals.

Example log output:

2024-01-20T10:15:30.123Z [INFO]: New SSE connection for filesystem
2024-01-20T10:15:30.124Z [DEBUG]: Server instance created with sessionId: /filesystem?sessionId=abc123
2024-01-20T10:15:30.125Z [VERBOSE]: STDIO message received: {"type":"ready"}

Basic Configuration Example

hostname: "0.0.0.0"  # Listen on all interfaces
port: 3000

servers:
  filesystem:
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - "/path/to/root"
  
  git:
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-git"

Network Configuration Examples

Listen on localhost only (development):

hostname: "127.0.0.1"
port: 3000

Listen on a specific interface:

hostname: "192.168.1.100"
port: 3000

Listen on all interfaces (default):

hostname: "0.0.0.0"
port: 3000

Server Configuration

Each server in the servers section requires:

command: Command to run the server
args: List of arguments for the command
path (optional): Working directory

Example:

servers:
  myserver:
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-mytype"
      - "--some-option"

Complete Configuration Example

hostname: "0.0.0.0"
port: 3000

auth:
  basic:
    enabled: true
    credentials:
      - username: "admin"
        password: "your-secure-password"
  bearer:
    enabled: true
    tokens:
      - "your-secure-token"

servers:
  filesystem:
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - "/path/to/root"

Running the Gateway

Start with default config:

npm start

Start with custom config:

CONFIG_PATH=/path/to/my/config.yaml npm start

Adding New Server Types

Install the desired MCP server package.
Add it to the servers section of your config:

servers:
  mynewserver:
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-newtype"

Architecture

The gateway creates unique sessions for each server instance, allowing multiple clients to use the same server type independently. Each session maintains:

STDIO connection to the MCP server
SSE connection to the client
Message bridging between transports

Resources are automatically cleaned up when clients disconnect.

Environment Variables

CONFIG_PATH: Path to the YAML configuration file (default: ./config.yaml)

Contributing

Issues and PRs are welcome. Please be patient with response times.

License

MIT License

Example curl for calling the filesystem directory_tree tool with a session ID:

curl -X POST "http://localhost:3000/api/filesystem/directory_tree?sessionId=randomSession12345" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/home/aaron/Clara"
  }'

mcp-gateway