◈MCP Nexus
v1.0.0 · MIT-friendly Apache-2.0 · zero-dependency core

The intelligent routing & discovery layer for MCP tools.

Connect once. Discover dynamically. Route intelligently. Execute safely.
One umbrella MCP endpoint in front of hundreds of tools — the agent only ever sees the right capability at the right time.

Get started View on GitHub
100%heuristic reference accuracy
0hard-failure residuals (§31)
no LLM neededGPU- & key-free by default

What you get

One endpoint, hundreds of tools

Agents connect once over stdio or Streamable HTTP. The gateway serves the full nexus.* surface — register, remove, inspect, list, route, discover, invoke, approvals.

Dynamic capability discovery

Instead of dumping 500 tool schemas into the agent's context, nexus.discover returns the minimal tool surface that fits the current request.

Explainable routing

Every decision carries a provider, confidence, matched capabilities, and alternatives — so you can see why a tool was chosen.

Policy-aware execution

Allow / deny / approval gates with per-tool permission scopes. Approval-gated tools queue for an operator and resolve through the gateway or the dashboard.

Works with no LLM

Heuristic → semantic → LLM fallback chain. The zero-dependency stack routes perfectly offline; Gemini and OpenRouter bolt on only when you add a key.

Deterministic & measured

A 32-task §31 reference suite runs offline in CI. mcp-nexus benchmark exits 0 only when every exact + semantic task routes correctly.

Architecture

                    AI AGENT
             Claude / Cursor / Codex
                       │
                       ▼
              ┌─────────────────┐
              │    MCP SERVER   │  stdio · Streamable HTTP
              └────────┬────────┘
                       │
                       ▼
              ┌─────────────────┐
              │    DISCOVERY    │
              └────────┬────────┘
                       │
             ┌─────────┴─────────┐
             ▼                   ▼
        TOOL REGISTRY         ROUTER          intent overlay (§25)
                               │
                   ┌───────────┼───────────┐
                   ▼           ▼           ▼
                Heuristic   Semantic    LLM*
                   │           │           │
                   └───────────┼───────────┘
                               ▼
                         POLICY ENGINE
                               │
                               ▼
                         TOOL RUNNER
                               │
              local · stdio · docker · http
                               │
                               ▼
                            MCP TOOL

* LLM is optional — MCP Nexus routes perfectly with no API key, no GPU, no network.
Run everything with npm install && npm start and a reference dashboard over mcp-nexus dashboard.

Deterministic §31 benchmark

6 tools · 32 tasks (exact / semantic / ambiguous / unknown) · fully offline · asserted in CI

ProviderAccuracyexactsemanticambiguousunknown
Heuristic100%15/154/45/58/8
Semantic87.5%15/154/42/57/8
Hybrid chain93.8%15/154/44/57/8
Large (50 tools)100%20/20———

Hard failures: none. The benchmark command is the CI gate.

Quick start

$ git clone https://github.com/dsk-dev-ai/mcp-nexus.git
$ cd mcp-nexus
$ npm install

# stdio for a local client, or Streamable HTTP for remote clients:
$ npm start                          # stdio
$ npm start -- start:http            # http://127.0.0.1:3001/mcp

# manage tools, route, and verify in a second terminal:
$ npm start -- add tools/repoarch.json
$ npm start -- search "check vulnerable dependencies"
$ npm start -- doctor
$ npm start -- benchmark             # exit 0 = §31 reference green

Documentation

API reference

MCP gateway (stdio + HTTP), dashboard REST, CLI, SDK.

Architecture

System design, router chain, policy, executor.

Routing

Heuristic, semantic, LLM providers, intent overlay.

Tool registry

Manifest schema (JSON + YAML), transports, permissions.

Benchmarks

Full §31 numbers, method, reproduction.

Dashboard

Web UI + REST, policies, approvals, auth.

Security

Threat model, permissions, audit log.

Clients

Verified MCP client compatibility matrix.

SDK & plugins

Build Nexus-compatible tools and routers.

Performance

V1 latency targets vs measured.

Integrations

Docker, CI, environment setup.

Changelog

Every release, documented.