English | 简体中文

MCP Gateway

MCP Gateway is a lightweight Model Context Protocol gateway that exposes one small MCP entry point for multiple downstream MCP services.

Instead of flattening every downstream tool into the client at startup, the gateway exposes a fixed discovery and routing API. Agents can list services, inspect tools for one service, fetch one schema, and then forward the actual tool call.

Features

• One MCP entry point for multiple downstream MCP services.
• Token-efficient discovery through a small fixed gateway tool surface.
• Stdio and Streamable HTTP downstream transports.
• Optional inbound Streamable HTTP endpoint enabled by CLI flags.
• Hot reload for service-pool config changes.
• Stops removed, disabled, or replaced downstream services during reload.
• Restarts failed downstream processes up to three times before marking them unavailable.
• Atomic config reload that keeps the previous valid config when a new config is invalid.
• Optional newline-delimited JSON file logging that never writes operational logs to MCP stdout.
• Version reporting through --version or -v.

Why Use It

• Keep agent-side MCP configuration small: every agent connects to the gateway, while downstream services are managed in one config file.
• Reduce initial tool context: agents discover only the service, tool, and schema needed for the current task.
• Keep service lifecycle control centralized instead of duplicating command paths, environment variables, and secrets across multiple clients.

Quick Start

Install globally:

npm install -g @jadchene/mcp-gateway-service

Create a local config:

cp config.example.json config.json

Start the stdio gateway:

mcp-gateway-service --config ./config.json

Start with inbound Streamable HTTP:

mcp-gateway-service --config ./config.json --http --host 127.0.0.1 --port 3100 --path /mcp

Use stateless JSON responses for HTTP clients that expect direct JSON-RPC responses from POST:

mcp-gateway-service --config ./config.json --http --port 3100 --path /mcp --json-response

Check the installed version:

mcp-gateway-service --version
mcp-gateway-service -v

Configuration

Pass the config file by CLI argument:

mcp-gateway-service --config ./config.json

Or by environment variable:

MCP_GATEWAY_CONFIG=./config.json mcp-gateway-service

If neither is provided, the service tries config.json in the current working directory.

Config example:

{
  "logging": {
    "enable": false,
    "path": "./logs/mcp-gateway.log"
  },
  "services": [
    {
      "serviceId": "demo-echo",
      "enable": true,
      "name": "Demo Echo Service",
      "description": "Sample echo MCP service.",
      "transport": {
        "type": "stdio",
        "command": "node",
        "args": [
          "--experimental-strip-types",
          "examples/echo-service.ts"
        ]
      }
    },
    {
      "serviceId": "remote-http",
      "enable": false,
      "name": "Remote Streamable HTTP Service",
      "description": "Example downstream MCP service over Streamable HTTP.",
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:3200/mcp",
        "headers": {
          "Authorization": "Bearer ${MCP_TOKEN}"
        },
        "enableJsonResponse": false
      }
    }
  ]
}

Configuration notes:

• logging.enable defaults to false.
• logging.path is required only when logging.enable is true.
• Relative logging.path values are resolved from the config file directory.
• Service enable defaults to true; setting it to false skips that service.
• cwd and env are optional for stdio services.
• Stdio transport.framing may be line or content-length. When omitted, the gateway tries line and then content-length.
• HTTP downstream services use transport.type: "http" and transport.url.
• HTTP transport.headers provides static request headers.
• HTTP transport.enableJsonResponse enables stateless JSON response mode for that downstream service.

Inbound Streamable HTTP

Inbound HTTP is enabled only with --http. Passing --host, --port, --path, or --json-response without --http does not start an HTTP listener.

The HTTP endpoint uses the same path for GET and POST:

• GET /mcp opens the SSE read channel and returns the session in the Mcp-Session-Id response header.
• POST /mcp sends JSON-RPC messages. New clients should bind the session through the Mcp-Session-Id request header.
• Query-string sessionId is accepted for compatibility.
• The endpoint SSE event advertises the single path, such as /mcp.

Gateway Tools

The gateway exposes six public tools:

Tool	Purpose
gateway_list_services	List all downstream MCP services managed by the gateway, including each serviceId, description, and availability.
gateway_get_service	Return one service summary, runtime state, recent errors, and cached metadata. Use this for diagnostics.
gateway_list_tools	List tools exposed by one downstream service. Optional toolName filters by one or more name fragments.
gateway_get_tool_schema	Return the input and output schema for one downstream tool.
gateway_manage_service	Reconnect a service or persistently enable/disable it in the config file.
gateway_call_tool	Call one downstream tool through the gateway and return the downstream MCP result.

Default token-efficient workflow:

1. Call gateway_list_services once.
2. Call gateway_list_tools(serviceId) only when a service is needed. Use toolName to filter large tool lists by name.
3. Call gateway_get_tool_schema(serviceId, toolName) before first use of a tool.
4. Call gateway_call_tool to execute the downstream tool.
5. Use gateway_get_service only for diagnostics.
6. Use gateway_manage_service only to reconnect, enable, or disable a service.

gateway_manage_service actions:

• reconnect: retry the current downstream lifecycle without modifying config.
• enable: persist enable: true for the service and reload config.
• disable: persist enable: false for the service and reload config.

Skill Integration

This repository includes a public gateway skill:

• Skill path: skills/mcp-gateway/SKILL.md

Use it when your agent supports skills. It keeps discovery token-efficient and routes downstream calls through the minimal gateway contract.

MCP Client Configuration

Codex:

[mcp_servers.gateway]
command = "mcp-gateway-service"
args = ["--config", "./config.json"]

Gemini CLI:

{
  "mcpServers": {
    "gateway": {
      "type": "stdio",
      "command": "mcp-gateway-service",
      "args": ["--config", "./config.json"]
    }
  }
}

Claude Code:

{
  "mcpServers": {
    "gateway": {
      "type": "stdio",
      "command": "mcp-gateway-service",
      "args": ["--config", "./config.json"]
    }
  }
}

Streamable HTTP mode:

Start one shared HTTP gateway process first:

mcp-gateway-service --config ./config.json --http --host 127.0.0.1 --port 3100 --path /mcp

Then point MCP clients at the HTTP endpoint.

Codex:

[mcp_servers.gateway]
url = "http://127.0.0.1:3100/mcp"

Gemini CLI:

{
  "mcpServers": {
    "gateway": {
      "httpUrl": "http://127.0.0.1:3100/mcp"
    }
  }
}

Claude Code:

{
  "mcpServers": {
    "gateway": {
      "type": "http",
      "url": "http://127.0.0.1:3100/mcp"
    }
  }
}

Use the same URL for every client that should share the gateway service pool. Use --json-response only when your HTTP client expects stateless JSON-RPC responses directly from POST requests.

Development

npm install
npm run dev

Build and test:

npm run build
npm test

Run the built server:

node dist/index.js --config ./config.json

License

MIT. See LICENSE.