Mcplex

🚀 MCPlex — The MCP Smart Gateway

Semantic tool routing • Security guardrails • Real-time observability

[](https://github.com/ModernOps888/mcplex/actions/workflows/ci.yml) [](https://github.com/ModernOps888/mcplex/releases) [](LICENSE) [](https://www.rust-lang.org/) [](https://modelcontextprotocol.io)

Stop dumping 50k tokens of tool definitions into your LLM's context window. MCPlex intelligently routes only the tools your agent actually needs.

---

The Problem

Every developer building multi-agent AI systems with MCP hits the same wall:

| Pain Point | Impact | |-----------|--------| | 🧠 Context Bloat | 20+ MCP servers = 50k+ tokens of tool definitions consuming your context window | | 🔓 No Security | No RBAC, no audit trails, tool poisoning vulnerabilities | | 👁️ Blind Operations | Can't track costs, latency, or debug wrong tool selection | | 🔄 Restart Required | Config changes require full restart in production | | 🕸️ N×M Complexity | Orchestrating dozens of servers is an integration nightmare |

The Solution

MCPlex is a single-binary Rust gateway that sits between your AI agent and MCP servers:

Your Agent ──→ MCPlex Gateway ──→ GitHub MCP     (stdio — persistent)
                    │           ──→ Slack MCP      (stdio — persistent)
                    │           ──→ Database MCP   (HTTP)
                    │           ──→ Filesystem MCP  (stdio — persistent)
                    ▼
            🧠 Smart Routing (70-90% token savings)
            🔒 RBAC + Audit Logs + API Key Auth
            📊 Real-time Dashboard + Prometheus
            📦 Response Caching (auto-detect read-only)
            🔑 Multi-Tenant (API key → role mapping)
            🔥 Hot-reload Config

Transport Support

MCPlex supports both MCP transport types as a first-class citizen:

| Transport | Discovery | Runtime Calls | Connection Model | |-----------|-----------|---------------|-----------------| | Stdio | ✅ Full MCP handshake | ✅ Multiplexed JSON-RPC | Persistent child process (long-lived) | | Streamable HTTP | ✅ Full MCP handshake | ✅ Standard HTTP POST | Stateless (connection pooling) |

Stdio servers are spawned at startup and kept alive for the gateway's lifetime. The MCP handshake (initialize → notifications/initialized) runs once, then all subsequent tools/call, resources/read, and prompts/get requests are multiplexed over the same stdin/stdout pipe using JSON-RPC ID correlation.

⚡ Quick Start

1. Install (Pre-built Binary)

Download the latest release from GitHub Releases:

# Linux / macOS
curl -LO https://github.com/ModernOps888/mcplex/releases/latest/download/mcplex-linux-x86_64
chmod +x mcplex-linux-x86_64
sudo mv mcplex-linux-x86_64 /usr/local/bin/mcplex

2. Build from Source

git clone https://github.com/modernops888/mcplex.git
cd mcplex
cargo build --release

3. Configure

cp mcplex.toml my-config.toml
# Edit my-config.toml with your MCP servers

Minimal config for stdio servers:

[gateway]
listen = "127.0.0.1:3100"
dashboard = "127.0.0.1:9090"

[router]
strategy = "semantic"

[[servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

[[servers]]
name = "memory"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory"]

4. Run

./target/release/mcplex --config my-config.toml

# Expected output:
# 🔌 Spawning stdio server 'filesystem': npx ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
# 🤝 MCP handshake complete for 'filesystem'
# 📡 Server 'filesystem': 11 tools, 0 resources, 0 prompts
# 🔌 Spawning stdio server 'memory': npx ["-y", "@modelcontextprotocol/server-memory"]
# 🤝 MCP handshake complete for 'memory'
# 📡 Server 'memory': 3 tools, 0 resources, 0 prompts
# ⚡ MCPlex gateway listening on 127.0.0.1:3100

5. Connect Your Agent

Point your MCP client to http://127.0.0.1:3100/mcp and open the dashboard at http://127.0.0.1:9090.

🚀 Running as a Service (Deployment)

For persistent environments, run MCPlex as a background service to ensure it starts automatically on boot and restarts if it crashes.

Linux (systemd)

Create a systemd unit file at /etc/systemd/system/mcplex.service:

[Unit]
Description=MCPlex Gateway
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/mcplex
ExecStart=/usr/local/bin/mcplex --config /path/to/mcplex/mcplex.toml
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable mcplex
sudo systemctl start mcplex
sudo systemctl status mcplex

macOS (launchd)

Create a launchd plist file at ~/Library/LaunchAgents/com.modernops.mcplex.plist:

    Label
    com.modernops.mcplex
    ProgramArguments
    
        /usr/local/bin/mcplex
        --config
        /path/to/mcplex.toml
    
    RunAtLoad
    
    KeepAlive
    
    StandardOutPath
    /tmp/mcplex.log
    StandardErrorPath
    /tmp/mcplex-error.log
    EnvironmentVariables
    
        PATH
        /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
    

Load and start the service:

launchctl load ~/Library/LaunchAgents/com.modernops.mcplex.plist
launchctl start com.modernops.mcplex

Log Rotation

When running as a service, ensure you implement log rotation to prevent infinite log growth. For macOS, add an entry to /etc/newsyslog.conf; for Linux, use logrotate. MCPlex also has built-in audit log rotation configured via max_log_size_mb.

Service Troubleshooting

| Issue | Resolution | |-------|------------| | Service fails to start immediately | Check your configuration file syntax by running mcplex --check --config manually. | | Port already in use | Verify no other service is bound to the listen port. Change gateway.listen in your config. | | launchd permission errors | Ensure the ProgramArguments path is absolute and executable by the user. | | Server respawn loop | Check the StandardErrorPath log for fatal bootstrap errors or missing dependencies (e.g., Node.js for npx servers). |

---

🔌 How to Connect Your Agent

MCPlex is a transparent MCP proxy — any MCP client that supports Streamable HTTP can connect to it. Your agent talks to MCPlex as if it were a single MCP server, and MCPlex handles multiplexing, routing, and security behind the scenes.

Claude Code / Claude Desktop (Recommended — stdio bridge)

Claude Code and Claude Desktop use stdio transport. MCPlex ships a cross-platform bridge (bridge.mjs) that translates stdio ↔ HTTP. Works on macOS, Windows, and Linux.

Add a .mcp.json to your project root (Claude Code auto-discovers it):

{
  "mcpServers": {
    "mcplex": {
      "command": "node",
      "args": ["/path/to/mcplex/bridge.mjs"],
      "env": {
        "MCPLEX_GATEWAY": "http://127.0.0.1:3100/mcp"
      }
    }
  }
}

For Claude Desktop, add the same config to claude_desktop_config.json.

VS Code / GitHub Copilot (agent mode)

VS Code supports MCP servers natively. Add a .vscode/mcp.json to your workspace (or run MCP: Add Server from the Command Palette) pointing at the MCPlex bridge:

{
  "servers": {
    "mcplex": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcplex/bridge.mjs"],
      "env": {
        "MCPLEX_GATEWAY": "http://127.0.0.1:3100/mcp"
      }
    }
  }
}

A ready-to-copy template lives at [examples/vscode-mcp.json](examples/vscode-mcp.json).

With the default meta-tool mode, Copilot's agent sees just 3 gateway tools (~200 tokens) instead of every tool definition from every connected server — the same 70–90% context savings apply inside your IDE session. Tool discovery happens on demand via mcplex_find_tools, and every call is still routed through RBAC, allowlists, audit logging, and the response cache.

Cursor / Windsurf / HTTP-capable MCP Clients

Clients that support streamable HTTP can connect directly:

{
  "mcpServers": {
    "mcplex-gateway": {
      "url": "http://127.0.0.1:3100/mcp"
    }
  }
}

Custom Python Agent

import requests

GATEWAY = "http://127.0.0.1:3100/mcp"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}  # Optional

# Initialize
resp = requests.post(GATEWAY, json={
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {"protocolVersion": "2025-11-25", "capabilities": {},
               "clientInfo": {"name": "my-agent", "version": "1.0"}}
}, headers=HEADERS)

# List all tools (MCPlex aggregates from all servers)
resp = requests.post(GATEWAY, json={
    "jsonrpc": "2.0", "id": 2, "method": "tools/list"
}, headers=HEADERS)
tools = resp.json()["result"]["tools"]

# Call a tool (MCPlex routes to the right server automatically)
resp = requests.post(GATEWAY, json={
    "jsonrpc": "2.0", "id": 3, "method": "tools/call",
    "params": {"name": "create_issue", "arguments": {"repo": "my-repo", "title": "Bug fix"}}
}, headers=HEADERS)

How It Catches Your Agent's Calls

MCPlex acts as a man-in-the-middle proxy for all MCP traffic:

Your Agent ──POST /mcp──→ MCPlex Gateway ──→ Upstream MCP Server
                              │                (persistent stdio or HTTP)
                              ├─ ✅ Auth check (constant-time API key compare)
                              ├─ 🚦 Rate limit check
                              ├─ 🧪 Input validation (name charset, 64KB / depth-16 args cap)
                              ├─ 🔒 RBAC + allowlist/blocklist (role bound to API key)
                              ├─ 📝 Audit log (every call)
                              └─ 📊 Metrics (latency, tokens, security events)

Every tools/call goes through the security engine and is logged. Every tools/list goes through the semantic router. There's no way to bypass it — if your agent uses MCPlex as its MCP endpoint, all calls are intercepted, checked, and logged.

🤖 Compatible AI Models

MCPlex is model-agnostic — it routes any MCP-compliant client traffic regardless of which LLM is driving it. These are the frontier models actively tested with MCPlex as of July 2026:

| Model | Provider | MCP Client | Best For | |-------|----------|-----------|----------| | GPT-5.6 Sol | OpenAI | ChatGPT Work, custom | Flagship reasoning + agentic tasks | | GPT-5.6 Terra | OpenAI | ChatGPT Work, custom | Balanced performance / cost | | GPT-5.6 Luna | OpenAI | ChatGPT Work, custom | Cost-efficient everyday tasks | | Claude Fable 5 | Anthropic | Claude Code, Claude Desktop | Extended reasoning + code | | Claude Mythos 5 | Anthropic | Claude Code, Claude Desktop | Complex multi-step agent workflows | | Claude Sonnet 5 | Anthropic | Claude Code, Claude Desktop | High-capability, broad availability | | Gemini 3.5 Flash | Google | Gemini Spark, custom | High-throughput, cost-efficient | | Gemini 3.1 Pro | Google | Gemini Spark, custom | Multimodal + Workspace integration | | Grok 4.5 | xAI | Custom / open-weight stacks | Competitive reasoning, open ecosystem |

The meta-tool pattern (3 gateway tools, ~200 tokens) is particularly effective with models that have smaller default context budgets — MCPlex's token savings become more impactful as model costs rise.

> Context savings scale with model pricing. With GPT-5.6 Sol at frontier pricing, eliminating 40k tokens of tool definitions per request translates to measurable cost reduction at scale.

🧠 Semantic Tool Routing

The killer feature. Instead of dumping all tool definitions into your LLM's context, MCPlex uses a meta-tool pattern that works with every standard MCP client — no custom extensions needed:

| Scenario | Without MCPlex | With MCPlex | Savings | |----------|---------------|-------------|---------| | 5 servers, 50 tools | ~10,000 tokens | ~200 tokens | 98% | | 10 servers, 100 tools | ~20,000 tokens | ~200 tokens | 99% | | 20 servers, 200 tools | ~40,000 tokens | ~200 tokens | 99.5% |

How It Works

When your agent calls tools/list, MCPlex returns 3 lightweight meta-tools (~200 tokens) instead of all real tools:

Agent                        MCPlex Gateway
  │                               │
  ├──tools/list──────────────────►│  Returns: mcplex_find_tools, mcplex_call_tool,
  │                               │           mcplex_list_categories (~200 tokens)
  │                               │
  ├──mcplex_find_tools────────────►│  "store a memory"
  │◄──────────────────────────────┤  → [{name: "create_memory", desc: "...", inputSchema: {...}},
  │                               │     {name: "save_note", desc: "...", inputSchema: {...}}]
  │                               │
  ├──mcplex_call_tool─────────────►│  {name: "create_memory", arguments: {...}}
  │◄──────────────────────────────┤  → tool result (routed through security + cache + audit)

• mcplex_find_tools(query) — Search for tools by natural language intent. Returns matching tools with full schemas.
• mcplex_call_tool(name, arguments) — Execute a discovered tool. Routes through the full security/audit/cache pipeline.
• mcplex_list_categories() — Browse available tool categories (server groups) with tool counts.

This works with Claude Code, Claude Desktop, Cursor, Windsurf, and any other MCP client — no custom extensions or client-side plugins required.

Routing Mode

MCPlex supports three routing modes via router.mode:

| Mode | Behavior | Client Compatibility | |------|----------|---------------------| | metatool (default) | Returns 3 gateway meta-tools; agent discovers real tools via mcplex_find_tools | ✅ All standard MCP clients | | passthrough | Returns all real tools directly (no routing indirection) | ✅ All standard MCP clients | | legacy | Uses _mcplex_query param extension for filtering | ❌ Custom clients only |

Routing Strategy

Within metatool and legacy modes, MCPlex uses a routing strategy to rank tools:

• semantic — Character n-gram embeddings with cosine similarity (recommended)
• keyword — TF-IDF keyword matching (zero ML dependency)
• passthrough — No filtering (baseline)

[router]
mode = "metatool"            # "metatool", "passthrough", or "legacy"
strategy = "semantic"        # "semantic", "keyword", or "passthrough"
top_k = 5                    # Return top 5 most relevant tools
similarity_threshold = 0.3   # Minimum relevance score
cache_embeddings = true       # Cache for faster repeated queries

🔒 Security Engine

Role-Based Access Control (RBAC)

[security]
enable_rbac = true

[roles.developer]
allowed_tools = ["github/*", "database/query_*"]

[roles.admin]
allowed_tools = ["*"]

[roles.readonly]
allowed_tools = ["*/list_*", "*/get_*"]
blocked_tools = ["*/delete_*", "*/drop_*"]

> Role trust boundary: a caller's role is only ever established server-side, from a verified api_key/api_keys match — never from anything a client sends in the request body. When enable_rbac = true and no api_key/api_keys are configured, every tool call is denied by default (no role can be established), and the gateway logs a startup warning so this isn't mistaken for a bug.

Per-Server Tool Blocklists

[[servers]]
name = "database"
url = "http://localhost:8080/mcp"
blocked_tools = ["drop_table", "delete_*", "truncate_*"]

Structured Audit Logging

Every tool invocation is logged as JSON Lines:

{"timestamp":"2026-04-10T10:00:00Z","event":"tool_call","tool_name":"github/create_issue","server_name":"github","duration_ms":342,"trace_id":"a1b2c3d4"}
{"timestamp":"2026-04-10T10:00:01Z","event":"tool_blocked","tool_name":"database/drop_table","reason":"security_policy","trace_id":"e5f6g7h8"}

📊

…

Source & license

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

• Author: ModernOps888
• Source: ModernOps888/mcplex
• License: MIT

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