nexus-mcp

The MCP server that connects your AI agents to the Nexus platform.

nexus-mcp exposes 62 structured tools across four layers — knowledge access, coordination, governance, and reviews. It communicates exclusively with the Nexus HTTP API and holds no direct database credentials. Installed automatically when you run nexus init.

Installation

nexus-mcp is installed automatically when you run nexus init in your project workspace. The CLI writes the MCP server configuration to your agent config file.

For manual installation or standalone use:

npx @gwdn/nexus-mcp

Or install globally:

npm install -g @gwdn/nexus-mcp

Published on npm as @gwdn/nexus-mcp. Current version: v0.10.3.

Architecture

The MCP server acts as a mediation layer between local agent runtimes and the Nexus HTTP API via the Model Context Protocol (stdio transport).

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

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

Tool layers

The server organizes its 62 tools into four layers:

Layer 1 — Knowledge Access (6 tools)

Layer 2 — Coordination (48 tools)

Layer 3 — Governance (3 tools)

Layer 4 — Reviews (5 tools)

Utility (3 tools)

Tool naming convention

All tools follow the {domain}_{operation} pattern:

Configuration

After nexus init, your agent config contains an entry like:

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

Environment variables

Schema version envelope

Since v0.10.0, structured tool responses are wrapped in a version envelope:

{
  "schema": "nexus.{tool-name}.v1",
  "data": { ... }
}

The schema field identifies the response shape and version, enabling forward-compatible parsing. Currently 12 tools emit this envelope. Tools that return simple confirmations or single-value results may omit the envelope.

Skill lifecycle

Skills are managed centrally in the Nexus platform and delivered to agents at runtime.

How skills are loaded:

• When an agent invokes a skill command (e.g. /nexus-sec-scan), the skill body is loaded live from the Nexus backend via the MCP server — not from local files.
• Skill updates pushed via sk_update take effect immediately for all projects the skill is assigned to. No pull, restart, or re-deployment required.
• The local .nexus/skills/ directory is a workspace cache written by nexus pull. It exists for offline reference and IDE autocompletion, but is never the authoritative source.

When to run nexus pull:

• To update local .nexus/ cache files (AGENTS.md, skill files, agent files) for reference
• After adding new skill assignments in the dashboard
• Not required for skill content updates — agents always fetch the latest version at invocation time

Scope:

• Core skills (project_id = NULL) are tenant-wide and available to all projects. Only platform owners and admins can create or modify them.
• Project-scoped skills belong to a single project and are managed by project admins and editors. They do not appear in other projects unless explicitly promoted to core.

See Skills for descriptions, run-only-on-request skills and permissions.

Changes in v0.10.14 to v0.10.16

v0.10.16

• Short directive rules: pd_create / pd_update accept rule (max 240 characters), rationale (max 2000, never sent to agents), level (must | should), category (commits, language, docs, security, workflow, operations, communication) and sort_order. title, body and priority stay accepted as deprecated aliases. See Directives.
• Catalog references: pd_create takes template_slug or template_id to add a default or optional rule from the platform catalog. Combining a catalog reference with rule fields, or sending neither, is rejected before the backend is called.
• pd_list documents the effective list: each entry has a source (mandatory, flag, template, project); mandatory and flag rules cannot be edited with pd_update.
• Skills: sk_create requires a description (1 to 500 characters); sk_update rejects a blank one. Both accept invocation (model | user).
• project_update: description is one short plain-text sentence (listing subtitle); long-form Markdown goes into readme, which agents see at depth standard.
• Fixed: the server version reported in MCP serverInfo was stuck at 0.10.2; it is now read from the installed package.
• Security: @modelcontextprotocol/sdk floor raised to ^1.31.0 (GHSA-6qxp-vccf-f47h; nexus-mcp does not use the SDK's OAuth client), lockfile refresh, npm audit reports 0 vulnerabilities.

v0.10.15

• task_create / task_update accept an optional category (coderabbit_fix; null clears it).
• doc_classify accepts the classification coderabbit_review.

v0.10.14

• project_id fallback fixed: NEXUS_PROJECT_ID is now applied even when the client omits the project_id key entirely (the common case). Together with nexus-cli 0.28.6, which writes NEXUS_PROJECT_ID into .mcp.json, project-scoped tools work in Claude Code without an explicit project_id.

Role checks (NEXUS-APP 0.16.0)

The backend now enforces roles for skill and directive changes made through MCP:

Auto-ingested scan reports

When agents append a session entry with entry_type set to security_scan or performance_scan, the platform automatically creates a knowledge-base document from the entry summary.

• The ingest document is classified as scan_report and tagged with source auto-scan
• The summary field of the session entry becomes the document body — skills instruct agents to write the complete structured report into this field
• Scan reports appear in the project knowledge base under the scan report classification and are searchable via kb_search

Known issues

task_note actor constraint (fixed in v0.10.1)

nexus_task_note previously returned Database operation failed in some environments. Root cause: the task_notes.actor column is a UUID FK referencing auth.users. Prior versions passed a display name or email string, violating the constraint. Fixed in nexus-mcp v0.10.1 and the nexus-hub backend.

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.

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