MCP Nexus

MCP Nexus es un enrutador inteligente local-first para el Model Context Protocol. Tu harness de IA se conecta a un único endpoint MCP — Nexus — mientras Nexus gestiona todos tus servidores MCP reales entre bastidores: indexa sus herramientas, descubre capacidades bajo demanda, inicia servidores de forma diferida, ejecuta llamadas enrutadas y aprende del uso local para mejorar los resultados con el tiempo.

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)

Por qué

Cada servidor MCP conectado aporta esquemas de herramientas al contexto del modelo. Con diez servidores, estás quemando decenas de miles de tokens en definiciones que el modelo rara vez usa, y la calidad de la selección de herramientas se degrada.

Nexus invierte el modelo: en lugar de empujar cada esquema descendente al contexto, mantiene un índice de capacidades ligero en disco y sirve un pequeño plano de control. El agente descubre capacidades cuando las necesita (search_capabilities), inspecciona esquemas exactos solo para lo que ha seleccionado (describe_capabilities), y ejecuta a través de Nexus (execute_capability). Todo el estado — configuración, índice, analíticas, secuencias aprendidas — vive localmente en .mcp-nexus/.

Related MCP server: Master MCP Server

Inicio rápido

# 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)

Configuración del harness (Claude Code, Cursor, Codex y otros clientes MCP):

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

Nexus encuentra project-mcp.json automáticamente subiendo desde el directorio de trabajo, o pasa --config ./path/to/nexus.json.

Entonces, desde el punto de vista del agente:

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

Qué se expone vs. qué permanece oculto

Destacados

• Local-first. Sin servicio en la nube, sin cuenta, sin telemetría. Elimina .mcp-nexus/ y todo el estado aprendido desaparece.

• Ciclo de vida diferido. Los servidores descendentes se inician solo cuando una tarea los necesita y se detienen tras tiempos de inactividad por niveles (caliente / templado / frío).

• Búsqueda híbrida. Clasificación léxica BM25 sobre campos ponderados, coincidencia exacta de id/herramienta, expansión de alias (pr → pull request, configurable) y una interfaz EmbeddingProvider conectable para capas semánticas opcionales.

• Clasificación adaptativa con explicaciones. Cada resultado lleva su desglose de señales; las capacidades fijadas superan a la popularidad aprendida; las capacidades bloqueadas nunca se sugieren.

• Predicción de secuencias. Las transiciones repetidas de herramientas se aprenden localmente y se usan para impulsar las capacidades más probables a continuación — la predicción nunca se auto-ejecuta.

• Cero dependencias nativas. El almacenamiento usa el node:sqlite integrado de Node; instalar este paquete nunca compila nada.

• Independiente del harness. Cualquier cosa que hable MCP stdio puede situarse delante de Nexus.

Requisitos

• Node.js >= 22.5 (se recomienda 24 LTS)

Documentación

• Referencia de configuración — cada campo, orden de resolución, sustitución de entorno

• Referencia de CLI — todos los comandos y banderas

• Arquitectura — módulos, modelo de puntuación, esquema de almacenamiento

• Configuración del harness — Claude Code, Cursor, Codex, clientes MCP genéricos

• examples/project-mcp.json — configuración inicial anotada

Desarrollo

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

Las pruebas de integración arrancan el paquete real @modelcontextprotocol/server-everything como servidor stdio descendente y enrutan ejecuciones a través de un runtime completo — se omiten automáticamente si el paquete no se puede resolver.

Consulta AGENTS.md para las convenciones de contribución (commits, versionado, estructura).

Privacidad

Nexus almacena cachés de configuración, índices y analíticas en .mcp-nexus/ (o en tu directorio de datos XDG). El propio enrutador no envía nada a ningún sitio. Si configuras un proveedor de embeddings externo, solo se enviaría texto de capacidades (títulos/descripciones/palabras clave) — nunca argumentos, secretos ni analíticas. Los argumentos de herramientas en bruto nunca se persisten.

Licencia

Apache-2.0