# dsk-dev-ai/mcp-nexus architecture

> Architecture diagram of the GitHub repository dsk-dev-ai/mcp-nexus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dsk-dev-ai/mcp-nexus
- Repository: https://github.com/dsk-dev-ai/mcp-nexus

## Overview

MCP Nexus is an MCP tool discovery, routing, and safe-execution gateway. An MCP client connects through stdio or Streamable HTTP; the server exposes registry, discovery, routing, approval, and invocation operations. Routing selects a registered tool, policy checks its permission scopes, and approved calls execute over local/stdio, Docker, or HTTP transports. The repository also provides operator CLI and dashboard interfaces, activity logging, and optional LLM routing. Some links reflect README or SOURCE INDEX references because implementation excerpts are partial.

Main entry points: [`src/server/server.ts`](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/server/server.ts) (MCP server), [`src/dashboard/server.ts`](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/dashboard/server.ts) (Dashboard API), [`src/cli.ts`](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/cli.ts) (Operator CLI), [`src/registry/registry.ts`](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/registry/registry.ts) (Tool registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway &amp; operations"]
  node_mcpserver["MCP server<br/>[server.ts]"]
  node_httpgateway["HTTP gateway<br/>[httpGateway.ts]"]
  node_cli["Operator CLI<br/>[cli.ts]"]
  node_dashboard["Dashboard API<br/>[server.ts]"]
  node_config["Configuration<br/>[config.ts]"]
end

subgraph group_catalog["Tool catalog"]
  node_manifest["Tool manifests<br/>[manifest.ts]"]
  node_registry[("Tool registry<br/>[registry.ts]")]
end

subgraph group_routing["Discovery &amp; routing"]
  node_router["Router coordinator<br/>[index.ts]"]
  node_heuristic["Heuristic router<br/>[heuristic.ts]"]
  node_intents["Intent overlay<br/>[intents.ts]"]
  node_semantic["Semantic router<br/>[semantic.ts]"]
  node_llm["LLM router<br/>[llm.ts]"]
end

subgraph group_safety["Policy &amp; execution"]
  node_policy["Policy engine<br/>[policy.ts]"]
  node_scopes["Permission scopes<br/>[scopes.ts]"]
  node_approvals[("Approval store<br/>[approvals.ts]")]
  node_executor["Tool executor<br/>[executor.ts]"]
end

subgraph group_observability["Operations &amp; plugins"]
  node_activity[("Activity log<br/>[logger.ts]")]
  node_sdk["Plugin interfaces<br/>[interfaces.ts]"]
  node_benchmark["Router benchmark<br/>[suite.ts]"]
end

node_client(("MCP client"))
node_tool(("MCP tools"))

node_client -->|"connects stdio"| node_mcpserver
node_client -->|"connects HTTP"| node_httpgateway
node_httpgateway -->|"uses server"| node_mcpserver
node_cli -->|"loads settings"| node_config
node_cli -->|"manages tools"| node_registry
node_cli -->|"starts gateway"| node_httpgateway
node_cli -->|"starts dashboard"| node_dashboard
node_cli -->|"runs benchmark"| node_benchmark
node_cli -->|"parses manifests"| node_manifest
node_mcpserver -->|"reads and updates"| node_registry
node_mcpserver -->|"routes requests"| node_router
node_mcpserver -->|"checks permissions"| node_policy
node_mcpserver -->|"derives scopes"| node_scopes
node_mcpserver -->|"requests approval"| node_approvals
node_mcpserver -->|"executes calls"| node_executor
node_mcpserver -->|"records activity"| node_activity
node_manifest -->|"validates entries"| node_registry
node_router -->|"tries provider"| node_heuristic
node_router -->|"falls back"| node_semantic
node_router -.->|"optional fallback"| node_llm
node_heuristic -->|"matches intent"| node_intents
node_heuristic -->|"scores tools"| node_registry
node_semantic -->|"scores tools"| node_registry
node_dashboard -->|"serves tool data"| node_registry
node_dashboard -->|"routes queries"| node_router
node_dashboard -->|"resolves requests"| node_approvals
node_dashboard -->|"manages policy"| node_policy
node_dashboard -->|"uses executor"| node_executor
node_dashboard -->|"shows activity"| node_activity
node_policy -->|"checks grants"| node_approvals
node_executor -->|"executes transport"| node_tool
node_sdk -->|"defines plugin contract"| node_registry
node_sdk -->|"defines plugin contract"| node_executor
node_sdk -->|"defines plugin contract"| node_policy

click node_mcpserver "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/server/server.ts"
click node_httpgateway "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/server/httpGateway.ts"
click node_cli "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/cli.ts"
click node_dashboard "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/dashboard/server.ts"
click node_config "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/config.ts"
click node_manifest "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/registry/manifest.ts"
click node_registry "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/registry/registry.ts"
click node_router "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/router/index.ts"
click node_heuristic "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/router/heuristic.ts"
click node_intents "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/router/intents.ts"
click node_semantic "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/router/semantic.ts"
click node_llm "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/router/llm.ts"
click node_policy "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/policy/policy.ts"
click node_scopes "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/policy/scopes.ts"
click node_approvals "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/policy/approvals.ts"
click node_executor "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/executor/executor.ts"
click node_activity "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/telemetry/logger.ts"
click node_sdk "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/sdk/interfaces.ts"
click node_benchmark "https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/bench/suite.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcpserver,node_httpgateway,node_cli,node_dashboard,node_config,node_client toneBlue
class node_manifest,node_registry toneAmber
class node_router,node_heuristic,node_intents,node_semantic,node_llm toneMint
class node_policy,node_scopes,node_approvals,node_executor toneRose
class node_activity,node_sdk,node_benchmark,node_tool toneIndigo
```

## Components

### Gateway & operations

- [MCP server](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/server/server.ts): `src/server/server.ts`
- [HTTP gateway](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/server/httpGateway.ts): `src/server/httpGateway.ts`
- [Operator CLI](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/cli.ts): `src/cli.ts`
- [Dashboard API](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/dashboard/server.ts): `src/dashboard/server.ts`
- [Configuration](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/config.ts): `src/config.ts`

### Tool catalog

- [Tool manifests](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/registry/manifest.ts): `src/registry/manifest.ts`
- [Tool registry](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/registry/registry.ts): `src/registry/registry.ts`

### Discovery & routing

- [Router coordinator](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/router/index.ts): `src/router/index.ts`
- [Heuristic router](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/router/heuristic.ts): `src/router/heuristic.ts`
- [Intent overlay](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/router/intents.ts): `src/router/intents.ts`
- [Semantic router](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/router/semantic.ts): `src/router/semantic.ts`
- [LLM router](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/router/llm.ts): `src/router/llm.ts`

### Policy & execution

- [Policy engine](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/policy/policy.ts): `src/policy/policy.ts`
- [Permission scopes](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/policy/scopes.ts): `src/policy/scopes.ts`
- [Approval store](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/policy/approvals.ts): `src/policy/approvals.ts`
- [Tool executor](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/executor/executor.ts): `src/executor/executor.ts`

### Operations & plugins

- [Activity log](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/telemetry/logger.ts): `src/telemetry/logger.ts`
- [Plugin interfaces](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/sdk/interfaces.ts): `src/sdk/interfaces.ts`
- [Router benchmark](https://github.com/dsk-dev-ai/mcp-nexus/blob/main/src/bench/suite.ts): `src/bench/suite.ts`

### Other components

- **MCP client**
- **MCP tools**

## Connections

- MCP client → MCP server: connects stdio (evidence: `README.md`)
- MCP client → HTTP gateway: connects HTTP (evidence: `README.md`)
- HTTP gateway → MCP server: uses server (evidence: `src/server/httpGateway.ts`)
- Operator CLI → Configuration: loads settings (evidence: `src/cli.ts`)
- Operator CLI → Tool registry: manages tools (evidence: `src/cli.ts`)
- Operator CLI → HTTP gateway: starts gateway (evidence: `src/cli.ts`)
- Operator CLI → Dashboard API: starts dashboard (evidence: `src/cli.ts`)
- Operator CLI → Router benchmark: runs benchmark (evidence: `src/cli.ts`)
- Operator CLI → Tool manifests: parses manifests (evidence: `src/cli.ts`)
- MCP server → Tool registry: reads and updates (evidence: `src/server/server.ts`)
- MCP server → Router coordinator: routes requests (evidence: `src/server/server.ts`)
- MCP server → Policy engine: checks permissions (evidence: `src/server/server.ts`)
- MCP server → Permission scopes: derives scopes (evidence: `src/server/server.ts`)
- MCP server → Approval store: requests approval (evidence: `src/server/server.ts`)
- MCP server → Tool executor: executes calls (evidence: `src/server/server.ts`)
- MCP server → Activity log: records activity (evidence: `src/server/server.ts`)
- Tool manifests → Tool registry: validates entries (evidence: `src/registry/registry.ts`)
- Router coordinator → Heuristic router: tries provider (evidence: `README.md`)
- Router coordinator → Semantic router: falls back (evidence: `README.md`)
- Router coordinator → LLM router: optional fallback (evidence: `README.md`)
- Heuristic router → Intent overlay: matches intent (evidence: `src/router/heuristic.ts`)
- Heuristic router → Tool registry: scores tools (evidence: `src/router/heuristic.ts`)
- Semantic router → Tool registry: scores tools (evidence: `src/router/semantic.ts`)
- Dashboard API → Tool registry: serves tool data (evidence: `src/dashboard/server.ts`)
- Dashboard API → Router coordinator: routes queries (evidence: `src/dashboard/server.ts`)
- Dashboard API → Approval store: resolves requests (evidence: `src/dashboard/server.ts`)
- Dashboard API → Policy engine: manages policy (evidence: `src/dashboard/server.ts`)
- Dashboard API → Tool executor: uses executor (evidence: `src/dashboard/server.ts`)
- Dashboard API → Activity log: shows activity (evidence: `src/dashboard/server.ts`)
- Policy engine → Approval store: checks grants (evidence: `src/policy/policy.ts`)
- Tool executor → MCP tools: executes transport (evidence: `README.md`)
- Plugin interfaces → Tool registry: defines plugin contract (evidence: `src/sdk/interfaces.ts`)
- Plugin interfaces → Tool executor: defines plugin contract (evidence: `src/sdk/interfaces.ts`)
- Plugin interfaces → Policy engine: defines plugin contract (evidence: `src/sdk/interfaces.ts`)
