Skip to content

docs: streamline and update mcp server setup documentation #69155

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
clydin wants to merge 1 commit into
base: main
Choose a base branch
from
+110 −120
Open

docs: streamline and update mcp server setup documentation #69155

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
230 changes: 110 additions & 120 deletions adev/src/content/ai/mcp-server-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,159 +1,149 @@
# Angular CLI MCP Server setup
# Angular CLI MCP Server

The Angular CLI includes an experimental [Model Context Protocol (MCP) server](https://modelcontextprotocol.io/) enabling AI assistants in your development environment to interact with the Angular CLI. We've included support for CLI powered code generation, adding packages, and more.
The Angular CLI includes a Model Context Protocol (MCP) server that enables AI assistants (like Cursor, Gemini CLI, JetBrains AI, etc.) to interact directly with the Angular CLI. It provides tools for code generation, workspace analysis, and running builds/tests.

## Available Tools
<docs-callout title="Integration with Angular AI Agent Skills">
If your host environment supports custom Agent Skills (such as Antigravity IDE or Gemini CLI), you can combine the Angular CLI MCP server with the official [Angular AI Skills](https://angular.dev/ai/skills). While the skills provide the agent with deep instruction-level guidance and coding standards, the MCP server provides the action tools (like compiling, running tests, and analyzing workspaces) to execute those guidelines, resulting in a complete and powerful development agent.
</docs-callout>

The Angular CLI MCP server provides several tools to assist you in your development workflow. By default, the following tools are enabled:
## Get Started

To use the MCP server, you configure your host environment (IDE or CLI) to run `npx @angular/cli mcp`.

| Name | Description | `local-only` | `read-only` |
| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------: | :---------: |
| `ai_tutor` | Launches an interactive AI-powered Angular tutor. Recommended to run from a new Angular project using v20 or later. [Learn more](ai/ai-tutor). | ✅ | ✅ |
| `find_examples` | Finds authoritative code examples from a curated database of official, best-practice examples, focusing on **modern, new, and recently updated** Angular features. | ✅ | ✅ |
| `get_best_practices` | Retrieves the Angular Best Practices Guide. This guide is essential for ensuring that all code adheres to modern standards, including standalone components, typed forms, and modern control flow. | ✅ | ✅ |
| `list_projects` | Lists the names of all applications and libraries defined within an Angular workspace. It reads the `angular.json` configuration file to identify the projects. | ✅ | ✅ |
| `onpush_zoneless_migration` | Analyzes Angular code and provides a step-by-step, iterative plan to migrate it to `OnPush` change detection, a prerequisite for a zoneless application. | ✅ | ✅ |
| `search_documentation` | Searches the official Angular documentation at <https://angular.dev>. This tool should be used to answer any questions about Angular, such as for APIs, tutorials, and best practices. | ❌ | ✅ |
<docs-tab-group>
<docs-tab label="Antigravity IDE">
Create a file named `.antigravity/mcp.json` in your project's root:

### Experimental Tools
```json
{
"mcpServers": {
"angular-cli": {
"command": "npx",
"args": ["-y", "@angular/cli", "mcp"]
}
}
}
```

Some tools are provided in experimental / preview status since they are new or not fully tested. Enable them individually with the [`--experimental-tool`](#command-options) option and use them with caution.
</docs-tab>

| Name | Description | `local-only` | `read-only` |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------: | :---------: |
| `build` | Perform a one-off, non-watched build using `ng build`. | ✅ | ❌ |
| `devserver.start` | Asynchronously starts a development server that watches the workspace for changes, similar to running `ng serve`. Since this is asynchronous it returns immediately. To manage the resulting server, use the `devserver.stop` and `devserver.wait_for_build` tools. | ✅ | ✅ |
| `devserver.stop` | Stops a development server started by `devserver.start`. | ✅ | ✅ |
| `devserver.wait_for_build` | Returns the output logs of the most recent build in a running development server started by `devserver.start`. If a build is currently ongoing, it will first wait for that build to complete and then return the logs. | ✅ | ✅ |
| `e2e` | Executes the end-to-end tests configured in the project. | ✅ | ✅ |
| `modernize` | Performs code migrations and provides further instructions on how to modernize Angular code to align with the latest best practices and syntax. [Learn more](https://angular.dev/reference/migrations) | ✅ | ❌ |
| `test` | Runs the project's unit tests. | ✅ | ✅ |
<docs-tab label="Gemini CLI">
Create `.gemini/settings.json` in the project root:

## Get Started
```json
{
"mcpServers": {
"angular-cli": {
"command": "npx",
"args": ["-y", "@angular/cli", "mcp"]
}
}
}
```

To get started, run the following command in your terminal:
</docs-tab>

```bash
ng mcp
```
<docs-tab label="Cursor">
Create `.cursor/mcp.json` in the project root (or globally at `~/.cursor/mcp.json`):

When run from an interactive terminal, this command displays instructions on how to configure a host environment to use the MCP server. The following sections provide example configurations for several popular editors and tools.
```json
{
"mcpServers": {
"angular-cli": {
"command": "npx",
"args": ["-y", "@angular/cli", "mcp"]
}
}
}
```

### Cursor
</docs-tab>

Create a file named `.cursor/mcp.json` in your project's root and add the following configuration. You can also configure it globally in `~/.cursor/mcp.json`.
<docs-tab label="VS Code">
Create `.vscode/mcp.json`:

```json
{
"mcpServers": {
"angular-cli": {
"command": "npx",
"args": ["-y", "@angular/cli", "mcp"]
```json
{
"servers": {
"angular-cli": {
"command": "npx",
"args": ["-y", "@angular/cli", "mcp"]
}
}
}
}
}
```
```

### Firebase Studio
</docs-tab>
</docs-tab-group>

Create a file named `.idx/mcp.json` in your project's root and add the following configuration:
## Available Tools (Default)

```json
{
"mcpServers": {
"angular-cli": {
"command": "npx",
"args": ["-y", "@angular/cli", "mcp"]
}
}
}
```
When the MCP server is enabled, AI agents have access to the following tools:

### Gemini CLI
| Name | Description |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------- |
| `ai_tutor` | Launches an interactive AI-powered Angular tutor. |
| `get_best_practices` | Retrieves the Angular Best Practices Guide (crucial for standalone components, typed forms, etc.). |
| `list_projects` | Lists all applications and libraries in the workspace by reading `angular.json`. |
| `onpush_zoneless_migration` | Analyzes code and provides a plan to migrate it to `OnPush` change detection (prerequisite for zoneless). |
| `search_documentation` | Searches the official documentation at `https://angular.dev`. |

Create a file named `.gemini/settings.json` in your project's root and add the following configuration:
## Experimental Tools

```json
{
"mcpServers": {
"angular-cli": {
"command": "npx",
"args": ["-y", "@angular/cli", "mcp"]
}
}
}
```
Some tools must be enabled explicitly using the `--experimental-tool` (or `-E`) flag.

### JetBrains IDEs
| Name | Description |
| :------------------------- | :-------------------------------------------------------------------- |
| `run_target` | Executes a configured target (e.g., build, test, lint, e2e, deploy). |
| `devserver.start` | Asynchronously starts a dev server (`ng serve`). Returns immediately. |
| `devserver.stop` | Stops the dev server. |
| `devserver.wait_for_build` | Returns the logs of the most recent build in a running dev server. |

In JetBrains IDEs (like IntelliJ IDEA or WebStorm), after installing the JetBrains AI Assistant plugin, go to `Settings | Tools | AI Assistant | Model Context Protocol (MCP)`. Add a new server (`+`) and select `As JSON`. Then paste the following configuration:
## Common Workflows

```json
{
"mcpServers": {
"angular-cli": {
"command": "npx",
"args": ["-y", "@angular/cli", "mcp"]
}
}
}
```
These workflows demonstrate how AI assistants coordinate different MCP tools to automatically achieve complex developer stories.

For the most up-to-date instructions on configuring MCP servers, please refer to the JetBrains documentation: [Connect to an MCP server](https://www.jetbrains.com/help/ai-assistant/mcp.html#connect-to-an-mcp-server).
### 1. Performance Tuning: Zoneless & OnPush Migration

### VS Code
The AI agent optimizes change detection performance and migrates components to a zoneless-ready state.

In your project's root, create a file named `.vscode/mcp.json` and add the following configuration. Note the use of the `servers` property.
1. **Discover Workspace**: The AI agent calls `list_projects` to locate components, projects, and style/test configurations in the workspace.
2. **Schematic Modernization (Prerequisite)**: The AI agent runs any prerequisite signal migrations using standard `ng generate` commands (e.g., Signal Inputs, Signal Queries).
3. **Plan Migration**: The AI agent calls `onpush_zoneless_migration` with the absolute path of the directory or component file.
4. **Apply Changes**: The AI agent automatically applies the single actionable change returned by the tool to the codebase.
5. **Verify Changes**: The AI agent runs unit tests by calling `run_target` with the target parameter set to `"test"`.
6. **Repeat**: The AI agent calls `onpush_zoneless_migration` again to retrieve the next step, repeating until the tool indicates the migration is complete.

```json
{
"servers": {
"angular-cli": {
"command": "npx",
"args": ["-y", "@angular/cli", "mcp"]
}
}
}
```
### 2. Feature Development & TDD Loop

### Other IDEs
The AI agent automates research, implementation, and verification when developing new features.

For other IDEs, check your IDE's documentation for the proper location of the MCP configuration file (often `mcp.json`). The configuration should contain the following snippet.
1. **API & Syntax Research**: The AI agent uses `search_documentation` to look up Angular APIs or syntax rules (e.g., `@defer` block options).
2. **Load Coding Standards**: The AI agent calls `get_best_practices` with the workspace path to load Angular version-aligned coding rules.
3. **Start Local Dev Server**: The AI agent starts a background server by calling `devserver.start`.
4. **Monitor Build**: The AI agent uses `devserver.wait_for_build` to watch build logs and ensure compilation succeeds as it edits the code.
5. **Write and Execute Tests**: The AI agent identifies the project's test framework (e.g., Jasmine, Jest, Vitest) via `list_projects`, writes the corresponding test file, and runs the tests using `run_target` with `"test"`.
6. **Stop Dev Server**: When finished, the AI agent stops the active dev server by calling `devserver.stop`.

```json
{
"mcpServers": {
"angular-cli": {
"command": "npx",
"args": ["-y", "@angular/cli", "mcp"]
}
}
}
```
### 3. Developer Onboarding and Learning

The AI agent guides the developer through Angular concepts in an interactive sandbox.

1. **Discover Projects**: The AI agent calls `list_projects` to scan the workspace and identify the codebase structure.
2. **Launch Tutor**: The AI agent runs `ai_tutor` to load the curriculum instructions, persona, and tutoring guidelines.
3. **Follow the Curriculum**: The AI agent guides the user through the curriculum, explaining concepts and instructing them on what components to build or modify.
4. **Implement & Verify**: The AI agent helps implement the sandbox code and verifies changes using `run_target` with `"test"` or `"build"`.

## Command Options

The `mcp` command can be configured with the following options passed as arguments in your IDE's MCP configuration:
You can pass arguments to the MCP server in the `args` array of your configuration:

| Option | Type | Description | Default |
| :---------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ |
| `--read-only` | `boolean` | Only register tools that do not make changes to the project. Your editor or coding agent may still perform edits. | `false` |
| `--local-only` | `boolean` | Only register tools that do not require an internet connection. Your editor or coding agent may still send data over the network. | `false` |
| `--experimental-tool`<br>`-E` | `string` | Enable an [experimental tool](#experimental-tools). Separate multiple options by spaces, e.g. `-E tool_a tool_b`. Enable all `devserver.x` tools by using `-E devserver`. | |
- `--read-only`: Only registers tools that do not modify the project.
- `--local-only`: Only registers tools that do not require an internet connection.
- `--experimental-tool` (`-E`): Enables specific experimental tools (e.g., `-E run_target`, `-E devserver`).

For example, to run the server in read-only mode in VS Code, you would update your `mcp.json` like this:
Example for read-only mode with experimental tools enabled:

```json
{
"servers": {
"angular-cli": {
"command": "npx",
"args": ["-y", "@angular/cli", "mcp", "--read-only"]
}
}
}
"args": ["-y", "@angular/cli", "mcp", "--read-only", "-E", "run_target", "-E", "devserver"]
```

## Feedback and New Ideas

The Angular team welcomes your feedback on the existing MCP capabilities and any ideas you have for new tools or features. Please share your thoughts by opening an issue on the [angular/angular GitHub repository](https://github.com/angular/angular/issues).
Loading