English | 简体中文

MCP Gateway

Introduction

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

The project uses the official TypeScript SDK v2 and requires Node.js 24 or later.

Related MCP server: MCP Gateway (Parent MCP Server)

Why Use It

• Keep the agent context small even when many MCP services are configured.

• Connect the agent once, then add or remove downstream services in the gateway config.

• Find tools by name or description and load schemas only when required.

• Use stdio and Streamable HTTP services through the same interface.

• Require user confirmation for selected tool-name patterns, or hide and block matching tools entirely.

• Reload config changes without restarting the gateway.

Quick Start

Install

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

Create config.json. Replace your-mcp-service with the command of an installed MCP server:

{
  "services": [
    {
      "serviceId": "tools",
      "name": "Tools",
      "transport": {
        "type": "stdio",
        "command": "your-mcp-service"
      }
    }
  ]
}

Stdio

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

Codex config.toml:

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

Claude Code:

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

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 config.toml:

[mcp_servers.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"
  },
  "services": [
    {
      "serviceId": "local-tools",
      "name": "Local Tools",
      "confirmationRequiredTools": ["delete_*", "deploy_?"],
      "disabledTools": ["internal_*", "legacy_tool"],
      "transport": {
        "type": "stdio",
        "command": "your-mcp-service",
        "args": []
      }
    },
    {
      "serviceId": "remote-tools",
      "name": "Remote Tools",
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:3200/mcp"
      }
    }
  ]
}

The config file is watched for changes. Invalid updates are rejected and the last valid config stays active. See config.example.json for another example.

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.

gateway_list_services accepts optional serviceId and desc string arrays as case-insensitive substring filters. Matches across these two fields use OR. The optional available boolean further limits those matches by current availability.

Calls keep the downstream tool's original side effects and confirmation rules. Tools matching confirmationRequiredTools are never invoked until the current MCP session reviews the exact service, tool, and arguments and answers yes to the form elicitation; sessions without form elicitation support receive an error. A no, decline, or cancel returns an explicit rejection without invoking the downstream tool. An uncertain gateway_call_tool failure is never replayed automatically. Enabling or disabling a service with gateway_manage_service atomically updates the config file.

disabledTools takes precedence over confirmationRequiredTools when both match. A disabled tool is hidden and rejected immediately without asking for confirmation.

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
npm run dev -- --config ./config.json

Build and run the compiled service:

npm run build
npm start -- --config ./config.json

License

MIT