Installation

@westyx-nexus/mcp is published to the Westyx GitLab Package Registry, not the public npm registry. The registry is public - no auth token needed - you just have to point the @westyx-nexus scope at it, otherwise npx @westyx-nexus/mcp fails with a 404.

Set up the GitLab registry

Add this one line to your ~/.npmrc:

@westyx-nexus:registry=https://gitlab.com/api/v4/groups/131002782/-/packages/npm/

131002782 is the westyx/nexus group ID. The ~/.npmrc (in your home directory) is what npx reads when the AI client launches the server. No token, no login - the packages are publicly readable.

A scope maps to exactly one registry. This is the group registry, so a single @westyx-nexus scope serves every Westyx Nexus package - this MCP server and the browser SDKs alike. Use the same line everywhere.

Register the server

The command is always npx -y @westyx-nexus/mcp (add --dev to target the dev environment instead of production).

Claude Code

claude mcp add nexus -- npx -y @westyx-nexus/mcp
# dev:
claude mcp add nexus-dev -- npx -y @westyx-nexus/mcp --dev

Cursor / Claude Desktop / Gemini CLI / Windsurf (JSON)

~/.cursor/mcp.json, claude_desktop_config.json, ~/.gemini/settings.json, etc.:

{
  "mcpServers": {
    "nexus": {
      "command": "npx",
      "args": ["-y", "@westyx-nexus/mcp"]
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.nexus]
command = "npx"
args = ["-y", "@westyx-nexus/mcp"]

GitHub Copilot (VS Code)

.vscode/mcp.json:

{
  "servers": {
    "nexus": {
      "command": "npx",
      "args": ["-y", "@westyx-nexus/mcp"]
    }
  }
}

Authentication

nexus_login (default) - a browser-based Keycloak device flow. Ask your assistant to run the tool; it returns a verification URL + code. Once you approve, an MCP key is minted and stored on this machine (0600). nexus_logout removes it. To fully revoke a key server-side, delete it on your Nexus profile page (User settings -> MCP keys).
NEXUS_MCP_KEY (headless / CI fallback) - if set, it always wins over the stored key. No browser needed. Mint a key on your profile page:

{
  "mcpServers": {
    "nexus": {
      "command": "npx",
      "args": ["-y", "@westyx-nexus/mcp"],
      "env": { "NEXUS_MCP_KEY": "wxm_xxxxxxxxxxxxxxxx" }
    }
  }
}

The key is resolved per request, so running nexus_login mid-session takes effect on the very next tool call - no restart.

Choosing the project

The effective project for each tool call is resolved in this order:

An explicit project argument on the tool call (a project UUID).
A .nexus-mcp.json file in the working directory (or any parent), committed to your repo - it is not a secret:
{ "project": "11111111-1111-1111-1111-111111111111" }
A home registry (<config dir>/projects.json) mapping repo paths to UUIDs.

Run the list_projects tool to discover the UUIDs (and your personal environment) for every project you can access. The environment is optional on every tool - omit it to use your personal dev environment, or pass develop / staging / etc. if your grant allows.

Environment selection

Variable / flag	Default	Description
`--dev` / `NEXUS_ENV=dev`	production	Target the dev environment.
`NEXUS_MCP_KEY`	(unset)	Headless / CI key; overrides the stored credential.
`NEXUS_BASE_URL`	per-env host	Override the API base URL (local / staging).
`NEXUS_CONFIG_HOME`	per-OS config dir	Override where credentials and the registry are stored.

Restart the client after changing its config; the Nexus tools then appear in its tool list. See the Tools reference for what each one does.

Getting started

How-to guides

Concepts

AI MCP Server

Beta

Set up the GitLab registry

Register the server

Claude Code

Cursor / Claude Desktop / Gemini CLI / Windsurf (JSON)

Codex CLI

GitHub Copilot (VS Code)

Authentication

Choosing the project

Environment selection

​Set up the GitLab registry

​Register the server

​Claude Code

​Cursor / Claude Desktop / Gemini CLI / Windsurf (JSON)

​Codex CLI

​GitHub Copilot (VS Code)

​Authentication

​Choosing the project

​Environment selection

Set up the GitLab registry

Register the server

Claude Code

Cursor / Claude Desktop / Gemini CLI / Windsurf (JSON)

Codex CLI

GitHub Copilot (VS Code)

Authentication

Choosing the project

Environment selection