Gatewarden Nexus

Documentation

Docs

Reference documentation for the nexus MCP server, CLI client, and platform API.

MCP Server Reference

The nexus-mcp server exposes 38 tools across 4 layers via the Model Context Protocol (stdio transport). It communicates exclusively with the Nexus HTTP API and holds no direct database credentials.

Architecture

Identity is resolved once at startup via GET /api/mcp/identity using a 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

  • Layer 1 — Knowledge Access (5 tools): kb_search, kb_memory, kb_get, kb_related, project_list
  • Layer 2 — Coordination (23 tools): Vault letters (vl_*), tasks (task_*), sessions (session_*), decision comments (dc_*), document ingestion (doc_*), skills (sk_*)
  • Layer 3 — Governance (3 tools): ADR lifecycle — adr_create, adr_submit, adr_decide
  • Layer 4 — Reviews (5 tools): Entity reviews — rv_list, rv_get, rv_create, rv_decide, rv_comment

Tool Naming Convention

All tools follow the {domain}_{operation} pattern. Domain prefixes:

PrefixDomain
kb_*Knowledge
vl_*Vault Letters
task_*Tasks
session_*Sessions
dc_*Decision Comments
doc_*Documents
sk_*Skills
adr_*ADR Governance
rv_*Reviews

Environment Variables

VariableRequiredDescription
NEXUS_API_URLYesNexus API base URL (e.g. https://nexus.gatewarden.eu)
NEXUS_PRIVATE_TOKENYesnxs_pat_* API token for identity resolution

CLI Reference

The nexus CLI is a native Rust binary that manages project scaffolding, authentication, and project binding for agentic workflows. It uses the same API token model as the MCP server.

Commands

nexus loginAuthenticate with a Nexus API token
nexus init [path]Initialize a customer project repository for agentic workflows
nexus init --shadowed-aiInit and add all AI scaffold files to .gitignore
nexus logoutRemove stored credentials
nexus link [--project-id <id>]Bind a project to the current workspace
nexus unlinkRemove project binding from the workspace
nexus pull [--project-id <id>]Pull skills, agent files, and MCP config from the platform
nexus deinit [--force]Remove all AI scaffold files (.nexus/, .claude/, .opencode/, etc.)
nexus skills exportExport enabled skills for the linked project as JSON
nexus statusShow auth, project, and workspace status
nexus preflightRun environment readiness checks (git, node, API, MCP)
nexus config showDisplay current configuration
nexus config set K=VUpdate a configuration value
nexus config pathShow the config file path

Platform API

The Nexus platform exposes a RESTful API under /api/ for all MCP server and CLI communication. The API enforces tenant isolation, project-scoped RBAC, and token-based authentication.

Authentication Model

API tokens use the nxs_pat_* prefix and are passed as Bearer tokens in the Authorization header. Tokens are SHA-256 hashed at rest and resolve to a user identity with tenant and project scope.

RBAC Model

Nexus uses a dual-layer RBAC model: (1) platform-level roles via app_metadata.platform_role (platform_owner, platform_admin), and (2) project-scoped roles via project_memberships (owner, admin, developer, viewer). Customer-level access is managed through customer_memberships.

OpenAPI Schema

A downloadable OpenAPI schema for the Nexus platform API is planned for a future release.

Coming soon

Additional Topics

Getting Started

Soon

Set up your first project, connect agents via the MCP server, and understand the core concepts.

Architecture Guide

Soon

Deep dive into the platform architecture, entity hierarchy, data model, and design decisions.

ADR Governance

Soon

Understand the ADR lifecycle, state machine, and governance workflows for architectural decisions.

Entity Review System

Soon

Learn how the multi-entity review workflow handles approvals, rejections, and comments.

Back to home