Mcp 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 now provides a REST API interface to MCP servers, making them accessible to any HTTP client that supports OpenAPI/Swagger specifications. This feature is particularly useful for integrating with OpenAI's custom GPTs and other REST API clients.

REST API Endpoints

Before making tool calls, you need to get a session ID:

curl "http://localhost:3000/api/sessionid"
# Returns: {"sessionId": ""}

Each tool exposed by an MCP server is available at:

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

Note: The sessionId query parameter is required for all tool calls.

For example, to call the directory_tree tool on a filesystem 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, making it easy 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

At the moment, 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 addresses common deployment scenarios, such as running LibreChat in a containerized environment where certain MCP servers, like the Puppeteer server, may have limited functionality. MCP Gateway provides a robust solution for distributing MCP servers across multiple machines while maintaining seamless connectivity.

Security Features

MCP Gateway supports two authentication methods that can be enabled independently:

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

Both methods can be enabled simultaneously, and any valid authentication will grant access.

Authentication Configuration

Add authentication settings to your config.yaml:

auth:
  basic:
    enabled: true
    credentials:
      - username: "admin"
        password: "your-secure-password"
      # Add more username/password pairs as needed
  bearer:
    enabled: true
    tokens:
      - "your-secure-token"
      # Add more tokens as needed

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. By default, it looks for config.yaml in the current directory, but you can specify a different path using the CONFIG_PATH environment variable.

Debug Configuration

The gateway uses Winston for logging, providing rich formatting and multiple log levels:

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

Log levels, from least to most verbose:

• error: Only show errors
• warn: Show warnings and errors
• info: Show general information, warnings, and errors (default)
• debug: Show debug information and all above
• verbose: Show all possible logging information

The logs include timestamps and are color-coded by level when viewing in a terminal. Additional metadata is included as JSON when relevant.

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 needs:

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

Example with all options:

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

Complete Configuration Example

hostname: "0.0.0.0"
port: 3000

# Authentication configuration (optional)
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

Standard start:

npm start

With custom config:

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

Adding New Server Types

1. Install the MCP server package you want to use
2. Add a new entry to the servers section in your config:

servers:
  mynewserver:
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-newtype"
      # Add any server-specific arguments here

Architecture

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

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

When a client disconnects, all associated resources are automatically cleaned up.

Environment Variables

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

Contributing

Issues and PRs are welcome, but in all honesty they could languish a while.

License

MIT License

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: acehoss
• Source: acehoss/mcp-gateway
• License: MIT

Install and usage instructions live in the source repository linked above.