Content
# 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:
```bash
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:
```bash
# 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:
```bash
# 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](https://github.com/LibreChat/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`:
```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
```bash
curl -u username:password http://localhost:3000/serverName
```
#### Bearer Token Authentication
```bash
curl -H "Authorization: Bearer your-secure-token" http://localhost:3000/serverName
```
## Installation
```bash
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](https://github.com/winstonjs/winston) for logging, providing rich formatting and multiple log levels:
```yaml
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
```yaml
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)
```yaml
hostname: "127.0.0.1"
port: 3000
```
#### Listen on a specific interface
```yaml
hostname: "192.168.1.100"
port: 3000
```
#### Listen on all interfaces (default)
```yaml
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:
```yaml
servers:
myserver:
command: npx
args:
- -y
- "@modelcontextprotocol/server-mytype"
- "--some-option"
```
### Complete Configuration Example
```yaml
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:
```bash
npm start
```
With custom config:
```bash
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:
```yaml
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"
}'
