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. They do not appear in other projects unless explicitly promoted to core.

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