MCPGateway

MCP Gateway

[](LICENSE) [](https://nodejs.org/) [](https://www.typescriptlang.org/) [](#endpoints) [![LobeHub MCP listing badge][lobehub-mcp-badge]][lobehub-mcp-listing]

> Universal MCP aggregation server that routes 300+ tools from multiple MCP servers through a single endpoint with 15 layers of token optimization (95-98% reduction). Works with Claude Desktop, Claude Code, Cursor, OpenAI Codex, and VS Code Copilot.

Key Features

• Multi-Server Aggregation — Connect multiple MCP servers (STDIO, HTTP, SSE) through one gateway endpoint
• 15 Token Optimization Layers — Progressive disclosure, smart filtering, aggregations, code batching, delta responses, auto-summarization, and more
• Web Dashboard — Real-time UI to manage tools, backends, and server lifecycle with hot-reload
• Sandboxed Code Execution — Execute TypeScript/JavaScript in secure Node.js VM for batch operations
• Skills System — Save and reuse code patterns for zero-shot task execution
• Authentication — API Key and OAuth/JWT support with rate limiting
• Docker Ready — Easy deployment with Docker/Compose

Quick Install

git clone https://github.com/abdullah1854/MCPGateway.git
cd MCPGateway
npm install
cp config/servers.example.json config/servers.json
npm run dev

Connect Your AI Client

Claude Desktop / Cursor / VS Code Copilot — Add as remote MCP server:

http://localhost:3010/mcp

Claude Code — Add to settings:

{
  "mcpServers": {
    "mcp-gateway": {
      "type": "url",
      "url": "http://localhost:3010/mcp"
    }
  }
}

Dashboard: http://localhost:3010/dashboard

Best for: teams that want one MCP endpoint, a browser dashboard, and aggressive token savings when working across many tools.

[lobehub-mcp-badge]: https://lobehub.com/badge/mcp/abdullah1854-mcpgateway [lobehub-mcp-listing]: https://lobehub.com/mcp/abdullah1854-mcpgateway

Quick Links

• [Quick start](#quick-start)
• [Supported clients](#supported-mcp-clients)
• [Dashboard screenshots](#screenshots)
• [Backend configuration](#backend-server-configuration)
• [Security modes](#security-modes)
• [Examples](examples/)
• Issues & support

Quick Start in 3 Commands

npm install
cp config/servers.example.json config/servers.json
npm run dev

Then open http://localhost:3010/dashboard, connect your preferred client, and continue with the full [Quick Start](#quick-start) below for server configuration and production setup.

Supported MCP Clients

| Client | Support | Notes | |--------|---------|-------| | Claude Desktop | ✅ | Connect through the gateway's HTTP or SSE endpoints | | Claude Code | ✅ | Reduces context overhead for large tool catalogs | | Cursor | ✅ | Use one gateway to expose hundreds of backend tools | | OpenAI Codex | ✅ | Works with the gateway's standard MCP endpoints | | VS Code Copilot | ✅ | Centralizes MCP tooling across local and remote servers |

---

How MCP Gateway Complements Anthropic's Tool Search

> January 2025: Anthropic released Tool Search Tool - a native server-side feature for discovering tools from large catalogs using defer_loading and regex/BM25 search.

MCP Gateway and Anthropic's Tool Search solve different problems:

| Problem | Anthropic Tool Search | MCP Gateway | |---------|----------------------|-------------| | Tool Discovery (finding the right tool from 100s) | ✅ Native defer_loading + search | ✅ Progressive disclosure | | Result Filtering (trimming large results) | ❌ Not available | ✅ maxRows, fields, format | | Auto-Summarization (extracting insights) | ❌ Not available | ✅ 60-90% token savings | | Delta Responses (only send changes) | ❌ Not available | ✅ 90%+ savings for polling | | Aggregations (count, sum, groupBy) | ❌ Not available | ✅ Server-side analytics | | Code Batching (multiple ops in one call) | ❌ Not available | ✅ 60-80% fewer round-trips | | Skills (reusable code patterns) | ❌ Not available | ✅ 95%+ token savings |

Bottom line: Anthropic's Tool Search helps you find the right tool. MCP Gateway helps you use tools efficiently by managing large results, batching operations, and providing reusable patterns.

You can use both together - let Anthropic handle tool discovery while routing tool calls through MCP Gateway for result optimization.

---

Why MCP Gateway?

Problem: AI agents face three critical challenges when working with MCP servers:

1. Tool Overload - Loading 300+ tool definitions consumes 77,000+ context tokens before any work begins
2. Result Bloat - Large query results (10K rows) can consume 50,000+ tokens per call
3. Repetitive Operations - Same workflows require re-explaining to the model every time

> Note: Anthropic's Tool Search Tool now addresses #1 natively for direct API users. MCP Gateway remains essential for #2 and #3, and provides tool discovery for MCP clients that don't have native tool search.

Solution: MCP Gateway aggregates all your MCP servers and provides 15 layers of token optimization:

| Layer | What It Does | Token Savings | Unique to Gateway? | |-------|--------------|---------------|:------------------:| | Progressive Disclosure | Load tool schemas on-demand | 85% | Shared* | | Smart Filtering | Auto-limit result sizes | 60-80% | ✅ | | Aggregations | Server-side analytics | 90%+ | ✅ | | Code Batching | Multiple ops in one call | 60-80% | ✅ | | Skills | Zero-shot task execution | 95%+ | ✅ | | Caching | Skip repeated queries | 100% | ✅ | | PII Tokenization | Redact sensitive data | Security | ✅ | | Response Optimization | Strip null/empty values | 20-40% | ✅ | | Session Context | Avoid resending data in context | Very High | ✅ | | Schema Deduplication | Reference identical schemas by hash | Up to 90% | ✅ | | Micro-Schema Mode | Ultra-compact type abbreviations | 60-70% | ✅ | | Delta Responses | Send only changes for repeated queries | 90%+ | ✅ | | Context Tracking | Monitor context usage, prevent overflow | Safety | ✅ | | Auto-Summarization | Extract insights from large results | 60-90% | ✅ | | Query Planning | Detect optimization opportunities | 30-50% | ✅ |

\Anthropic's Tool Search provides native tool discovery; MCP Gateway provides it for MCP clients without native support.*

Result: A typical session drops from ~500,000 tokens to ~25,000 tokens (95% reduction).

305 Tools Through 19 Gateway Tools

Cursor connected to MCP Gateway - 19 tools provide access to 305 backend tools across 16 servers

Minimal Context Usage

Claude Code /context view - Only 8.9k tokens (4.5%) for all MCP tools instead of 200k+ for raw definitions

What's New (v1.0.0)

• Gateway MCP Tools - All code execution features now exposed as MCP tools (gateway_*) that any client can discover and use directly
• Hot-Reload Server Management - Add, edit, and delete MCP servers from the dashboard without restarting
• UI State Persistence - Disabled tools and backends are remembered across server restarts
• Enhanced Dashboard - Reconnect failed backends, view real-time status, improved error handling
• Connection Testing - Test server connections before adding them to your configuration
• Export/Import Config - Backup and share your server configurations easily
• Parallel Tool Execution - Execute multiple tool calls simultaneously for better performance
• Result Filtering & Aggregation - Reduce context bloat with maxRows, fields, format, and aggregation options

Features

Core Gateway Features

• 🔀 Multi-Server Aggregation - Route multiple MCP servers through one gateway
• 🎛️ Web Dashboard - Real-time UI to manage tools, backends, and server lifecycle
• ➕ Hot-Reload Server Management - Add, edit, delete MCP servers from dashboard without restart
• 🌐 HTTP Streamable Transport - Primary transport, works with all clients
• 📡 SSE Transport - Backward compatibility for older clients
• 🔐 Authentication - API Key and OAuth/JWT support
• ⚡ Rate Limiting - Protect your backend servers
• 🐳 Docker Ready - Easy deployment with Docker/Compose
• 📊 Health Checks - Monitor backend status with detailed diagnostics
• 🔄 Auto-Restart - Server restarts automatically on crash or via dashboard
• 💾 UI State Persistence - Remembers disabled tools/backends across restarts

Code Execution Mode (Token-Efficient AI)

Inspired by Anthropic's Code Execution with MCP - achieve up to 98.7% token reduction:

• 🔍 Progressive Tool Disclosure - Search and lazy-load tools to reduce token usage (85% reduction)
• 💻 Sandboxed Code Execution - Execute TypeScript/JavaScript in secure Node.js VM
• 📉 Context-Efficient Results - Filter, aggregate, and transform tool results (60-80% reduction)
• 🔒 Privacy-Preserving Operations - PII tokenization for sensitive data
• 📁 Skills System - Save and reuse code patterns for zero-shot execution (eliminates prompt tokens)
• 🗄️ State Persistence - Workspace for agent state across sessions
• 🛠️ Gateway MCP Tools - All code execution features exposed as MCP tools for any client
• 🧹 Response Optimization - Automatically strip null/empty values from responses (20-40% reduction)
• 🧠 Session Context - Track sent data to avoid resending in multi-turn conversations
• 🔗 Schema Deduplication - Reference identical schemas by hash (up to 90% reduction)
• 📐 Micro-Schema Mode - Ultra-compact schemas with abbreviated types (60-70% reduction)
• 🔄 Delta Responses - Send only changes for repeated queries (90%+ reduction)
• 📊 Context Tracking - Monitor context window usage and get warnings before overflow
• 📝 Auto-Summarization - Extract key insights from large results (60-90% reduction)
• 🔍 Query Planning - Analyze code to detect optimization opportunities (30-50% improvement)

Monitoring & Observability

• 📈 Prometheus Metrics - Tool call latency, error rates, cache performance
• 📊 JSON Metrics API - Programmatic access to gateway statistics
• 💾 Result Caching - LRU cache with TTL for tool results
• 📝 Audit Logging - Track sensitive operations

Screenshots

Dashboard Overview

Tools Management

Add Server Dialog

Quick Start

1. Install Dependencies

npm install

2. Configure Backend Servers

Copy the example config and edit it:

cp config/servers.example.json config/servers.json

Edit config/servers.json to add your MCP servers:

{
  "servers": [
    {
      "id": "filesystem",
      "name": "Filesystem",
      "enabled": true,
      "transport": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
      },
      "toolPrefix": "fs"
    }
  ]
}

Server identity rules:

• id is the stable backend identifier used by the gateway API and dashboard routes. It must be unique and contain only lowercase letters, numbers, and hyphens, for example mssql-crm-prod.
• name is the human-readable display label. It can use spaces and title case, for example CRM Production MSSQL.
• toolPrefix is the namespace prepended to tools from that backend. It must contain only lowercase letters, numbers, and underscores, for example mssql_crm_prod.

3. Start the Gateway

# Development
npm run dev

# Production
npm run build
npm start

The gateway will start on http://localhost:3010 by default.

Security modes

For local experimentation you can run without auth:

• AUTH_MODE=none

However, sensitive endpoints (/dashboard, /dashboard/api/*, /api/code/*, /metrics/json) are blocked by default when AUTH_MODE=none. To allow unauthenticated access (not recommended except for isolated local use), explicitly opt in:

• ALLOW_INSECURE=1

For secure usage, prefer:

• AUTH_MODE=api-key with API_KEYS=key1,key2
• or AUTH_MODE=oauth with the appropriate OAUTH_* settings shown below.

Hardening Setup

Use DEPLOYMENT_PROFILE to make the gateway fail closed for the environment you are running:

| Profile | Intended use | Code isolation | Store requirement | |---------|--------------|----------------|-------------------| | local-single-user | Trusted local development | Node vm by default, SANDBOX_ISOLATE=1 optional | memory default | | shared-local | Shared workstation or LAN | Strong isolation required | memory allowed | | remote-private | Private remote service | Strong isolation required | memory allowed | | remote-public | Internet-facing service | Strong isolation required | redis required |

Protected profiles (shared-local, remote-private, remote-public) require:

• AUTH_MODE=api-key or AUTH_MODE=oauth
• Non-wildcard CORS_ORIGINS
• A code-execution allowlist via CODE_EXECUTION_REQUIRE_ALLOWLIST=1, CODE_EXECUTION_ALLOWED_TOOLS, or CODE_EXECUTION_ALLOWED_TOOL_PREFIXES
• Strong sandbox isolation; Node 25 protected runs fail closed when isolated-vm is unavailable

For Redis-backed shared state:

STORE_BACKEND=redis
REDIS_URL=redis://127.0.0.1:6379
STORE_NAMESPACE=mcp-gateway

remote-public refuses to start unless STORE_BACKEND=redis is configured and reachable. Local and private deployments can keep the in-memory default, but memory stores are process-local and reset on restart.

Before shipping a hardening change, run the full validation gate:

npm run typecheck
npm test
npm run lint
npm run build

Hardening closeout notes

The latest hardening closeout adds these guardrails:

• Sandbox host-callable wrappers are pinned to safe call shapes so user code cannot pivot through wrapper constructors.
• Redis-backed rate limits use atomic TTL-aware updates, and remote-public remains fail-closed without reachable Redis.
• completion/complete requests are routed through the owning backend so resource references cannot cross backend boundaries.
• Redis session cleanup returns expired session IDs so local PII token maps are removed when shared sessions expire.
• REST skill execution now carries the authenticated identity/scope into the skill runner.
• REST tool-call caching is explicit opt-in with cache: true or cache: { "enabled": true }; cache hits do not bypass authorization.

To confirm what is running locally without restarting the gateway:

lsof -nP -iTCP:3010 -sTCP:LISTEN
curl -sS http://127.0.0.1:3010/health/summary

Endpoints

Core Endpoints

| Endpoint | Transport | Use Case | |----------|-----------|----------| | /mcp | HTTP Streamable | Primary endpoint - works with all clients | | /sse | Server-Sent Events | Backward compatibility | | /health | JSON | Health checks and status | | /dashboard | Web UI | Manage tools, backends, and restart server | | /metrics | Prometheus | Prometheus-format metrics | | /metrics/json | JSON | JSON-format metrics |

Code Execution API

| Endpoint | Method | Description | |----------|--------|-------------| | /api/code/tools/search | GET | Search tools with filters | | /api/code/tools/tree | GET | Get filesystem-like tool tree | | /api/code/tools/names | GET | Get all tool names (minimal tokens) | | /api/code/tools/:name/schema | GET | Lazy-load specific tool schema | | /api/code/tools/stats | GET | Tool statistics by backend | | /api/code/sdk | GET | Auto-generated TypeScript SDK | | /api/code/execute | POST | Execute code in sandbox | | /api/code/tools/:name/call | POST | Call tool with result filtering | | /api/code/tools/:name/call/aggregate | POST | Call t

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: abdullah1854
• Source: abdullah1854/MCPGateway
• License: MIT

Install and usage instructions live in the source repository linked above.