📌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

MCP Gateway is a flexible 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 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, making them accessible to any HTTP client that supports OpenAPI/Swagger specifications.

REST API Endpoints

To get a session ID:

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

To call a tool on a MCP server:

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

# Then 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

The gateway can generate OpenAPI schemas for all configured tools:

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

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

Purpose

MCP Gateway enables HTTP+SSE capable clients to interact with MCP servers running on remote machines, addressing deployment scenarios such as running in containerized environments.

Security Features

MCP Gateway supports two independent authentication methods:

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

Both methods can be enabled simultaneously.

Authentication Configuration

Add 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 is configured using a YAML file, typically config.yaml. The CONFIG_PATH environment variable can specify a different path.

Debug Configuration

Configure logging using Winston:

debug:
  level: "info"  # Possible values: "error", "warn", "info", "debug", "verbose"

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"

Running the Gateway

Start the gateway:

npm start

With custom config:

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

Adding New Server Types

Install the MCP server package you want to use
Update the servers section in your config:

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

Architecture

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

Environment Variables

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

Contributing

Issues and PRs are welcome.

License

MIT License

mcp-gateway