English | 简体中文

MCP Gateway

Introduction

MCP Gateway puts multiple MCP services behind one endpoint. An agent connects to the gateway and sees up to six routing tools; downstream services, tools, and schemas are looked up only when they are needed.

Supports stdio and Streamable HTTP with MCP 2026-07-28, 2025-11-25, and 2025-06-18. Legacy /sse endpoints are unsupported.

Related MCP server: mcpstead

Quick Start

Install

Requires Node.js 24 or later.

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

Create config.json using the configuration example. Replace the downstream command, arguments, and paths with those of an installed MCP server.

Stdio

The agent starts the gateway process, so no separate startup command is needed.

Codex:

codex mcp add gateway -- mcp-gateway-service --config /absolute/path/config.json

Claude Code:

claude mcp add gateway -- mcp-gateway-service --config /absolute/path/config.json

Replace /absolute/path/config.json with the file you created. On Windows, a path such as C:/mcp/gateway/config.json works. Absolute paths avoid depending on the client's working directory.

Streamable HTTP

Start the gateway:

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

The default endpoint is http://127.0.0.1:3000/mcp. HTTP hides gateway_manage_service by default. Non-loopback binds require a bearer token in MCP_GATEWAY_AUTH_TOKEN.

Codex:

codex mcp add gateway --url http://127.0.0.1:3000/mcp

Claude Code:

claude mcp add --transport http gateway http://127.0.0.1:3000/mcp

Configuration and Tools

CLI Options

Stdio remains available when --http is enabled.

Config File

{
  "logging": {
    "enable": false,
    "path": "./logs/mcp-gateway.log",
    "maxBytes": 10485760
  },
  "services": [
    {
      "serviceId": "local-tools",
      "enable": true,
      "name": "Local Tools",
      "description": "Local MCP service",
      "callTimeoutMs": 120000,
      "confirmationRequiredTools": ["delete_*", "deploy_?"],
      "codexAutoReview": false,
      "disabledTools": ["internal_*", "legacy_tool"],
      "transport": {
        "type": "stdio",
        "command": "your-mcp-service",
        "args": ["--config", "/absolute/path/service/config.json"],
        "cwd": "/absolute/path/service",
        "env": {},
        "inheritEnv": false,
        "envAllowlist": []
      }
    },
    {
      "serviceId": "remote-tools",
      "enable": false,
      "name": "Remote Tools",
      "description": "Remote MCP service",
      "callTimeoutMs": 120000,
      "confirmationRequiredTools": [],
      "codexAutoReview": false,
      "disabledTools": [],
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:3200/mcp",
        "headers": {
          "Authorization": "Bearer replace-with-token"
        }
      }
    }
  ]
}

Configure and enable the services you use. Remove Authorization for an HTTP service without token authentication.

Configuration reloads automatically; invalid updates keep the last valid configuration. The complete example is also available in config.example.json.

Gateway Tools

The usual flow is gateway_list_services → gateway_list_tools → gateway_get_tool_schema when needed → gateway_call_tool. Pass {} to gateway_call_tool when the downstream tool has no arguments.

Confirmations show the service, tool, and arguments and require a client with interactive confirmation support. Calls with uncertain outcomes are not retried automatically.

For Codex automatic review, set "codexAutoReview": true in the selected services[] block and start Codex with codex -c approvals_reviewer=auto_review. This applies to gateway confirmations; configure downstream services' own approvals separately. Otherwise, use Accept / Decline / Cancel. Codex policy determines whether an operation is approved.

Agents with Skills support can use the included MCP Gateway Skill for the discovery and calling workflow.

Development

git clone https://github.com/jadchene/mcp-gateway.git
cd mcp-gateway
npm install
npm run verify

Create config.json as shown above, then start the development service:

npm run dev -- --config ./config.json

npm run verify builds the service. Run the compiled output with npm start -- --config ./config.json.

License

MIT