DEV Community

Cover image for MCP Nexus 1.0: the routing & discovery layer for MCP tools
Darshan Kachare
Darshan Kachare

Posted on

MCP Nexus 1.0: the routing & discovery layer for MCP tools

#ai #mcp #typescript #opensource

Agents keep gaining access to more MCP tools — dozens, then hundreds. Exposing them all at once to Claude Code, Cursor, or OpenCode creates four concrete problems:

Problem Consequence
Discovery an agent can't reason over 500 tool descriptions
Context every exposed tool bloats the agent's context with irrelevant schemas
Security a tool shouldn't automatically receive unlimited permissions
Maintenance wiring each tool into each agent is duplicated, scattered work

MCP Nexus answers with a capability surface: rather than dumping every tool, it exposes the few that fit the current request. One umbrella MCP endpoint in front of hundreds of tools — the agent only ever sees the right capability at the right time.

It's free and open source (Apache-2.0), written in TypeScript, and runs on the Model Context Protocol. v1.0.0 is out.

What it does

  • One endpoint, hundreds of tools — agents connect once over stdio or Streamable HTTP to the full nexus.* surface: register_tool, remove_tool, inspect_tool, list_tools, route, discover, invoke, approvals, resolve_approval.
  • Dynamic capability discovery — nexus.discover returns the minimal tool surface that fits the request instead of 500 schemas.
  • Explainable routing — every decision carries a provider, confidence, matched capabilities, and alternatives.
  • LLM-optional — heuristic → semantic → LLM fallback. It routes perfectly with no GPU, no API key, no internet.
  • Policy-aware execution — per-tool permission scopes plus allow / deny / approval rules.
  • Audit-ready — JSONL activity log with executionId correlated end-to-end from gateway invoke to dashboard activity.

Architecture 

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

* LLM is optional — the zero-dependency router stack runs fully offline.

Quick start

Requires Node.js ≥ 22 (Node 24 recommended for native TypeScript).

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

# stdio (local client)
npm start

# …or Streamable HTTP (remote clients)
npm start -- start:http        # http://127.0.0.1:3001/mcp
Enter fullscreen mode Exit fullscreen mode

Connect the endpoint from any MCP client. From a second terminal, manage the registry:

npm start -- add tools/repoarch.json
npm start -- add tools/ctx.json
npm start -- add tools/dependency-audit.json

npm start -- list                               # browse
npm start -- inspect repoarch                   # full manifest
npm start -- search "check vulnerable dependencies"   # dry-run routing
npm start -- doctor                             # environment check
npm start -- benchmark                          # CI gate
Enter fullscreen mode Exit fullscreen mode

Now connect any MCP client and ask:

"Analyze my repository architecture and check dependencies for vulnerabilities."

The agent calls nexus.route / nexus.invoke; Nexus discovers, selects, policy-checks, and executes the right tool — over both transports.

How routing works

The router chain is provider fallback, left to right:

heuristic → semantic → llm
Enter fullscreen mode Exit fullscreen mode
Provider What it does
heuristic deterministic keyword / capability scoring with an embedded stemmer
semantic zero-dependency character-bigram / IDF fuzzy router; recovers typos like "archtecture" and "vulnerbilities"
llm Gemini (REST) or OpenRouter (OpenAI-compatible); reports unavailable without a key so the chain never depends on it

A deterministic intent overlay fires at the route head in both heuristic and semantic layers, so domain vocabulary — git history, dependency/lockfile risk, secret scanning, repo structure — always wins over generic context fallbacks.

Every decision is explainable:

$ npm start -- search "check vulnerable dependencies"

Request: "check vulnerable dependencies"
Selected: dependency-audit
Provider: heuristic
Confidence: 100%
Matched capabilities: dependency-audit
Alternatives: repoarch (49%), ctx (0%)
Why: Matched capabilities: dependency-audit for "dependency-audit".
Enter fullscreen mode Exit fullscreen mode

Policy-aware execution

Manifests carry permission scopes; global rules add allow / deny / approval:

// .nexus/policy.json
{
  "default": "allow",
  "rules": [
    { "tool": "git", "blocklists": ["git.push"], "approvals": ["git.commit"] }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Approval-gated tools queue for an operator and resolve over the gateway (nexus.approvals, nexus.resolve_approval) or through the web dashboard.

Deterministic benchmark, not vibes

A fully-offline reference suite — 6 tools / 32 tasks across exact / semantic / ambiguous / unknown intents — reproducible on any machine:

Provider Accuracy exact semantic ambiguous unknown
Heuristic 100.0% 15/15 4/4 5/5 8/8
Semantic 87.5% 15/15 4/4 2/5 7/8
Hybrid 93.8% 15/15 4/4 4/5 7/8
Large (50 tools) 100.0% 20/20 — — —

Hard failures: none. mcp-nexus benchmark exits 0 only when every exact + semantic reference task routes correctly — and that is the CI gate.

Try it

Top comments (0)