> ## Documentation Index
> Fetch the complete documentation index at: https://docs.westyx.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install and configure the Westyx Nexus MCP server in your AI coding client.

`@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.

<Note>
  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.
</Note>

## Register the server

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

### Claude Code

```bash theme={null}
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.:

```json theme={null}
{
  "mcpServers": {
    "nexus": {
      "command": "npx",
      "args": ["-y", "@westyx-nexus/mcp"]
    }
  }
}
```

### Codex CLI

`~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.nexus]
command = "npx"
args = ["-y", "@westyx-nexus/mcp"]
```

### GitHub Copilot (VS Code)

`.vscode/mcp.json`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

1. An explicit **`project`** argument on the tool call (a project UUID).

2. A **`.nexus-mcp.json`** file in the working directory (or any parent), committed to your repo - it is not a secret:

   ```json theme={null}
   { "project": "11111111-1111-1111-1111-111111111111" }
   ```

3. 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](tools) reference for what each one does.