Skip to main content
Glama
deenesjakoruzh
fyrlabs

mcp-nexus

by fyrlabs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

MCP Nexus

CI npm version License

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/.

How much this helps depends on your harness

Some harnesses now defer tool definitions themselves, so it is worth being precise about what Nexus adds on top.

Harness

Without Nexus

What Nexus adds

GitHub Copilot / VS Code

Hard cap of 128 tools per request. Past it, agent mode refuses to run until you manually turn tools off.

Downstream tool count stops mattering: the harness sees 4 tools regardless of how many servers you run.

Claude Code (tool search on by default)

Tool definitions are deferred, but every tool name plus each server's instructions still load at session start, and every configured server is connected in the background.

Names collapse to 4. Servers stay unspawned until something actually calls them.

Cursor, Windsurf, older models, Bedrock / Azure / proxied setups

Every schema loads upfront.

The full reduction below.

On a synthetic 20-server, 400-tool ecosystem (npm run bench), the schemas total roughly 52,000 tokens against 544 for the Nexus control plane. That number is the upfront-loading case; where the harness already defers definitions, the saving is smaller but the lazy process startup and the tool-count ceiling still apply.

Context is not the only reason to use it. Nexus also gives you lazy server startup, per-capability policies, health quarantine, and local usage learning, none of which a harness provides.

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

Exposed to the model

Kept local

Control-plane tools

4 fixed tools

—

Capability metadata

Only on search (small records: id, title, description, risk, score)

Full index in SQLite

Tool input schemas

Only for described capabilities

Persisted at index time

Usage analytics

—

Local events + aggregates

Secrets

Never (redacted from logs and CLI output)

Resolved in-process, passed to the downstream server env

Highlights

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

  • Lazy execution lifecycle. After the one-time background index, servers start only when a task needs them, stop after tiered idle timeouts (hot / warm / cold), and are never stopped mid-call. A server that keeps failing to start is quarantined for a short, growing window instead of costing a startup timeout on every call.

  • Hybrid search. BM25 lexical ranking over weighted fields, exact id/tool matching, alias expansion (pr → pull request, configurable), plus optional semantic search: point routing.semantic at any OpenAI-compatible embeddings endpoint (cloud, or fully-local via Ollama) — embeddings are batched, cached in SQLite, and the system falls back to lexical automatically when the endpoint is down (a circuit breaker opens after two consecutive failures and suppresses calls for 60s before probing again). Search queries are sent to that endpoint too — see Privacy.

  • Risk policies and optional tool promotion. Deny or flag capabilities by risk class, and (opt-in, routing.promotion: "session") expose discovered tools directly as nexus__<server>__<tool> after discovery (argument schemas are reconstructed from the downstream JSON schema; exotic keywords are simplified). Risk classes come from a keyword heuristic over each tool's own name and description, so treat policies as a workflow guardrail against accidents, not as a security boundary against a hostile server. See risk classification.

  • 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.

  • Context reduction, measured. npm run bench builds a synthetic ecosystem and measures the real numbers: at 2,000 capabilities the full downstream schema payload is ~130k tokens versus ~540 tokens for the Nexus control plane (≈99.6% estimated reduction), with index-level search p95 at 0.05ms against the spec's 50ms budget (full router path adds policy and stats lookups).

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

Requirements

  • Node.js >= 22.13 (24 LTS recommended; node:sqlite must be available unflagged)

Documentation

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). Raw tool arguments are never persisted. With the default settings (routing.semantic.provider: "null") the router makes no network requests at all.

Semantic search is the one feature that sends data off the machine, and only if you turn it on. Pointing routing.semantic at an OpenAI-compatible endpoint sends two kinds of text there:

  • Capability text (titles, descriptions, keywords) at index time, once per tool.

  • Your search query on every search, to embed it for comparison. Queries are written by the agent from your conversation, so treat them as conversation content.

Tool arguments, tool results, secrets, and analytics are never sent. If the query text matters to you, use provider: "hash" (fully local, no network) or point baseUrl at a local Ollama instance.

License

Apache-2.0

Available Tools

4 tools
describe_capabilitiesDescribe capabilitiesB

Return the full metadata and input schemas for the given capability IDs.

ParametersJSON Schema
NameRequiredDescriptionDefault
capabilityIdsYesCapability IDs returned by search_capabilities

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It clearly states the tool returns metadata and schemas, which is a read-like operation, but it doesn't disclose any limitations, such as whether invalid IDs cause errors or whether the returned data is verbose. The description is accurate but sparse on behavioral nuances.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single clear sentence that is entirely on-topic. It front-loads the action and object, with no filler. Could earn a 5 if it referenced a sibling or workflow, but it remains efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema and no annotations, the description is the sole source of behavioral information. It tells the agent what the tool returns, but for a metadata-inspection tool, an agent might need to know whether it can be used before executing a capability or how errors are surfaced. Still, for a simple lookup tool, this is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents the 'capabilityIds' parameter. The description adds the purpose context ('full metadata and input schemas') but doesn't add format or constraint details beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Return') and resource ('metadata and input schemas') for given capability IDs. It distinguishes itself from sibling tools like search_capabilities (which likely finds capabilities) and execute_capability (which runs them), though it doesn't explicitly name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: given capability IDs, retrieve metadata. The parameter description notes IDs come from search_capabilities, implicitly showing a workflow step. However, it doesn't state when to use this vs execute_capability or search_servers, leaving some inference needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

execute_capabilityExecute capabilityA

Execute a downstream MCP capability by ID. The underlying server is started on demand and the arguments are forwarded verbatim.

ParametersJSON Schema
NameRequiredDescriptionDefault
argumentsNoArguments matching the tool's input schema (see describe_capabilities)
capabilityIdYesCapability ID to execute

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the transparency burden. It discloses two genuine behaviors: the backing server is 'started on demand' (affecting latency/resource use) and arguments are 'forwarded verbatim' (no transformation). It does not mention output shape, error behavior, or potential side effects of the downstream capability, so coverage is partial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each adding distinct information: the core action and two behavioral caveats. No redundant or filler wording, and the most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The definition is largely sufficient for a simple pass-through invocation, and the arguments schema points to describe_capabilities for the input contract. However, there is no output schema or description of the return value/error behavior, so an agent does not know what to expect after invocation. This is a moderate gap given no annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents both parameters completely (100% coverage), so the baseline is 3. The description's 'arguments are forwarded verbatim' reinforces the arguments parameter's semantics, but adds no new parameter-specific detail beyond the schema, which already tells the agent to see describe_capabilities for the expected argument shape.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action – 'Execute a downstream MCP capability by ID' – with a clear verb and resource. The 'by ID' scoping and the 'downstream MCP' qualifier distinguish it from siblings like describe_capabilities and search_capabilities, which are informational rather than invocational.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: you invoke this when you have a capability ID and want to run it, and the 'forwarded verbatim' phrasing indicates arguments should already conform to the target schema. It does not explicitly list exclusions or alternatives, but the sibling names make the distinction clear. This is adequate context without explicit when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_capabilitiesSearch capabilitiesA

Search every indexed downstream MCP capability by natural language, keywords, tags, server id, or capability id. Returns lightweight metadata only.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of results to return
queryYesNatural language or keyword query describing the capability you need

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are absent, so the description carries the full behavioral burden. It usefully discloses that the tool is a search operation returning 'lightweight metadata only', which implies read-only behavior and no full payload or execution. However, it does not mention result shape, pagination behavior, indexing caveats, or what happens when nothing matches.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense, front-loaded sentence carries the purpose, scope, search dimensions, and return nature with no filler. Every phrase earns its place, and the most important information appears first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter search tool, the description is largely complete: the query semantics are enriched, the limit is documented in the schema, and the return type is characterized. The main remaining gap is the absence of an output schema or a more concrete list of returned metadata fields, but this does not prevent a capable agent from selecting and invoking the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the baseline is 3. The description adds genuine meaning beyond the schema by expanding query to include tags, server id, and capability id as acceptable forms, which the schema's 'natural language or keyword query' line does not convey. The limit parameter remains fully covered by its schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the exact action ('Search'), the resource ('every indexed downstream MCP capability'), and the query dimensions (natural language, keywords, tags, server id, capability id), which clearly differentiates it from search_servers and the other sibling tools. It also specifies the return nature ('lightweight metadata only'), leaving no ambiguity about what the tool is for.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The scope phrasing implies when to use it—whenever you need to discover a capability across indexed downstream MCPs—but it never explicitly states when not to use it or points to describe_capabilities/execute_capability/search_servers. Sibling names hint at those alternatives, but the description itself provides no routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_serversSearch serversA

Rank configured downstream MCP servers against a domain-level query. Useful before drilling into capability search.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesDomain-level query such as 'project management'

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses the core behavior (ranking servers, not modifying them) and the scoping to configured downstream MCP servers. It doesn't cover details like ranking criteria, read-only guarantees, or response shape, but the disclosed behavior is accurate and non-contradictory.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler. The core action is front-loaded, and the usage context is a single additional clause that earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter search tool with no output schema, the description is largely complete: it states what is ranked, the query type, and when to use it. The main gap is the absence of any mention of the return value, which the absence of an output schema makes slightly more relevant.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the query parameter is already documented in the schema. The description reinforces 'domain-level query' but adds no parameter format or constraints beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses a specific verb ('Rank'), a specific resource ('configured downstream MCP servers'), and a clear scope ('domain-level query'). It also positions itself against the capability-search siblings, so an agent can distinguish it from search_capabilities without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description gives explicit temporal guidance: use this before drilling into capability search. It doesn't explicitly name the alternative or list when-not-to-use cases, but the context is clear enough given sibling names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.10.0
    • First observeddescribe_capabilities
    • First observedexecute_capability
    • First observedsearch_capabilities
    • First observedsearch_servers
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 4 tools

Disambiguation4/5

Each tool has a clear operational role: searching servers, searching capabilities, describing schemas, and executing. search_servers and search_capabilities are adjacent but their descriptions clearly separate domain-level server ranking from capability-level search.

Naming Consistency4/5

All tool names follow a consistent verb_noun snake_case pattern. The only minor inconsistency is 'capabilities' being plural in search/describe but singular in execute_capability.

Tool Count5/5

Four tools is well-scoped for a gateway or meta-server: discover servers, discover capabilities, inspect schemas, and execute. There is no redundancy or unnecessary bloat.

Completeness4/5

The discover → describe → execute workflow is covered end-to-end. Minor gaps such as explicit list-all-server or dedicated server metadata retrieval are missing, but search_servers can largely cover discovery needs.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcphub

    samanhappy
    A
    license
    Not graded
    quality
    A
    maintenance
    A unified hub for centrally managing and dynamically orchestrating multiple MCP servers/APIs into separate endpoints with flexible routing strategies.
    547 npm
    2,426
    Apache 2.0

  • Master MCP Server

    Jakedismo
    F
    license
    Not graded
    quality
    Not graded
    maintenance
    Aggregates multiple MCP servers behind a single, secure endpoint with unified tool/resource discovery, OAuth authentication, and resilient request routing. Enables users to manage and interact with multiple MCP backends through one centralized interface with load balancing and circuit breakers.
    2
    -

  • Smart MCP Proxy

    Dumbris
    A
    license
    Not graded
    quality
    D
    maintenance
    Federating gateway for AI agents to discover and call tools from multiple MCP servers with intelligent search and dynamic tool registration.
    39
    MIT