MCP Nexus

MCP Nexus is a local-first intelligent router for the Model Context Protocol. Your AI harness connects to one MCP endpoint — Nexus — while Nexus manages all of your real MCP servers behind the scenes: indexing their tools, discovering capabilities on demand, starting servers lazily, executing routed calls, and learning from local usage to rank results better over time.

Before                                With MCP Nexus

AI Harness                            AI Harness
  ├── GitHub MCP   (30 tools)           └── mcp-nexus (4 control tools)
  ├── Jira MCP      (25 tools)              ├── search_capabilities
  ├── Slack MCP     (20 tools)              ├──── describe_capabilities
  ├── Figma MCP     (18 tools)              ├──── execute_capability
  ...                                   └──── search_servers
  ~90+ tool schemas in context                  │
                                     (everything else stays indexed
                                      on disk until actually needed)

Why

Every connected MCP server contributes tool schemas to the model's context. Ten servers later you are burning tens of thousands of tokens on definitions the model rarely uses, and tool-selection quality degrades.

Nexus flips the model: instead of pushing every downstream schema into context, it keeps a lightweight capability index on disk and serves a tiny control plane. The agent discovers capabilities when needed (search_capabilities), inspects exact schemas only for what it selected (describe_capabilities), and executes through Nexus (execute_capability). All state — config, index, analytics, learned sequences — lives locally in .mcp-nexus/.

Related MCP server: Master MCP Server

Quick start

# 1. Scaffold a project config
npx @fyrlabs/mcp-nexus init

# 2. Add downstream MCP servers (anything runnable over stdio)
npx @fyrlabs/mcp-nexus add github -- npx -y @modelcontextprotocol/server-github
#    or import an existing config:
npx @fyrlabs/mcp-nexus import --from claude

# 3. Point your harness at Nexus (see docs/harness-setup.md)

Harness configuration (Claude Code, Cursor, Codex, and other MCP clients):

{
  "mcpServers": {
    "mcp-nexus": {
      "command": "npx",
      "args": ["-y", "@fyrlabs/mcp-nexus"]
    }
  }
}

Nexus finds project-mcp.json automatically by walking up from the working directory, or pass --config ./path/to/nexus.json.

Then, from the agent's point of view:

search_capabilities  { "query": "find comments people left on my PR" }
→ github.review_comments.list  score=0.94 ...

describe_capabilities { "capabilityIds": ["github.review_comments.list"] }
→ exact input schema

execute_capability   { "capabilityId": "github.review_comments.list",
                       "arguments":  { ... } }
→ forwarded verbatim to the right server, started on demand

What gets exposed vs. what stays hidden

Highlights

• Local-first. No cloud service, no account, no telemetry. Delete .mcp-nexus/ and all learned state is gone.

• Lazy lifecycle. Downstream servers start only when a task needs them and stop after tiered idle timeouts (hot / warm / cold).

• Hybrid search. BM25 lexical ranking over weighted fields, exact id/tool matching, alias expansion (pr → pull request, configurable), and a pluggable EmbeddingProvider interface for optional semantic layers.

• Adaptive ranking with explanations. Every result carries its signal breakdown; pinned capabilities outrank learned popularity; blocked capabilities are never suggested.

• Sequence prediction. Repeated tool transitions are learned locally and used to boost likely-next capabilities — prediction never auto-executes.

• Zero native dependencies. Storage uses Node's built-in node:sqlite; installing this package never compiles anything.

• Harness-agnostic. Anything that speaks MCP stdio can sit in front of Nexus.

Requirements

• Node.js >= 22.5 (24 LTS recommended)

Documentation

• Configuration reference — every field, resolution order, env substitution

• CLI reference — all commands and flags

• Architecture — modules, scoring model, storage schema

• Harness setup — Claude Code, Cursor, Codex, generic MCP clients

• examples/project-mcp.json — annotated starter config

Development

git clone https://github.com/fyrlabs/mcp-nexus && cd mcp-nexus
npm install
npm run build       # tsc -> dist/
npm run test        # vitest (unit + integration, mirrors src/ structure under src/tests/)
npm run typecheck   # strict tsc, no emit
npm run lint        # eslint

Integration tests spin up the real @modelcontextprotocol/server-everything package as a downstream stdio server and route executions through a full runtime — they skip automatically if the package cannot be resolved.

See AGENTS.md for contribution conventions (commits, versioning, structure).

Privacy

Nexus stores configuration caches, indexes, and analytics in .mcp-nexus/ (or your XDG data dir). Nothing is sent anywhere by the router itself. If you configure an external embedding provider, only capability text (titles/descriptions/keywords) would be sent there — never arguments, secrets, or analytics. Raw tool arguments are never persisted.

License

Apache-2.0