---
title: Nx MCP Server Reference
description: Complete reference for the Nx MCP (Model Context Protocol) server, including available tools, configuration options, and setup instructions for various AI clients.
sidebar:
  order: 5
  label: Nx MCP Server
filter: 'type:References'
---

The Nx MCP server is a [Model Context Protocol](https://modelcontextprotocol.io/introduction) implementation that connects AI agents to systems they can't easily reach on their own: Nx Cloud CI pipelines, self-healing fixes, task monitoring, and up-to-date Nx documentation.

{% aside type="tip" title="Quick Setup" %}
To configure your Nx workspace for AI agents (MCP, skills, and more), run `npx nx configure-ai-agents`. See the [AI Integration guide](/docs/getting-started/ai-setup) for details.
{% /aside %}

{% aside type="note" title="MCP + Skills" %}
The Nx MCP server works best alongside [agent skills](/docs/features/enhance-ai). Skills handle domain knowledge — workspace exploration, code generation, task execution — while the MCP server provides connectivity to Nx Cloud and task monitoring. For background on this approach, see our blog post on [why we deleted most of our MCP tools](/blog/why-we-deleted-most-of-our-mcp-tools).
{% /aside %}

For an overview of how Nx gives coding agents workspace context, see
[enhance your AI coding agent](/docs/features/enhance-ai).

## Installation

There are a few ways to setup the Nx MCP server.

### via .mcp.json

{% tabs syncKey="nx-version" %}
{% tabitem label="Nx >= 21.4" %}

```json
// .mcp.json
{
  "servers": {
    "nx-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["nx", "mcp"]
    }
  }
}
```

{% /tabitem %}
{% tabitem label="Nx < 21.4" %}

```json
// .mcp.json
{
  "servers": {
    "nx-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["nx-mcp@latest"]
    }
  }
}
```

{% /tabitem %}
{% /tabs %}

### Via Nx Console extension

If you're using Cursor or VS Code, install the [Nx Console extension](/docs/getting-started/editor-setup) which automatically manages the MCP server for you.

## Client-specific setup

> If your preferred client is not listed, configure your client to run `npx nx mcp` (Nx >= 21.4) or `npx nx-mcp@latest` (older versions) to start the Nx MCP server.

### Claude Code

{% aside type="tip" title="Using an agent sandbox?" %}
Claude Code, Codex, and the GitHub Copilot CLI all sandbox the commands they run, and each blocks Unix sockets until you allow them. See [Nx fails in an AI agent sandbox](/docs/kb/nx-sandbox-unix-sockets) for the per-agent setting.
{% /aside %}

{% tabs syncKey="nx-version" %}
{% tabitem label="Nx >= 21.4" %}

```shell
claude mcp add nx-mcp npx nx mcp
```

{% /tabitem %}
{% tabitem label="Nx < 21.4" %}

```shell
claude mcp add nx-mcp npx nx-mcp@latest
```

{% /tabitem %}
{% /tabs %}

### VS Code

{% tabs syncKey="nx-version" %}
{% tabitem label="Nx >= 21.4" %}

```shell
code --add-mcp '{"name":"nx-mcp","command":"npx","args":["nx","mcp"]}'
```

{% /tabitem %}
{% tabitem label="Nx < 21.4" %}

```shell
code --add-mcp '{"name":"nx-mcp","command":"npx","args":["nx-mcp"]}'
```

{% /tabitem %}
{% /tabs %}

Alternatively, configure it in your VS Code settings or use the Nx Console extension for automatic setup.

### Cursor

1. Install [Nx Console](/docs/getting-started/editor-setup) from the marketplace
2. You'll receive a notification to "Improve Copilot/AI agent with Nx-specific context"
3. Click "Yes" to configure the MCP server

If you miss the notification, run the `nx.configureMcpServer` command from the command palette (`Ctrl/Cmd + Shift + P`).

### JetBrains IDEs

1. Install [Nx Console](/docs/getting-started/editor-setup) from the marketplace
2. You'll receive a notification to "Improve Copilot/AI agent with Nx-specific context"
3. Click "Yes" to configure the MCP server

If you miss the notification, run the `Nx: Setup MCP Server` command from the command palette (`Ctrl/Cmd + Shift + A`).

## Command-line options

The `nx mcp` command (or `npx nx-mcp` for older versions) accepts the following options:

| Option                  | Alias | Description                                                                                                                         |
| ----------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `[workspacePath]`       | `-w`  | Path to the Nx workspace root. Defaults to the current working directory if not provided.                                           |
| `--transport <type>`    |       | Transport protocol to use: `stdio` (default), `sse`, or `http`                                                                      |
| `--port <port>`         | `-p`  | Port to use for the HTTP/SSE server (default: 9921). Only valid with `--transport sse` or `--transport http`.                       |
| `--tools <patterns...>` | `-t`  | Filter which tools are enabled. Accepts glob patterns including negation (e.g., `"*"`, `"!nx_docs"`, `"ci_*"`)                      |
| `--minimal`             |       | Hide workspace analysis tools (default: `true`). Use `--no-minimal` to expose all tools. See [Minimal Mode](#minimal-mode-default). |
| `--disableTelemetry`    |       | Disable sending of telemetry data                                                                                                   |
| `--debugLogs`           |       | Enable debug logging                                                                                                                |
| `--help`                |       | Display help information                                                                                                            |

### HTTP transport

If you want to host the server instead of communicating via `stdio`, use the `--transport` and `--port` flags:

{% tabs syncKey="nx-version" %}
{% tabitem label="Nx >= 21.4" %}

```shell
npx nx mcp --transport sse --port 9921
```

{% /tabitem %}
{% tabitem label="Nx < 21.4" %}

```shell
npx nx-mcp@latest --transport sse --port 9921
```

{% /tabitem %}
{% /tabs %}

The HTTP transport supports multiple concurrent connections, allowing different clients to connect simultaneously with independent sessions.

### Filtering tools

You can limit which tools are available using the `--tools` option with glob patterns:

{% tabs syncKey="nx-version" %}
{% tabitem label="Nx >= 21.4" %}

```shell
# Enable all tools (default)
npx nx mcp --tools "*"

# Disable specific tools
npx nx mcp --tools "*" "!nx_docs"

# Enable only Nx Cloud CI tools
npx nx mcp --tools "ci_*"

# Enable workspace tools only
npx nx mcp --tools "nx_workspace" "nx_project_details" "nx_docs"
```

{% /tabitem %}
{% tabitem label="Nx < 21.4" %}

```shell
# Enable all tools (default)
npx nx-mcp@latest --tools "*"

# Disable specific tools
npx nx-mcp@latest --tools "*" "!nx_docs"

# Enable only Nx Cloud CI tools
npx nx-mcp@latest --tools "ci_*"

# Enable workspace tools only
npx nx-mcp@latest --tools "nx_workspace" "nx_project_details" "nx_docs"
```

{% /tabitem %}
{% /tabs %}

This is useful when you want to restrict the LLM's capabilities or reduce noise in the tool list.

### Minimal mode (Default)

By default, the MCP server runs in **minimal mode** (`--minimal`), which hides workspace analysis and generator tools. These capabilities are now handled more efficiently by [agent skills](/docs/features/enhance-ai), which provide domain knowledge as incrementally-loaded instructions rather than tool-call-based data dumps. This reduces token usage and keeps the tool list focused on what MCP does best: connectivity to Nx Cloud and running processes.

To restore all tools (e.g., for clients that don't support skills), pass `--no-minimal`:

{% tabs syncKey="nx-version" %}
{% tabitem label="Nx >= 21.4" %}

```shell
npx nx mcp --no-minimal
```

{% /tabitem %}
{% tabitem label="Nx < 21.4" %}

```shell
npx nx-mcp@latest --no-minimal
```

{% /tabitem %}
{% /tabs %}

When the Nx Console extension manages the MCP server in VS Code or Cursor, it automatically enables minimal mode if it detects that agent skills are installed in the workspace.

## Available tools

### Documentation tools

| Tool      | Description                                                                                       |
| --------- | ------------------------------------------------------------------------------------------------- |
| `nx_docs` | Returns documentation sections relevant to user queries about Nx configuration and best practices |

### Task monitoring tools

| Tool                               | Description                                                      |
| ---------------------------------- | ---------------------------------------------------------------- |
| `nx_current_running_tasks_details` | Lists currently running Nx TUI processes and their task statuses |
| `nx_current_running_task_output`   | Returns terminal output for specific running tasks               |

### Visualization tools

| Tool                 | Description                                                                                              |
| -------------------- | -------------------------------------------------------------------------------------------------------- |
| `nx_visualize_graph` | Opens interactive project or task graph visualizations (requires a running IDE instance with Nx Console) |

### Nx Cloud CI tools

These tools enable AI agents to interact with CI pipelines and self-healing capabilities:

| Tool                      | Description                                                                                                                                                 |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ci_information`          | Retrieves CI pipeline execution information from Nx Cloud for the current branch. Returns pipeline status, failed tasks, and self-healing status.           |
| `ci_task_output`          | Retrieves terminal output for a specific CI task (failed or successful), using a runId from `ci_information` or resolving it from the branch / URL context. |
| `update_self_healing_fix` | Apply or reject a self-healing CI fix from Nx Cloud. Records the decision on the suggested fix.                                                             |

### Extended tools (--no-minimal)

The following tools are hidden by default in minimal mode. They're available when running with `--no-minimal`, which is useful for AI clients that don't support skills or instruction files.

#### Workspace tools

| Tool                   | Description                                                                                                                         |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `nx_workspace`         | Returns a readable representation of the project graph and nx.json configuration. Also returns any project graph errors if present. |
| `nx_workspace_path`    | Returns the path to the Nx workspace root                                                                                           |
| `nx_project_details`   | Returns complete project configuration in JSON format for a specific project, including targets, dependencies, and metadata         |
| `nx_available_plugins` | Lists available Nx plugins from the core team and local workspace plugins                                                           |

#### Generator tools

| Tool                  | Description                                                                                   |
| --------------------- | --------------------------------------------------------------------------------------------- |
| `nx_generators`       | Returns a list of available code generators in your workspace                                 |
| `nx_generator_schema` | Returns the detailed JSON schema for a specific Nx generator, including all available options |

{% aside type="note" title="Tool Availability" %}
When no workspace path is specified, only the `nx_docs` and `nx_available_plugins` tools will be available. Nx Cloud tools require a workspace connected to Nx Cloud.
{% /aside %}

## Available resources

When connected to an Nx Cloud-enabled workspace, the Nx MCP server automatically exposes recent CI Pipeline Executions (CIPEs) as MCP resources. Resources appear in your AI tool's resource picker, allowing the LLM to access detailed information about CI runs including:

- Failed tasks and their error messages
- Terminal output from task executions
- Affected files in the pipeline run
- Build timing and performance data

## Tool usage examples

### Accessing documentation

Get accurate guidance without hallucinations:

```text
How do I configure Nx release for conventional commits?
What are the caching options for tasks?
```

The `nx_docs` tool retrieves relevant, up-to-date documentation based on your query.

### Analyzing CI failures

When a CI build fails, your AI assistant can:

```text
What failed in my last CI run?
Help me fix the build error
```

Using the Nx Cloud tools, the AI can:

1. Access detailed information about the failed build
2. Retrieve terminal output from failed tasks
3. Understand what changed and suggest fixes

### Autonomous CI monitoring

With the `ci_information` and `update_self_healing_fix` tools, AI agents can monitor CI pipelines and interact with self-healing. For a ready-to-use implementation, see the [CI monitoring skill](/docs/features/enhance-ai#self-healing-ci-integration) in Claude Code:

```text
Monitor CI and fix any failures
```

The AI agent can:

1. Poll CI pipeline status via `ci_information`
2. Receive failure context and self-healing suggestions
3. Apply verified fixes via `update_self_healing_fix`
4. Continue iterating until CI passes

### Workspace exploration and code generation

For workspace exploration, code generation, and task execution, agents use [skills](/docs/features/enhance-ai) rather than MCP tools. Skills teach agents how to use the Nx CLI directly — running commands like `nx show projects`, `nx show project myapp`, and `nx generate` — which is more token-efficient than fetching large JSON payloads via MCP.

If your AI client doesn't support skills, use `--no-minimal` to expose the full set of workspace and generator tools via MCP.