Skip to content

Commit d674bc8

Browse files
MaxKlessFrozenPandaz
MaxKless
authored and
FrozenPandaz
committed
docs(misc): update nx-mcp reference and tweak ai docs for skills (#34468)
we changed the default options of the nx mcp so we need to update docs to reflect it (cherry picked from commit 08d899a)
1 parent 5665a87 commit d674bc8

3 files changed

Lines changed: 74 additions & 71 deletions

File tree

‎astro-docs/src/content/docs/features/enhance-AI.mdoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,8 @@ npx nx configure-ai-agents
2626
This sets up:
2727

2828
- **Agent configuration files**: `CLAUDE.md`, `AGENTS.md` with workspace-specific guidelines
29-
- **Agent skills**: Specialized capabilities for monorepo workflows, including CI monitoring and self-healing integration
30-
- **Nx MCP server**: Provides tools that combine local workspace metadata with CI context, enabling seamless local-to-CI workflows that unlock true agent autonomy
29+
- **Agent skills**: Domain-specific knowledge for monorepo workflows — workspace exploration, code generation, task execution, CI monitoring, and package linking. Skills teach agents _how_ to work with Nx rather than dumping data into context.
30+
- **Nx MCP server**: Provides connectivity to Nx Cloud CI pipelines, self-healing fixes, running processes, and Nx documentation — things agents can't easily reach on their own
3131

3232
## What This Enables
3333

‎astro-docs/src/content/docs/getting-started/ai-setup.mdoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ To automatically configure your Nx monorepo to work best with AI agents and assi
2626
npx nx configure-ai-agents
2727
```
2828

29-
This will prompt you for which AI agents/assistants to configure and set up the [Nx MCP server](/docs/features/enhance-ai) (Model Context Protocol—a standard for giving AI assistants tool access), AI agent configuration files (`AGENTS.md`, `CLAUDE.md`, etc.), and agent skills. For Claude Code, skills are installed via a plugin; for other agents, they're copied into your workspace.
29+
This will prompt you for which AI agents/assistants to configure and set up the [Nx MCP server](/docs/reference/nx-mcp), AI agent configuration files (`AGENTS.md`, `CLAUDE.md`, etc.), and agent skills (for workspace exploration, code generation, and task execution). For Claude Code, skills are installed via a plugin; for other agents, they're copied into your workspace.
3030

3131
Alternatively, you can install just the skills via:
3232

‎astro-docs/src/content/docs/reference/nx-mcp.mdoc‎

Lines changed: 71 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,16 @@ sidebar:
77
filter: 'type:References'
88
---
99

10-
The Nx MCP server is a [Model Context Protocol](https://modelcontextprotocol.io/introduction) implementation that gives LLMs deep access to your monorepo's structure: project relationships, file mappings, runnable tasks, ownership info, tech stacks, Nx generators, and Nx documentation.
10+
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.
1111

1212
{% aside type="tip" title="Quick Setup" %}
1313
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.
1414
{% /aside %}
1515

16+
{% aside type="note" title="MCP + Skills" %}
17+
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).
18+
{% /aside %}
19+
1620
For an overview of how Nx enhances AI assistants and powerful use cases, see the [Enhance Your LLM](/docs/features/enhance-ai) guide.
1721

1822
## Installation
@@ -124,15 +128,16 @@ If you miss the notification, run the `Nx: Setup MCP Server` command from the co
124128

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

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

137142
### HTTP Transport
138143

@@ -200,25 +205,38 @@ npx nx-mcp@latest --tools "nx_workspace" "nx_project_details" "nx_docs"
200205

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

203-
## Available Tools
208+
### Minimal Mode (Default)
204209

205-
### Workspace Tools
210+
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.
206211

207-
| Tool | Description |
208-
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
209-
| `nx_workspace` | Returns a readable representation of the project graph and nx.json configuration. Also returns any project graph errors if present. |
210-
| `nx_workspace_path` | Returns the path to the Nx workspace root |
211-
| `nx_project_details` | Returns complete project configuration in JSON format for a specific project, including targets, dependencies, and metadata |
212-
| `nx_docs` | Returns documentation sections relevant to user queries about Nx configuration and best practices |
213-
| `nx_available_plugins` | Lists available Nx plugins from the core team and local workspace plugins |
212+
To restore all tools (e.g., for clients that don't support skills), pass `--no-minimal`:
214213

215-
### Generator Tools
214+
{% tabs syncKey="nx-version" %}
215+
{% tabitem label="Nx >= 21.4" %}
216216

217-
| Tool | Description |
218-
| --------------------- | --------------------------------------------------------------------------------------------------------- |
219-
| `nx_generators` | Returns a list of available code generators in your workspace |
220-
| `nx_generator_schema` | Returns the detailed JSON schema for a specific Nx generator, including all available options |
221-
| `nx_run_generator` | Opens the Nx Console Generate UI with prefilled options (requires a running IDE instance with Nx Console) |
217+
```shell
218+
npx nx mcp --no-minimal
219+
```
220+
221+
{% /tabitem %}
222+
{% tabitem label="Nx < 21.4" %}
223+
224+
```shell
225+
npx nx-mcp@latest --no-minimal
226+
```
227+
228+
{% /tabitem %}
229+
{% /tabs %}
230+
231+
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.
232+
233+
## Available Tools
234+
235+
### Documentation Tools
236+
237+
| Tool | Description |
238+
| --------- | ------------------------------------------------------------------------------------------------- |
239+
| `nx_docs` | Returns documentation sections relevant to user queries about Nx configuration and best practices |
222240

223241
### Task Monitoring Tools
224242

@@ -255,8 +273,29 @@ These tools provide analytics and insights into your CI/CD data:
255273
| `cloud_analytics_tasks_search` | Analyzes aggregated task performance statistics including success rates and cache hit rates |
256274
| `cloud_analytics_task_executions_search` | Analyzes individual task execution data to investigate performance trends over time |
257275

276+
### Extended Tools (--no-minimal)
277+
278+
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.
279+
280+
#### Workspace Tools
281+
282+
| Tool | Description |
283+
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
284+
| `nx_workspace` | Returns a readable representation of the project graph and nx.json configuration. Also returns any project graph errors if present. |
285+
| `nx_workspace_path` | Returns the path to the Nx workspace root |
286+
| `nx_project_details` | Returns complete project configuration in JSON format for a specific project, including targets, dependencies, and metadata |
287+
| `nx_available_plugins` | Lists available Nx plugins from the core team and local workspace plugins |
288+
289+
#### Generator Tools
290+
291+
| Tool | Description |
292+
| --------------------- | --------------------------------------------------------------------------------------------------------- |
293+
| `nx_generators` | Returns a list of available code generators in your workspace |
294+
| `nx_generator_schema` | Returns the detailed JSON schema for a specific Nx generator, including all available options |
295+
| `nx_run_generator` | Opens the Nx Console Generate UI with prefilled options (requires a running IDE instance with Nx Console) |
296+
258297
{% aside type="note" title="Tool Availability" %}
259-
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.
298+
When no workspace path is specified, only the `nx_docs` tool will be available. Nx Cloud tools require a workspace connected to Nx Cloud.
260299
{% /aside %}
261300

262301
## Available Resources
@@ -270,48 +309,6 @@ When connected to an Nx Cloud-enabled workspace, the Nx MCP server automatically
270309

271310
## Tool Usage Examples
272311

273-
### Understanding Workspace Architecture
274-
275-
Ask your AI assistant about your workspace structure:
276-
277-
```text
278-
What is the structure of this workspace?
279-
How are the projects organized?
280-
```
281-
282-
The `nx_workspace` tool provides:
283-
284-
- All applications and libraries in your workspace
285-
- Project categorization through tags
286-
- Technology types (feature, UI, data-access)
287-
- Project ownership and team responsibilities
288-
289-
### Getting Project Details
290-
291-
To understand a specific project's configuration:
292-
293-
```text
294-
Show me the details of the my-app project
295-
What targets are available for my-lib?
296-
```
297-
298-
The `nx_project_details` tool returns:
299-
300-
- Complete target configuration
301-
- Project dependencies
302-
- Source and output paths
303-
- Tags and metadata
304-
305-
### Using Generators
306-
307-
Ask your AI assistant to scaffold new code:
308-
309-
```text
310-
Create a new React library in the packages/shared folder
311-
```
312-
313-
The AI will use `nx_generators` to find available generators and `nx_generator_schema` to understand the options, then can invoke `nx_run_generator` to open the Generate UI with preset values.
314-
315312
### Accessing Documentation
316313

317314
Get accurate guidance without hallucinations:
@@ -352,3 +349,9 @@ The AI agent can:
352349
2. Receive failure context and self-healing suggestions
353350
3. Apply verified fixes via `update_self_healing_fix`
354351
4. Continue iterating until CI passes
352+
353+
### Workspace Exploration and Code Generation
354+
355+
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.
356+
357+
If your AI client doesn't support skills, use `--no-minimal` to expose the full set of workspace and generator tools via MCP.

0 commit comments

Comments
 (0)
⚡