mcp-gateway

MCP Gateway acts as a bridge between STDIO MCP servers and HTTP-based clients. It can host multiple MCP server instances (of the same type or different types) and expose their tools via a REST API and SSE streams. Start the gateway with a configuration file (config.yaml by default) that defines which MCP server packages to run and how they should be instantiated. Clients first obtain a session ID from the gateway, then call specific tools exposed by each configured server using the session context. For example, you can request a session ID, then invoke a tool like directory_tree on a filesystem MCP server by POSTing to /api/filesystem/directory_tree with the sessionId as a query parameter and your tool inputs in the request body. The gateway also supports automatic resource cleanup when a client disconnects and can optionally enforce authentication (Basic or Bearer tokens) to protect access. OpenAPI/Swagger schemas can be generated to inspect available endpoints and their required parameters, making it easy to integrate with API clients or GPT-based tools.

Key capabilities include:

• Managing multiple server instances and types via a single gateway
• REST API access to MCP tools with per-session isolation
• OpenAPI schema generation for tooling discovery
• Optional Basic and Bearer token authentication
• YAML-based configuration and configurable debug logging
• Automatic session cleanup on disconnect

Prerequisites:

• Node.js (LTS version) and npm installed on your system
• A working YAML configuration file (config.yaml) or plan to supply CONFIG_PATH at runtime

1. Clone or install the MCP Gateway package

git clone https://github.com/acehoss/mcp-gateway.git
cd mcp-gateway
npm install

2. Create or edit the configuration file (config.yaml)

• Example structure is provided in the repository README. You can define servers to run (e.g., filesystem, git) and optional authentication settings.

hostname: "0.0.0.0"
port: 3000

servers:
  filesystem:
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - "/path/to/root"

  git:
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-git"
auth:
  basic:
    enabled: true
    credentials:
      - username: "admin"
        password: "your-secure-password"
  bearer:
    enabled: true
    tokens:
      - "your-secure-token"

3. Start the gateway

• With the default config path (config.yaml in the working directory):

npm start

• Or specify a custom config path:

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

4. Verify the server is running and accessible on the configured port (default 3000). You can fetch a session ID at /api/sessionid and then call tools via /api/{server}/{tool}?sessionId={session-id}.

Tips and common considerations:

• The gateway supports multiple servers and instances; each instance is isolated per session, enabling parallel usage by different clients.
• If you enable authentication, you must provide valid credentials or tokens for requests to succeed.
• Use the OpenAPI schema generation feature (npm start -- --schemaDump) to generate client-friendly schemas for all configured tools.
• Environment variable CONFIG_PATH can be used to point to a YAML config located outside the default directory.
• Ensure the underlying MCP server packages (e.g., @modelcontextprotocol/server-filesystem) are compatible with the gateway version and your Node.js runtime.
• When running behind a reverse proxy, forward headers and consider enabling TLS termination for secure HTTP endpoints.