slm-mcp-hub 0.1.0

The world's first MCP gateway that learns — intelligent federation, caching, cost tracking, and coordination for Model Context Protocol servers.

SLM MCP Hub

One hub. Every MCP. Every AI client. Massive token savings.
Federated MCP gateway with caching, cost tracking, and smart tool discovery.

v0.1.0 — Share MCP servers across sessions. Save 150K tokens per session.

36 MCPs × 5 sessions = 180 processes → 37 shared  ·  ~9GB → ~2GB RAM  ·  ~150K tokens saved

---

Why SLM MCP Hub?

Every AI coding session spawns its own MCP processes. 5 Claude Code sessions with 36 MCPs = 180 processes eating ~9GB RAM. Each loads ~150K tokens of tool definitions into the context window. On a 200K-context model, that's 75% gone before you type anything.

SLM MCP Hub fixes both problems:

1. One hub process manages all MCPs, shared across every session
2. Federated mode exposes 3 meta-tools instead of 400+, saving ~150K tokens per session

The Numbers

Metric	Without Hub	With Hub (Federated)
Processes	5 sessions x 36 MCPs = 180	37 shared (79% less)
RAM	~9 GB	~1.9 GB
Session startup	~30s (spawn 36 processes)	Instant (HTTP connect)
Tool definitions in context	400+ tools (~150K tokens)	3 meta-tools (~1K tokens)
Config management	Per-IDE, per-session	One hub config

---

How It Works (Federated Mode)

Instead of loading 400+ tool definitions, Claude gets 3 meta-tools:

• hub__search_tools — Search all tools by name or description. Returns full input schemas.
• hub__call_tool — Call any tool by name. Routes to the correct MCP server.
• hub__list_servers — List all connected servers and their tool counts.

Claude: hub__search_tools(query="github search")
Hub:    Found 4 tools: github__search_repositories, github__search_code, ...
        [includes full inputSchema for each]

Claude: hub__call_tool(tool="github__search_repositories", arguments={"query": "qualixar"})
Hub:    Routes to GitHub MCP → returns real results

3 tool definitions in context instead of 400+. That's the token savings.

---

Quick Start

pip install slm-mcp-hub

# Initialize and import your MCPs
slm-hub config init
slm-hub setup import ~/.claude.json

# Start the hub
slm-hub start

Connect Claude Code (Federated Mode)

Add to ~/.claude.json:

{
  "mcpServers": {
    "hub": {
      "type": "http",
      "url": "http://127.0.0.1:52414/mcp"
    }
  }
}

Restart Claude Code. All tools available via hub__search_tools and hub__call_tool.

MCPs That Stay Direct

Some MCPs need direct connections because Claude Code hooks depend on them:

{
  "mcpServers": {
    "hub": {"type": "http", "url": "http://127.0.0.1:52414/mcp"},
    "superlocalmemory": {"command": "slm", "args": ["mcp"]},
    "google-workspace": {"command": "uvx", "args": ["workspace-mcp", "..."]}
  }
}

Rule: MCPs with hooks that call their tools directly (e.g., SLM's session_init hook) must stay as direct connections. Everything else goes through the hub.

---

What Works Today (v0.1.0)

These features are built, tested, and working:

• Federation — All MCP servers (stdio + HTTP + SSE) behind one endpoint
• Federated Mode — 3 meta-tools, ~150K token savings, smart search with word-split matching
• Transparent Proxy Mode — /mcp/{server} endpoints with original tool names (zero behavior change)
• Intelligent Caching — SHA-256 content-hash, TTL, O(1) LRU eviction
• Cost Tracking — Per-tool costs, session budgets, cascade routing to cheaper alternatives
• Smart Tool Filtering — Project-type detection (13 categories), frequency ranking
• Multi-Client Auto-Setup — Detects Claude Code, VS Code, Cursor, Windsurf, Codex CLI
• Observability — Per-server metrics, request tracing, audit log, management API
• Lifecycle Management — Lazy startup, idle shutdown, always-on marking
• Permission Model — Per-session role-based rules (ALLOW/DENY/WARN)
• Resilience — Auto-restart (launchd/systemd), PID management, health checks
• Network Discovery — mDNS/Zeroconf LAN discovery (optional)
• Secrets — Loads ~/.claude-secrets.env on startup, ${VAR} placeholder resolution
• Parallel Requests — Async FastAPI, concurrent tool calls across MCPs

SLM Integration (Working)

• SLM Plugin — Logs every tool call to the SLM learning pipeline, recalls context on session start, summarizes sessions. Connects to the SLM daemon via HTTP API (localhost:8765). Auto-discovered on startup when SLM is running.
• Mesh Plugin — Registers the hub as a mesh peer, broadcasts tool usage to other sessions, supports distributed locking. Connects via the SLM mesh HTTP API.

---

Two Modes

Both run simultaneously on the same hub.

Federated Mode (Recommended)

Endpoint: /mcp — One entry in claude.json. 3 meta-tools. Massive token savings.

Best for: production use, small-context models, cost optimization.

Transparent Proxy Mode

Endpoint: /mcp/{server} — Per-server entries. Original tool names. Zero behavior change.

Best for: migration testing, environments where tool name compatibility matters.

See Architecture Guide for details.

---

Architecture

                    ┌─────────────────────────────────────────┐
                    │            SLM MCP Hub                  │
AI Client 1 ──┐    │                                         │    ┌── MCP Server 1
AI Client 2 ──┼────┤  Federation → Cache → Cost → Route ─────┼────┤── MCP Server 2
AI Client 3 ──┘    │       ↕           ↕         ↕           │    ├── MCP Server N
                    │   Permissions  Metrics   Learning       │    └── CLI-Anything
                    └─────────────────────────────────────────┘

Direct MCPs (not through hub):
  SuperLocalMemory ← hooks depend on direct access
  Google Workspace ← OAuth session tied to process

---

CLI Reference

slm-hub start [--port PORT] [--config PATH] [--log-level LEVEL]
slm-hub status
slm-hub config show | init | import <file>
slm-hub setup detect | register | unregister | import
slm-hub network discover | info

---

Configuration

Config: ~/.slm-mcp-hub/config.json. Env overrides: SLM_HUB_PORT, SLM_HUB_HOST, SLM_HUB_LOG_LEVEL, SLM_HUB_CONFIG_DIR. Secrets from ~/.claude-secrets.env.

---

Documentation

Guide	What You'll Learn
Getting Started	Install, import, connect, verify — 5 minutes
Architecture	Two modes, tool call flow, direct MCP rules
Migration Guide	Step-by-step from direct to hub, rollback
Configuration	All settings, API endpoints, CLI reference

---

Part of Qualixar

Product	What
SuperLocalMemory	Infinite memory for AI agents — 3 research papers, 6 retrieval channels
Qualixar OS	Universal command protocol for AI agents
SLM MCP Hub	Intelligent MCP gateway (this repo)
AgentAssert	AI agent behavioral contract testing
AgentAssay	AI agent evaluation framework
SkillFortify	AI skill testing — 22 frameworks

Author: Varun Pratap Bhardwaj · qualixar.com · superlocalmemory.com

---

License

AGPL-3.0-or-later. See LICENSE. Commercial: [e-mail]