Nexus MCP

MCP server for the Gatewarden Nexus platform. Provides the mediation layer between local agent runtimes and the Nexus HTTP API via the Model Context Protocol (stdio transport).

Install

npx @gwdn/nexus-mcp

Or add to your agent's MCP configuration (OpenCode, Claude Code, Cursor, etc.):

{
  "mcpServers": {
    "nexus": {
      "command": "npx",
      "args": ["-y", "@gwdn/nexus-mcp@latest"],
      "env": {
        "NEXUS_API_URL": "https://nexus.gatewarden.eu",
        "NEXUS_PRIVATE_TOKEN": "nxs_pat_..."
      }
    }
  }
}

Architecture

The server exposes 62 tools across 4 layers. All data access goes through the Nexus HTTP API -- the MCP server has no direct database access.

Agent Runtime (OpenCode, Claude, Cursor, ...)
    |
    |  stdio (MCP protocol)
    v
nexus-mcp (this package)
    |
    |  HTTPS (Bearer token auth)
    v
Nexus API (nexus.gatewarden.eu)
    |
    v
Supabase (PostgreSQL + RLS)

Layer 1 -- Knowledge Access (6 tools)

Layer 2 -- Coordination (48 tools)

Directives: short binding rules (ADR-0125)

A directive is one short binding rule. pd_list returns the effective list per project, and every entry carries a source:

Fields for pd_create / pd_update:

title, body and priority are deprecated aliases for rule, rationale and level (high maps to must). The backend no longer accepts the legacy general category.

// project rule
{ "rule": "Write commit messages in English.", "level": "must", "category": "commits" }
// catalog rule
{ "template_slug": "<catalog-slug>" }

Skills: description and invocation (ADR-0124)

sk_create requires description (1 to 500 characters, not blank): one line saying what the skill does and when to use it. Agents pick skills by it. sk_create and sk_update accept an optional invocation:

• model (default): the agent may load the skill on its own.
• user: only on explicit request (/command); rendered as disable-model-invocation for Claude Code.

Layer 3 -- Governance (3 tools)

Layer 4 -- Reviews (5 tools)

Authentication

Identity is resolved once at startup via GET /api/mcp/identity using the NEXUS_PRIVATE_TOKEN as a Bearer token. All subsequent API calls use the same token for authentication. The Nexus backend resolves the token to a user identity and enforces project-scoped RBAC.

Environment Variables

Development

Recommended: Devbox

We recommend using Devbox to get a fully reproducible, isolated development environment with all required tools pre-installed (Node.js 22, git, ripgrep, tmux, lazygit, and more).

Install Devbox (once, system-wide):

curl -fsSL https://get.jetify.com/devbox | bash

Enter the dev shell:

devbox shell

This drops you into a Nix-managed shell with every tool pinned to the versions declared in devbox.json. No global installs, no version drift.

Available Devbox scripts:

Without Devbox, you can still run commands directly:

npm install
npm run typecheck   # TypeScript check
npm test            # Run tests (164 unit + 34 E2E)
npm run build       # Compile to dist/
npm run dev         # Run via tsx (development)
npm start           # Run compiled JS (production)

Project Structure

nexus-mcp/
├── src/
│   ├── server.ts          # MCP server entry point (stdio transport)
│   ├── auth.ts            # Token-based identity resolution via Nexus API
│   ├── nexus-api.ts       # HTTP client for Nexus API (nexusGet, nexusPost)
│   ├── machine-id.ts      # Machine identification for session metadata
│   ├── project-scope.ts   # NEXUS_PROJECT_ID fallback for project-scoped tools
│   ├── version.ts         # Package version for MCP serverInfo (read from package.json)
│   ├── tools/             # 27 tool modules (62 tools total)
│   └── __tests__/         # 17 test files (205 unit + 34 E2E)
├── LICENSE                # Apache-2.0
├── SECURITY.md            # Security policy
├── CONTRIBUTING.md        # Contribution guidelines
└── CODE_OF_CONDUCT.md     # Contributor Covenant

Known Issues

npx cache prevents version upgrade

When using npx to run the MCP server, npm caches the resolved package in ~/.npm/_npx/. Subsequent invocations may continue to use the cached (outdated) version even after a new release is published.

Symptoms: MCP tools report an older version, or new tools/fixes are missing.

Fix: Clear all npx caches for this package before starting your agent:

find ~/.npm/_npx -path "*/node_modules/@gwdn/nexus-mcp" -type d \
  -exec rm -rf {} + 2>/dev/null

Tip: Pin @latest in your MCP config args to always resolve the newest version: ["--yes", "@gwdn/nexus-mcp@latest"]

Related

• Gatewarden Nexus -- Platform (Next.js / Supabase)
• nexus-cli -- Workspace CLI (Rust)
• nexus-link -- Hardware agent (Rust)

License

Apache-2.0 -- Copyright (c) 2026 RelicFrog Holding UG (haftungsbeschraenkt)