Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/acehoss--mcp-gateway/badge.svg)](/listings/acehoss--mcp-gateway)

HTML

<a href="/listings/acehoss--mcp-gateway"><img src="/api/listings/acehoss--mcp-gateway/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 281 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP Gateway
  2. 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.
  3. ## Features
  4. - Run multiple instances of the same MCP server type
  5. - Configure multiple different MCP server types
  6. - Flexible network binding configuration
  7. - Clean separation between server instances using session IDs
  8. - Automatic cleanup of server resources on connection close
  9. - YAML-based configuration
  10. - Optional Basic and Bearer token authentication
  11. - Configurable debug logging levels
  12. - REST API Support
  13. ## REST API Support
  14. 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.
  15. ### REST API Endpoints
  16. Before making tool calls, you need to get a session ID:
  17. ```bash
  18. curl "http://localhost:3000/api/sessionid"
  19. # Returns: {"sessionId": "<generated-id>"}
  20. ```
  21. Each tool exposed by an MCP server is available at:
  22. ```
  23. POST /api/{serverName}/{toolName}?sessionId={session-id}
  24. ```
  25. Note: The `sessionId` query parameter is required for all tool calls.
  26. For example, to call the `directory_tree` tool on a `filesystem` MCP server:
  27. ```bash
  28. # First get a session ID
  29. SESSION_ID=$(curl -s "http://localhost:3000/api/sessionid" | jq -r .sessionId)
  30. # Then make the tool call
  31. curl -X POST "http://localhost:3000/api/filesystem/directory_tree?sessionId=$SESSION_ID" \
  32. -H "Content-Type: application/json" \
  33. -d '{"path": "/some/path"}'
  34. ```
  35. ### OpenAPI Schema Generation
  36. The gateway can generate OpenAPI schemas for all configured tools, making it easy to integrate with OpenAPI-compatible clients:
  37. ```bash
  38. # Generate YAML format (default)
  39. npm start -- --schemaDump
  40. # Generate JSON format
  41. npm start -- --schemaDump --schemaFormat json
  42. ```
  43. The generated schema includes:
  44. - All available endpoints for each configured server
  45. - Tool descriptions and parameter schemas
  46. - Request/response formats
  47. - Authentication requirements
  48. ## Purpose
  49. 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.
  50. ## Security Features
  51. MCP Gateway supports two authentication methods that can be enabled independently:
  52. 1. Basic Authentication: Username/password pairs
  53. 2. Bearer Token Authentication: Token-based authentication
  54. Both methods can be enabled simultaneously, and any valid authentication will grant access.
  55. ### Authentication Configuration
  56. Add authentication settings to your `config.yaml`:
  57. ```yaml
  58. auth:
  59. basic:
  60. enabled: true
  61. credentials:
  62. - username: "admin"
  63. password: "your-secure-password"
  64. # Add more username/password pairs as needed
  65. bearer:
  66. enabled: true
  67. tokens:
  68. - "your-secure-token"
  69. # Add more tokens as needed
  70. ```
  71. ### Using Authentication
  72. #### Basic Authentication
  73. ```bash
  74. curl -u username:password http://localhost:3000/serverName
  75. ```
  76. #### Bearer Token Authentication
  77. ```bash
  78. curl -H "Authorization: Bearer your-secure-token" http://localhost:3000/serverName
  79. ```
  80. ## Installation
  81. ```bash
  82. npm install
  83. ```
  84. ## Configuration
  85. 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.
  86. ### Debug Configuration
  87. The gateway uses [Winston](https://github.com/winstonjs/winston) for logging, providing rich formatting and multiple log levels:
  88. ```yaml
  89. debug:
  90. level: "info" # Possible values: "error", "warn", "info", "debug", "verbose"
  91. ```
  92. Log levels, from least to most verbose:
  93. - `error`: Only show errors
  94. - `warn`: Show warnings and errors
  95. - `info`: Show general information, warnings, and errors (default)
  96. - `debug`: Show debug information and all above
  97. - `verbose`: Show all possible logging information
  98. The logs include timestamps and are color-coded by level when viewing in a terminal. Additional metadata is included as JSON when relevant.
  99. Example log output:
  100. ```
  101. 2024-01-20T10:15:30.123Z [INFO]: New SSE connection for filesystem
  102. 2024-01-20T10:15:30.124Z [DEBUG]: Server instance created with sessionId: /filesystem?sessionId=abc123
  103. 2024-01-20T10:15:30.125Z [VERBOSE]: STDIO message received: {"type":"ready"}
  104. ```
  105. ### Basic Configuration Example
  106. ```yaml
  107. hostname: "0.0.0.0" # Listen on all interfaces
  108. port: 3000
  109. servers:
  110. filesystem:
  111. command: npx
  112. args:
  113. - -y
  114. - "@modelcontextprotocol/server-filesystem"
  115. - "/path/to/root"
  116. git:
  117. command: npx
  118. args:
  119. - -y
  120. - "@modelcontextprotocol/server-git"
  121. ```
  122. ### Network Configuration Examples
  123. #### Listen on localhost only (development)
  124. ```yaml
  125. hostname: "127.0.0.1"
  126. port: 3000
  127. ```
  128. #### Listen on a specific interface
  129. ```yaml
  130. hostname: "192.168.1.100"
  131. port: 3000
  132. ```
  133. #### Listen on all interfaces (default)
  134. ```yaml
  135. hostname: "0.0.0.0"
  136. port: 3000
  137. ```
  138. ### Server Configuration
  139. Each server in the `servers` section needs:
  140. - `command`: The command to run the server
  141. - `args`: List of arguments for the command
  142. - `path` (optional): Working directory for the server
  143. Example with all options:
  144. ```yaml
  145. servers:
  146. myserver:
  147. command: npx
  148. args:
  149. - -y
  150. - "@modelcontextprotocol/server-mytype"
  151. - "--some-option"
  152. ```
  153. ### Complete Configuration Example
  154. ```yaml
  155. hostname: "0.0.0.0"
  156. port: 3000
  157. # Authentication configuration (optional)
  158. auth:
  159. basic:
  160. enabled: true
  161. credentials:
  162. - username: "admin"
  163. password: "your-secure-password"
  164. bearer:
  165. enabled: true
  166. tokens:
  167. - "your-secure-token"
  168. servers:
  169. filesystem:
  170. command: npx
  171. args:
  172. - -y
  173. - "@modelcontextprotocol/server-filesystem"
  174. - "/path/to/root"
  175. ```
  176. ## Running the Gateway
  177. Standard start:
  178. ```bash
  179. npm start
  180. ```
  181. With custom config:
  182. ```bash
  183. CONFIG_PATH=/path/to/my/config.yaml npm start
  184. ```
  185. ## Adding New Server Types
  186. 1. Install the MCP server package you want to use
  187. 2. Add a new entry to the `servers` section in your config:
  188. ```yaml
  189. servers:
  190. mynewserver:
  191. command: npx
  192. args:
  193. - -y
  194. - "@modelcontextprotocol/server-newtype"
  195. # Add any server-specific arguments here
  196. ```
  197. ## Architecture
  198. 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:
  199. - STDIO connection to the actual MCP server
  200. - SSE connection to the client
  201. - Message bridging between the transports
  202. When a client disconnects, all associated resources are automatically cleaned up.
  203. ## Environment Variables
  204. - `CONFIG_PATH`: Path to the YAML configuration file (default: `./config.yaml`)
  205. ## Contributing
  206. Issues and PRs are welcome, but in all honesty they could languish a while.
  207. ## License
  208. MIT License
  209. curl -X POST "http://localhost:3000/api/filesystem/directory_tree?sessionId=randomSession12345" -H "Content-Type: application/json" -d '{
  210. "path": "/home/aaron/Clara"
  211. }'

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.