MCP Gateway

A universal Model Context Protocol (MCP) Gateway that aggregates multiple MCP servers and provides result optimization that native tool search doesn't offer. Works with all major MCP clients:

• ✅ Claude Desktop / Claude Code

• ✅ Cursor

• ✅ OpenAI Codex

• ✅ VS Code Copilot

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:

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:

*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

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

2. Configure Backend Servers

Copy the example config and edit it:

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

3. Start the Gateway

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.

Endpoints

Core Endpoints

Code Execution API

Dashboard API

Dashboard

Access the web dashboard at http://localhost:3010/dashboard to:

• View all connected backends and their real-time status

• Add new MCP servers with connection testing (STDIO, HTTP, SSE transports)

• Edit existing servers (modify command, args, environment variables)

• Delete servers with graceful disconnect

• Enable/disable individual tools or entire backends

• Search and filter tools across all backends

• Export/import configuration for backup and sharing

• Reconnect failed backends with one click

• Restart the entire gateway server

• View tool counts and backend health at a glance

The dashboard persists UI state (disabled tools/backends) across server restarts.

Client Configuration

Claude Desktop / Claude Code

1. Open Claude Desktop → Settings → Connectors

2. Click Add remote MCP server

3. Enter your gateway URL:

4. Complete authentication if required

Note: Claude requires adding remote servers through the UI, not config files.

Claude Desktop via STDIO Proxy

If Claude Desktop doesn't support HTTP/SSE transports directly, you can use the included STDIO proxy script:

The proxy (scripts/claude-stdio-proxy.mjs) reads JSON-RPC messages from stdin, forwards them to the gateway HTTP endpoint, and writes responses to stdout. It automatically manages session IDs.

Cursor

1. Open Cursor → Settings → Features → MCP

2. Click Add New MCP Server

3. Choose Type: HTTP or SSE

4. Enter your gateway URL:

For HTTP (recommended):

For SSE:

Or add to your Cursor settings JSON:

OpenAI Codex

Option 1: CLI

Option 2: Config File

Add to ~/.codex/config.toml:

Important: Codex requires HTTPS for remote servers and only supports HTTP Streamable (not SSE).

VS Code Copilot

1. Open Command Palette (Cmd/Ctrl + Shift + P)

2. Run MCP: Add MCP Server

3. Choose Remote (URL)

4. Enter your gateway URL:

5. Approve the trust prompt

Or add to your VS Code settings.json:

Backend Server Configuration

The gateway can connect to MCP servers using different transports:

STDIO (Local Process)

HTTP (Remote Server)

Tool Prefixing

Use toolPrefix to namespace tools from different servers:

• Server with toolPrefix: "fs" exposes read_file as fs_read_file

• Prevents naming collisions between servers

• Makes it clear which server handles each tool

Authentication

API Key Authentication

Set environment variables:

Clients send the key in the Authorization header:

OAuth Authentication

Docker Deployment

Build and Run

Docker Compose

Environment Variables

Core Configuration

Optional Features

MCP Gateway includes optional features that are disabled by default for minimal, public-friendly deployments. Enable them by setting the corresponding environment variable to 1.

When a feature is disabled:

• The corresponding dashboard tab is hidden

• API endpoints return 404 Feature disabled with instructions to enable

• No errors occur from missing dependencies (Qdrant, Cipher service, etc.)

For personal/development use, enable the features you need in your .env:

Feature-Specific Configuration

These variables are only needed when the corresponding feature is enabled:

Optional Features Guide

This section provides detailed instructions for enabling and using each optional feature.

Skills System (ENABLE_SKILLS=1)

The Skills system allows you to save and reuse code patterns for zero-shot execution. Skills are the most powerful token-saving feature in MCP Gateway, reducing token usage by 95%+ for recurring tasks.

What Skills Do

• Save successful code patterns as reusable templates

• Execute complex workflows with a single tool call (~20 tokens)

• Eliminate prompt engineering for recurring tasks

• Hot-reload when skill files change on disk

Enabling Skills

Storage Locations

Skills are stored in two directories:

• workspace/skills/ - User-created skills (editable)

• external-skills/ - Shared/imported skills (read-only by default)

Each skill is a directory containing:

Creating Skills via MCP Tools

Executing Skills

Skills MCP Tools

Skills REST API

Dashboard

When enabled, a Skills tab appears in the dashboard (/dashboard) showing:

• All available skills with search/filter

• Skill details and code preview

• Execute skills directly from UI

• Create new skills from templates

Cipher Memory (ENABLE_CIPHER=1)

Cipher Memory provides persistent AI memory across all IDEs. Decisions, learnings, patterns, and insights are stored in a vector database and recalled automatically in future sessions.

What Cipher Does

• Cross-IDE memory - Memories persist across Claude, Cursor, Windsurf, VS Code, Codex

• Project-scoped context - Filter memories by project path

• Semantic search - Find relevant memories using natural language

• Auto-consolidation - Session summaries stored automatically

Prerequisites

Cipher requires two external services:

1. Cipher Memory Service - The memory API (default: http://localhost:8082)

2. Qdrant Vector Store - For semantic memory storage

Enabling Cipher

Using Cipher via MCP

The Cipher service exposes the cipher_ask_cipher tool via MCP:

Memory Types

Dashboard API

Dashboard

When enabled, a Memory tab appears showing:

• Total memories stored in Qdrant

• Recent memories with timestamps

• Memory categories breakdown (decisions, learnings, etc.)

• Search interface for finding memories

• Session history viewer

Claude Usage Tracking (ENABLE_CLAUDE_USAGE=1)

Track your Claude API token consumption and costs across all Claude Code sessions.

What It Does

• Aggregate usage data from Claude Code JSONL logs

• Track costs by model (Opus, Sonnet, Haiku)

• Monitor cache efficiency (creation vs read tokens)

• View daily/weekly/monthly trends

• Live session monitoring

Prerequisites

This feature uses the ccusage CLI tool to parse Claude Code conversation logs from ~/.claude/projects/.

Enabling Claude Usage

No additional configuration required - the service automatically finds Claude Code logs.

Dashboard API

Response Format

Dashboard

When enabled, a Usage tab appears showing:

• Total cost and token breakdown

• Cost by model pie chart

• Cache hit ratio (higher = more efficient)

• Daily usage trend graph

• Top usage days

• Live current session monitoring

Antigravity Usage Tracking (ENABLE_ANTIGRAVITY=1)

Track quota and usage for Antigravity IDE (formerly Windsurf/Codeium) accounts.

What It Does

• Real-time quota monitoring for all model tiers

• Multi-account support (Antigravity + Techgravity accounts)

• Conversation statistics from local data

• Brain/task tracking for agentic workflows

• Auto-detection of running Language Server processes

How It Works

The service:

1. Detects running language_server_macos processes

2. Extracts CSRF tokens and ports from process arguments

3. Queries the local gRPC-Web endpoint for quota data

4. Falls back to file-based stats if API unavailable

Prerequisites

• Antigravity IDE installed and running

• Account directories exist in ~/.gemini/antigravity/ or ~/.gemini/techgravity/

Enabling Antigravity Usage

No additional configuration required.

Dashboard API

Response Format

Dashboard

When enabled, an Antigravity tab appears showing:

• Running status indicator (green = active)

• Per-account quota bars for each model

• Remaining percentage with color coding (green/yellow/red)

• Time until quota reset

• Conversation and task statistics

• Multi-account support (Antigravity + Techgravity)

Enabling All Features

For personal/development use, enable everything:

Then restart the gateway:

All four tabs will now appear in the dashboard at http://localhost:3010/dashboard.

Health Check

Response:

Architecture

Code Execution Mode

The Code Execution Mode allows AI agents to write and execute code instead of making individual tool calls, achieving up to 98.7% token reduction for complex workflows.

Why Skills? (Efficiency & Token Usage)

Skills are the most powerful token-saving feature in MCP Gateway. Here's why:

The Token Problem

Without skills, every complex operation requires:

1. Input tokens: Describe the task in natural language (~200-500 tokens)

2. Reasoning tokens: Model thinks about how to implement it (~100-300 tokens)

3. Output tokens: Model generates code to execute (~200-1000 tokens)

4. Result tokens: Large query results enter context (~500-10,000+ tokens)

Total: 1,000-12,000+ tokens per operation

The Skills Solution

With skills, the same operation requires:

1. Input tokens: gateway_execute_skill({ name: "daily-report" }) (~20 tokens)

2. Result tokens: Pre-filtered, summarized output (~50-200 tokens)

Total: 70-220 tokens per operation → 95%+ reduction

Key Benefits

Real-World Example

Without Skills (Traditional approach):

With Skills (Skill-based approach):

Gateway MCP Tools

All code execution features are exposed as MCP tools that any client can use directly. When connected to the gateway, clients automatically get these 19 tools instead of 300+ raw tool definitions:

Tool Discovery (Progressive Disclosure)

Execution & Filtering

Skills (Highest Token Savings)

Optimization & Monitoring

Progressive Tool Disclosure

Instead of loading all tool definitions upfront (which can consume excessive tokens with 300+ tools), use progressive disclosure:

Detail levels for search:

• name_only - Just tool names

• name_description - Names with descriptions

• full_schema - Complete JSON schema

Sandboxed Code Execution

Execute TypeScript/JavaScript code in a secure Node.js VM sandbox:

The sandbox:

• Auto-generates TypeScript SDK from your MCP tools

• Supports async/await, loops, and conditionals

• Returns only console.log output (not raw data)

• Has configurable timeout protection

Context-Efficient Results

Reduce context bloat from large tool results:

Available aggregations: count, sum, avg, min, max, groupBy, distinct

Privacy-Preserving Operations

Automatically tokenize PII so sensitive data never enters model context:

Output shows tokenized values:

Tokens are automatically untokenized when data flows to another tool.

Skills System

Save successful code patterns as reusable skills:

Skills are stored in the skills/ directory and can be discovered via filesystem exploration.

Session State & Workspace

Persist state across agent sessions:

State is stored in the workspace/ directory.

Monitoring & Metrics

Prometheus Metrics

Returns metrics including:

• mcp_tool_calls_total - Total tool calls by backend and tool

• mcp_tool_call_duration_seconds - Tool call latency histogram

• mcp_tool_errors_total - Error count by backend

• mcp_cache_hits_total / mcp_cache_misses_total - Cache performance

• mcp_active_connections - Active client connections

JSON Metrics

Caching

Tool results are cached using an LRU cache with TTL:

Token Efficiency Architecture

MCP Gateway implements a multi-layered approach to minimize token usage at every stage of AI agent interactions.

Layer 1: Progressive Tool Disclosure (85% Reduction)

Traditional MCP clients load all tool schemas upfront. With 300+ tools, this can consume 77,000+ tokens before any work begins.

How it works:

Layer 2: Smart Result Filtering (60-80% Reduction)

Large tool results can consume thousands of tokens. Smart filtering is enabled by default.

Layer 3: Server-Side Aggregations

Instead of fetching raw data and processing client-side, compute aggregations in the gateway:

Available operations: count, sum, avg, min, max, groupBy, distinct

Layer 4: Code Execution Batching

Execute multiple operations in a single round-trip. Results are processed server-side; only console.log output returns.

Layer 5: Skills (95%+ Reduction)

Skills eliminate prompt engineering entirely for recurring tasks:

Layer 6: Result Caching

Identical queries hit the LRU cache instead of re-executing:

Layer 7: PII Tokenization

Sensitive data never enters model context while still flowing between tools:

Layer 8: Response Optimization (20-40% Reduction)

Automatically strip default/empty values from all responses:

Strips: null, undefined, empty strings "", empty arrays [], empty objects {}

Layer 9: Session Context Cache (Very High Reduction)

Tracks what schemas and data have been sent in the conversation to avoid resending:

Layer 10: Schema Deduplication (Up to 90% Reduction)

Many tools share identical schemas. Reference by hash instead of duplicating:

Layer 11: Micro-Schema Mode (60-70% Reduction)

Ultra-compact schema representation using abbreviated types:

Layer 12: Delta Responses (90%+ Reduction)

For repeated queries or polling, send only changes since last call:

Layer 13: Context Window Tracking (Safety)

Monitor context usage to prevent overflow and get optimization recommendations:

Layer 14: Auto-Summarization (60-90% Reduction)

Automatically extract insights from large results:

Layer 15: Query Planning (30-50% Improvement)

Analyze code before execution to detect optimization opportunities:

Combined Token Savings

Real-world impact: A typical 10-minute agent session with 50 tool calls drops from ~500,000 tokens to ~25,000 tokens.

Tips for AI Agents

When using MCP Gateway with AI agents (Claude, GPT, etc.), follow these best practices for efficient token usage:

1. Start with Tool Discovery

2. Use Code Execution for Complex Workflows

3. Filter Large Results

4. Use Aggregations

5. Save Reusable Patterns as Skills

Invoking Cipher from Any IDE

Cipher exposes the cipher_ask_cipher tool via MCP. To ensure memories persist across IDEs and sessions, always include the .

Tool Schema

Quick Reference

IDE Configuration Examples

Add these instructions to your IDE's rules file so the AI automatically uses Cipher.

Claude Code can use a SessionStart hook for automatic recall. For manual configuration:

Why projectPath Matters

The projectPath parameter is critical for:

1. Cross-IDE Filtering: Memories are scoped to projects, so switching from Cursor to Claude Code maintains context.

2. Avoiding Pollution: Without projectPath, memories from different projects mix together.

3. Team Sync: Workspace memory features rely on consistent project paths.

Common Mistake: Using {cwd} or just the project name. These don't resolve correctly. Always use the full absolute path like /path/to/your/project.

macOS Auto-Start (LaunchAgent)

To run the gateway automatically on login:

1. Copy and customize the example plist file:

Update these paths in the plist file:

• /path/to/mcp-gateway → Your actual installation path

• /usr/local/bin/node → Your Node.js path (run which node to find it)

2. Load the LaunchAgent:

Windows Setup

Running the Gateway

Windows Auto-Start (Task Scheduler)

To run the gateway automatically on Windows startup:

1. Open Task Scheduler (taskschd.msc)

2. Click Create Task (not Basic Task)

3. Configure:

   • General tab: Name it MCP Gateway, check "Run whether user is logged on or not"

   • Triggers tab: Add trigger → "At startup"

   • Actions tab: Add action:

     • Program: node (or full path like C:\Program Files\nodejs\node.exe)

     • Arguments: dist/index.js

     • Start in: C:\path\to\mcp-gateway

   • Settings tab: Check "Allow task to be run on demand"

Alternatively, use the start.example.sh pattern adapted for PowerShell:

Windows Service (NSSM)

For a proper Windows service, use NSSM:

Development

License

MIT