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

# MCP Server

> Give AI coding agents scoped, backend-enforced access to your Nexus configs, flags, and secrets over the Model Context Protocol.

The Westyx Nexus MCP server (`@westyx-nexus/mcp`) is a [Model Context Protocol](https://modelcontextprotocol.io) server that lets an AI coding agent (Claude, Cursor, Copilot, Gemini, ...) read your project's configs, feature flags, and secrets - and, where allowed, write them - directly from the editor, over stdio.

One universal install works for **every** MCP-capable assistant and **every project across every tenant** you belong to. There is no per-project install and no key to paste in: run the `nexus_login` tool once and you are signed in.

All authority is **backend-enforced**: the server is a thin bridge that maps MCP tool calls to the Nexus `/v1/mcp/*` API, authenticated with a per-user MCP key, addressing the project and environment on each call. It never decides what is allowed - the backend does, on every request.

```bash theme={null}
npx @westyx-nexus/mcp
```

> [!NOTE]
>
> Published to the **Westyx GitLab Package Registry** (public, no token needed), not the public npm registry - point the `@westyx-nexus` scope at it first or `npx` returns a 404. See [Installation](https://docs.westyx.dev/mcp/installation.md).

## Quick start

1. Add the server to your assistant (see [Installation](https://docs.westyx.dev/mcp/installation.md)).
2. Ask the assistant to run the **`nexus_login`** tool. It returns a URL + code; open it, approve, and your key is stored automatically.
3. Tell the server which project to use - drop a `.nexus-mcp.json` in your repo or run the `list_projects` tool.
4. Ask away: "list the secrets for the api service", etc.

No key needs to be configured beforehand. For headless / CI use, set `NEXUS_MCP_KEY` instead of running `nexus_login`.

## Security model

* **The MCP key is your identity, not a project secret.** It is platform-wide and tenant-agnostic; the project and environment are resolved per call.
* **Two-tier, additive authorization (backend-side):**
  * **Baseline** - on a project with MCP enabled where you hold a developer-type role, you get full read/write/reveal on **your own personal dev environment** only.
  * **Explicit grants** - an owner or manager can grant you scope on shared environments (`develop` and up) with separate **create** (add new items), **write** (modify existing), and **reveal** permissions. **Delete is never grantable on shared environments** - it works only on your personal dev environment.
* **Production is a hard NO.** Revealing, creating, writing, or deleting in production is rejected regardless of any grant. [Environment promotion](https://docs.westyx.dev/features/environment-promotion.md) is not an MCP capability either: items reach production only when a person accepts a promotion in the admin console.
* **Reveal is opt-in + confirmed.** `get_secret` returns metadata only by default; cleartext requires `confirm: true` and a `key_echo` matching the key name, and is still subject to the grant's reveal flag and the production block.
* The MCP key is stored with `0600` permissions and never logged. `nexus_login` never writes your Keycloak tokens to disk - only the narrow, separately revocable MCP key.

## What's new in v0.2.0

* **Config & flag write tools.** New `set_config`, `delete_config`, `set_flag`, and `delete_flag` tools - your AI can now create and modify configs and feature flags, not just secrets. `set_flag` edits name / description / enabled only; scheduling, rollout %, and targeting stay admin-UI only and are preserved untouched on update.
* **Create vs. modify are separate permissions.** Creating a not-yet-existing item needs your grant's **create** permission; modifying an existing one needs **write**.
* **Delete is personal-dev-env only.** All delete tools (config / flag / secret) work only on your own personal dev environment - never on shared environments, regardless of grant. `delete_secret` is tightened to match.
* **16 tools** - 2 auth, `list_projects`, 6 read, 7 reveal/write - all backend-enforced.

## What's new in v0.1.0

* **Keyless install + `nexus_login`.** Sign in via the browser (Keycloak device flow); a per-user MCP key is minted and stored locally. `NEXUS_MCP_KEY` remains the headless / CI fallback.
* **One universal install for all projects and tenants.** The MCP key is your identity; the project is addressed per call (`.nexus-mcp.json`, the `project` argument, or `list_projects`), and the environment defaults to your personal dev environment.
* **`--dev` flag** targets the dev environment; production is the default.

Continue with [Installation](https://docs.westyx.dev/mcp/installation.md) and the [Tools](https://docs.westyx.dev/mcp/tools.md) reference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.