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.
- 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
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.
Before making tool calls, you need to 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}
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"}'
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
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.
MCP Gateway supports two authentication methods that can be enabled independently:
- Basic Authentication: Username/password pairs
- Bearer Token Authentication: Token-based authentication
Both methods can be enabled simultaneously, and any valid authentication will grant access.
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
curl -u username:password http://localhost:3000/serverName
curl -H "Authorization: Bearer your-secure-token" http://localhost:3000/serverName
npm install
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.
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 errorswarn
: Show warnings and errorsinfo
: Show general information, warnings, and errors (default)debug
: Show debug information and all aboveverbose
: 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"}
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"
hostname: "127.0.0.1"
port: 3000
hostname: "192.168.1.100"
port: 3000
hostname: "0.0.0.0"
port: 3000
Each server in the servers
section needs:
command
: The command to run the serverargs
: List of arguments for the commandpath
(optional): Working directory for the server
Example with all options:
servers:
myserver:
command: npx
args:
- -y
- "@modelcontextprotocol/server-mytype"
- "--some-option"
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"
Standard start:
npm start
With custom config:
CONFIG_PATH=/path/to/my/config.yaml npm start
- Install the MCP server package you want to use
- 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
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.
CONFIG_PATH
: Path to the YAML configuration file (default:./config.yaml
)
Issues and PRs are welcome, but in all honesty they could languish a while.
MIT License
curl -X POST "http://localhost:3000/api/filesystem/directory_tree?sessionId=randomSession12345" -H "Content-Type: application/json" -d '{ "path": "/home/aaron/Clara" }'