◈ MCP Nexus

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.

Project site · Documentation · Changelog · Roadmap · Contributing

Contents

• Why MCP Nexus

• Architecture

• Features

• Quick start

• How routing works

• Policy-aware execution

• Tool manifests

• CLI reference

• Deterministic benchmark (31)

• SDK & plugins

• Run with Docker

• Configuration

• Security

• Repository layout

• Documentation

• Roadmap

• Contributing

• Sponsor

Related MCP server: LangGraph FastAPI MCP Server

Why MCP Nexus

Agents gain access to dozens — then hundreds — of MCP tools. Exposing them all at once creates four concrete problems:

MCP Nexus answers with a capability surface: rather than dumping every tool, it exposes the few that fit the current request.

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

* LLM is optional. MCP Nexus runs fully on the zero-dependency router stack (heuristic + fuzzy semantic) — no GPU, no API key, no internet required. http and docker transports execute tools over a JSON POST endpoint or docker run.

Features

• 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 current request instead of 500 schemas.

• Explainable routing — every decision carries a provider, confidence, matched capabilities, and alternatives. You always know why a tool was chosen.

• Deterministic & measured — a 32-task reference suite runs offline in CI; mcp-nexus benchmark exits 0 only when every exact + semantic task routes correctly.

• LLM-optional — heuristic → semantic → LLM fallback chain. Gemini and OpenRouter bolt on when you add a key; nothing degrades without one.

• Policy-aware execution — per-tool permission scopes plus allow / deny / approval rules; approval-gated tools wait for an operator.

• Modern transports — local subprocess, stdio, docker run, and HTTP POST execution.

• Audit-ready — JSONL activity log with executionId correlated end-to-end from gateway invoke to dashboard activity.

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

Streamable HTTP (remote clients):

npm start -- start:http     # http://127.0.0.1:3001/mcp

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

npm start -- add tools/repoarch.json            # register a tool
npm start -- list                               # browse
npm start -- inspect repoarch                   # full manifest
npm start -- search "check vulnerable dependencies"   # dry-run routing
npm start -- enable dependency-audit            # toggle enabled state
npm start -- doctor                             # environment check
npm start -- benchmark                          # CI gate: exit 0 iff §31 green

Expose tools to any agent

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

Now connect Claude Code, Cursor, OpenCode — or 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

A deterministic intent overlay (src/router/intents.ts) fires first 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".

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"] }
  ]
}

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

Tool manifests

Every tool is one file: capabilities, transport, permissions.

{
  "name": "dependency-audit",
  "version": "1.0.0",
  "description": "Scan dependencies of a project for vulnerable or insecure packages.",
  "capabilities": ["security", "dependency-audit"],
  "transport": { "type": "local", "command": ["npm", "audit"] },
  "permissions": { "network": { "access": true }, "filesystem": { "read": true, "write": false } },
  "enabled": true
}

See tools/ for 5 reference implementations or the registry docs for the full schema (JSON + YAML).

CLI reference

Deterministic benchmark (31)

A fully-offline reference suite — 6 tools / 32 tasks across exact / semantic / ambiguous / unknown intents. Reproducible on any machine: no LLM, no network, no random seeding.

Hard failures: none. The benchmark command exits 0 only when every exact + semantic reference task routes correctly — that is the CI gate. Method, full numbers, and npm run bench:latency (strict sub-2 ms per-task gate) live in docs/benchmarks.md.

SDK & plugins

Build Nexus-compatible tools and drop-in components with the SDK (createTool, defineCapabilities, definePermissions, registerTool, buildRouter) and the plugin contracts in src/sdk/interfaces.ts. The API reference covers the MCP gateway, dashboard REST API, and CLI.

Run with Docker

docker compose up -d     # dashboard at http://localhost:8080
docker compose exec nexus node src/index.ts add tools/repoarch.json

Registry and activity persist across restarts (named volume). See docs/dashboard.md, docs/performance.md, and the client compatibility matrix.

Configuration

Copy .env.example to .env and adjust (MCP_NEXUS_PORT, MCP_NEXUS_HOST, MCP_NEXUS_ROUTER_MODE, MCP_NEXUS_LOG_LEVEL, MCP_NEXUS_EXECUTION_TIMEOUT, MCP_NEXUS_API_TOKEN for dashboard auth, optional MCP_NEXUS_*_API_KEY for Gemini / OpenRouter).

Precedence: defaults < .nexus/config.json < .env < real environment.

Security

MCP Nexus executes tools on behalf of connected agents. Review tool permissions and execution policies before enabling untrusted tools.

V1 security surface:

• Permission model: allow / deny / approval.

• Execution isolation: subprocess with timeout, stdout/stderr capture.

• Per-tool permission scopes from manifests.

• Optional bearer-token auth on the dashboard REST API (MCP_NEXUS_API_TOKEN).

• Audit log: JSONL activity log (.nexus/activity.jsonl), with executionId surfaced end-to-end from gateway invoke to dashboard activity.

Report vulnerabilities via SECURITY.md.

Repository layout

src/
├── cli.ts               # CLI surface
├── config.ts            # env + .nexus/config.json
├── version.ts           # single version constant (gateway, dashboard, CLI)
├── registry/            # manifest schema + file store
├── router/              # heuristic + fuzzy semantic (zero-dep), intent overlay, llm (optional), fallback chain
├── policy/              # allow/deny/approval engine (read + replace)
├── executor/            # transports: local/stdio subprocess, docker run, http POST
├── telemetry/           # JSONL activity log
├── dashboard/           # single-page UI + REST API (optional bearer auth)
└── server/              # MCP server factory + stdio (server.ts) and Streamable HTTP (httpGateway.ts)
examples/                # sample JSON + YAML manifests
tests/                   # node:test suite (93 tests)
tools/                   # reference tool manifests
docs/                    # architecture, registry, routing, security, integrations

Documentation

Roadmap

Full detail in ROADMAP.md.

Contributing

See CONTRIBUTING.md — setup, architecture notes, and PR requirements. Code of Conduct in CODE_OF_CONDUCT.md.

Sponsor

MCP Nexus is free and open source (Apache-2.0). If it saves your team time, consider sponsoring the work:

GitHub Sponsors: https://github.com/sponsors/dsk-dev-ai

Sponsorships fund LLM-provider test keys, CI minutes, and docs. Every contribution is public in the changelog. You can also help by contributing — issues, PRs, and benchmark scenarios are all welcome.

License

Apache-2.0 — see LICENSE. Written by dsk-dev-ai.