MCP Nexus

MCP Nexus는 Model Context Protocol을 위한 로컬 우선 지능형 라우터입니다. AI 하네스는 Nexus라는 하나의 MCP 엔드포인트에 연결되고, Nexus가 실제 MCP 서버들을 백그라운드에서 모두 관리합니다. 즉, 도구를 인덱싱하고, 필요 시 기능을 발견하며, 서버를 지연 시작(lazy start)하고, 라우팅된 호출을 실행하며, 로컬 사용 기록을 학습하여 시간이 지날수록 결과 순위를 더 잘 매깁니다.

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)

왜 필요한가

연결된 각 MCP 서버는 모델 컨텍스트에 도구 스키마를 기여합니다. 서버가 10개가 되면 모델이 거의 사용하지 않는 정의에 수만 개의 토큰을 소모하게 되고, 도구 선택 품질도 저하됩니다.

Nexus는 모델을 뒤집습니다. 모든 다운스트림 스키마를 컨텍스트에 밀어 넣는 대신, 가벼운 기능 인덱스를 디스크에 유지하고 작은 제어 평면을 제공합니다. 에이전트는 필요할 때 기능을 발견하고(search_capabilities), 선택한 기능에 대해서만 정확한 스키마를 검사하며(describe_capabilities), Nexus를 통해 실행합니다(execute_capability). 모든 상태(설정, 인덱스, 분석, 학습된 시퀀스)는 .mcp-nexus/에 로컬로 저장됩니다.

Related MCP server: Master MCP Server

빠른 시작

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

하네스 설정(Claude Code, Cursor, Codex 및 기타 MCP 클라이언트):

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

Nexus는 작업 디렉터리에서 위로 올라가며 project-mcp.json을 자동으로 찾거나, --config ./path/to/nexus.json을 전달할 수 있습니다.

그런 다음 에이전트 관점에서:

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

노출되는 것 vs. 숨겨지는 것

주요 특징

• 로컬 우선. 클라우드 서비스 없음, 계정 없음, 텔레메트리 없음. .mcp-nexus/를 삭제하면 학습된 모든 상태가 사라집니다.

• 지연 수명 주기. 다운스트림 서버는 작업이 필요할 때만 시작되고 계층형 유휴 시간 초과(핫 / 웜 / 콜드) 후 중지됩니다.

• 하이브리드 검색. 가중 필드에 대한 BM25 어휘 순위, 정확한 id/도구 일치, 별칭 확장(pr → pull request, 구성 가능), 선택적 의미 계층을 위한 플러그형 EmbeddingProvider 인터페이스.

• 설명이 포함된 적응형 순위. 모든 결과는 신호 분석을 제공합니다. 고정된 기능은 학습된 인기도보다 우선하며, 차단된 기능은 절대 제안되지 않습니다.

• 시퀀스 예측. 반복되는 도구 전환을 로컬에서 학습하고 이를 사용하여 다음에 올 가능성이 높은 기능을 부스트합니다. 예측은 절대 자동 실행되지 않습니다.

• 네이티브 종속성 없음. 저장소는 Node의 내장 node:sqlite를 사용합니다. 이 패키지를 설치해도 컴파일되는 것은 없습니다.

• 하네스에 구애받지 않음. MCP stdio를 지원하는 모든 것은 Nexus 앞에 놓을 수 있습니다.

요구 사항

• Node.js >= 22.5 (24 LTS 권장)

문서

• 설정 참조 — 모든 필드, 해석 순서, env 대체

• CLI 참조 — 모든 명령 및 플래그

• 아키텍처 — 모듈, 점수 모델, 저장소 스키마

• 하네스 설정 — Claude Code, Cursor, Codex, 일반 MCP 클라이언트

• examples/project-mcp.json — 주석이 달린 시작 설정

개발

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

통합 테스트는 실제 @modelcontextprotocol/server-everything 패키지를 다운스트림 stdio 서버로 사용하고 전체 런타임을 통해 실행을 라우팅합니다. 패키지를 해석할 수 없으면 자동으로 건너뜁니다.

기여 규칙(커밋, 버전 관리, 구조)은 AGENTS.md를 참조하세요.

개인정보 보호

Nexus는 설정 캐시, 인덱스, 분석을 .mcp-nexus/(또는 XDG 데이터 디렉터리)에 저장합니다. 라우터 자체는 아무 곳에도 아무것도 보내지 않습니다. 외부 임베딩 제공자를 구성하는 경우, 기능 텍스트(제목/설명/키워드)만 해당 제공자에게 전송됩니다. 인수, 비밀 정보, 분석은 절대 전송되지 않습니다. 원시 도구 인수는 절대 영구 저장되지 않습니다.

라이선스

Apache-2.0