# MCPGateway

> Open-source MCP server — progressive tool discovery, code execution, intelligent routing & token optimization across 50+ tools

- **Type:** MCP server
- **Install:** `agentstack add mcp-abdullah1854-mcpgateway`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [abdullah1854](https://agentstack.voostack.com/s/abdullah1854)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [abdullah1854](https://github.com/abdullah1854)
- **Source:** https://github.com/abdullah1854/MCPGateway

## Install

```sh
agentstack add mcp-abdullah1854-mcpgateway
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
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:

```json
{
  "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](https://github.com/abdullah1854/MCPGateway/issues)

## Quick Start in 3 Commands

```bash
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](https://platform.claude.com/docs/en/agents-and-tools/tool-use/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](https://platform.claude.com/docs/en/agents-and-tools/tool-use/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](https://www.anthropic.com/engineering/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

```bash
npm install
```

### 2. Configure Backend Servers

Copy the example config and edit it:

```bash
cp config/servers.example.json config/servers.json
```

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

```json
{
  "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

```bash
# 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:

```bash
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:

```bash
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:

```bash
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](https://github.com/abdullah1854)
- **Source:** [abdullah1854/MCPGateway](https://github.com/abdullah1854/MCPGateway)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-abdullah1854-mcpgateway
- Seller: https://agentstack.voostack.com/s/abdullah1854
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.