# Getting Started with the Telerik UI for .NET MAUI Agentic UI Generator

The Agentic UI Generator is an intelligent development tool delivered through the Telerik UI for .NET MAUI [MCP (Model Context Protocol) server](https://www.nuget.org/packages/Telerik.MAUI.MCP) that enables UI generation from natural language prompts. Once configured and authenticated, you can use the Agentic UI Generator tool (`#telerik-maui-assistant`) together with the available specialized MCP assistants.

> tip
> The Telerik UI for .NET MAUI MCP server works in **Chat** (**Ask**) and **Agent** modes.

## Prerequisites

To use the Telerik MAUI MCP server, you need:

* [.NET](https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-8/overview) 9 or later, or [Node.js](https://nodejs.org/en) 18 or later.

* An [MCP-compatible client](https://modelcontextprotocol.io/clients) that supports MCP tools (latest version recommended).

* A [Telerik user account](https://www.telerik.com/account/).

* An active [DevCraft or Telerik UI for MAUI subscription license](https://www.telerik.com/purchase/maui-ui) or a [Telerik UI for MAUI trial](https://www.telerik.com/maui-ui).

* A [.NET MAUI application that includes Telerik UI for .NET MAUI](https://www.telerik.com/maui-ui/documentation/get-started/quickstart).

## Installing the Telerik UI for .NET MAUI MCP Server

Choose the runtime that best matches your development environment:

Install the server package by using the `dnx` script or the `dotnet` CLI:

```bash .NET 10
dnx Telerik.MAUI.MCP
```

```bash .NET 9
dotnet tool install Telerik.MAUI.MCP
```

After the package is available, configure `mcp.json`, add your Telerik license if needed, restart your MCP client, and then verify that the server is running.

### Configuring mcp.json

Use the following values in the [`mcp.json` file](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) of your editor. The exact wrapper differs by client, but the `command`, `args`, and server name stay the same.

| Setting Name | .NET 10 Value                 | .NET 9 Value                              |
| ------------ | ----------------------------- | ----------------------------------------- |
| Package Name | `"Telerik.MAUI.MCP"`          | `"Telerik.MAUI.MCP"`                      |
| Type         | `"stdio"`                     | `"stdio"`                                 |
| Command      | `"dnx"`                       | `"dotnet"`                                |
| Arguments    | `"Telerik.MAUI.MCP", "--yes"` | `"tool", "run", "telerik-maui-assistant"` |
| Server Name  | `"telerik-maui-assistant"`    | `"telerik-maui-assistant"`                |

### Configuring Your License

An active Telerik UI for .NET MAUI license is required to use the Telerik MAUI MCP server.

* When you use the .NET tooling (`dnx` or `dotnet tool install`) and the [license key file](https://www.telerik.com/maui-ui/documentation/installation/licensing/set-up-your-license) is stored in the default location, the server loads it automatically. The default path is `%AppData%\Telerik\telerik-license.txt` on Windows and `~/.telerik/telerik-license.txt` on Linux.
* When you use the .NET tooling and the [license key file](https://www.telerik.com/maui-ui/documentation/installation/licensing/set-up-your-license) is stored in a different location, add one of the following `env` settings to `mcp.json`.
* When you use Node.js, add one of the following `env` settings to `mcp.json`:

  * As a license file path (recommended):

    ```json
    "env": {
        "TELERIK_LICENSE_PATH": "THE_PATH_TO_YOUR_LICENSE_FILE"
    }
    ```

  * As a license key value:

    ```json
    "env": {
        "TELERIK_LICENSE": "YOUR_LICENSE_KEY_HERE"
    }
    ```

> note Use a license file path unless you need to share settings across systems. When your Telerik license changes, [update the license key](https://www.telerik.com/maui-ui/documentation/installation/licensing/set-up-your-license#updating-your-license-key) before you restart the MCP client.

Client configuration examples in the next section use `TELERIK_LICENSE_PATH`. If you prefer to pass the license value directly, replace it with `TELERIK_LICENSE` in the `env` object.

## MCP Clients Configuration

Use the following client-specific examples to create a working `mcp.json` file. The configuration values are the same across clients, but the config file location and top-level property name differ.

<TabStrip>
<TabStripTab title="Visual Studio">

> note Early Visual Studio 17.14 versions require the Copilot Chat window to stay open while the solution loads. For platform-specific details, see [Use MCP servers in Visual Studio](https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers).

1. Add an `.mcp.json` file to either of the following locations:

   * For a workspace-specific setup, add the file to the solution folder.
   * For a global setup, add the file to your user directory, `%USERPROFILE%` (for example, `C:\Users\YourName\.mcp.json`).

   ```json .NET 10
   {
     "servers": {
       "telerik-maui-assistant": {
         "type": "stdio",
         "command": "dnx",
         "args": ["Telerik.MAUI.MCP", "--yes"]
       }
     }
   }
   ```

   ```json .NET 9
   {
     "servers": {
       "telerik-maui-assistant": {
         "type": "stdio",
         "command": "dotnet",
         "args": ["tool", "run", "telerik-maui-assistant"]
       }
     }
   }
   ```

2. Restart Visual Studio.

3. Enable the Telerik MAUI MCP server in the [Copilot Chat window's tool selection dropdown](https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers?view=vs-2022#configuration-example-with-github-mcp-server).

</TabStripTab>
<TabStripTab title="Visual Studio Code">

> note Visual Studio Code `1.102.1` or later is required. For platform-specific details, see [Use MCP servers in Visual Studio Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).

The basic setup in Visual Studio Code involves the following steps:

1. Enable [`chat.mcp.enabled`](vscode://settings/chat.mcp.enabled) in the Visual Studio Code settings.

2. Create a `.vscode/mcp.json` file in your workspace root (or user folder for global setup):

   ```json .NET 10
   {
     "servers": {
       "telerik-maui-assistant": {
         "type": "stdio",
         "command": "dnx",
         "args": ["Telerik.MAUI.MCP", "--yes"]
       }
     }
   }
   ```

   ```json .NET 9
   {
     "servers": {
       "telerik-maui-assistant": {
         "type": "stdio",
         "command": "dotnet",
         "args": ["tool", "run", "telerik-maui-assistant"]
       }
     }
   }
   ```

3. For global discovery, enable [`chat.mcp.discovery.enabled`](vscode://settings/chat.mcp.discovery.enabled) in `settings.json`:

   ```json
   {
     "chat.mcp.discovery.enabled": true
   }
   ```

4. Restart Visual Studio Code.

</TabStripTab>
<TabStripTab title="Cursor">

> note For Cursor-specific details, see [Model Context Protocol in Cursor](https://docs.cursor.com/context/mcp).

Create a `.cursor/mcp.json` file in your workspace root (or user folder for global setup):

```json .NET 10
{
  "mcpServers": {
    "telerik-maui-assistant": {
      "type": "stdio",
      "command": "dnx",
      "args": ["Telerik.MAUI.MCP", "--yes"]
    }
  }
}
```

```json .NET 9
{
  "mcpServers": {
    "telerik-maui-assistant": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["tool", "run", "telerik-maui-assistant"]
    }
  }
}
```

</TabStripTab>
</TabStrip>

## Verifying That the MCP Server Is Working

After you restart the client, confirm that the server is available before you begin a larger prompt:

1. Start a new chat or agent session.
2. Begin the prompt with one of the Telerik triggers.
3. Approve tool permissions when the client asks.
4. Confirm that the editor shows the Telerik MAUI MCP server as running.

Use one of the following trigger strings in your prompt:

* `#telerik`
* `#telerikmaui`
* `#telerik-maui-assistant`

Look for one of the following client messages:

* Visual Studio: `Running telerik-maui-assistant`
* Visual Studio Code: `Running telerik-maui-assistant`
* Cursor: `Calling MCP tool telerik-maui-assistant`

## Troubleshooting

If the server does not appear or does not respond, check the following items first:

* Confirm that your installed runtime matches the configuration in `mcp.json`.
* Confirm that the JSON file is valid and uses the correct top-level property for your client.
* Confirm that your Telerik license file path or license value is available to the editor process.
* Restart the editor after every `mcp.json` change.

> warning
> **Known Issue: Hanging tool calls in Visual Studio**
>
> When you use Telerik AI tools in Visual Studio, GitHub Copilot may:
>
> * **hang** during tool invocation;
> * show UI for a successful tool response, but actually **fail silently**;
> * continue generation without waiting for **parallel tool calls**.
>
> In these cases, the response may be generated but not shown in the Copilot Agent UI.
>
> This is a known issue in Visual Studio Copilot, not in Telerik MCP servers or Telerik AI tools, and it does not reproduce in Visual Studio Code.
>
> For more details, see the [Visual Studio Developer Community issue for hanging Copilot tool calls](https://developercommunity.visualstudio.com/t/Copilot-stopped-working-after-latest-upd/10936456).
>
> Microsoft has marked the issue as **Fixed - Pending Release**. A future Visual Studio update is expected to resolve it.

## Usage

MCP clients do not always call tools deterministically. When your client supports explicit tool selection, reference the Telerik server directly in the prompt to increase the chance that the client uses Telerik-specific context.

Use the following practices when you work with the Telerik MAUI MCP server:

1. Start the prompt with `#telerik`, `#telerikmaui`, or `#telerik-maui-assistant`.
2. Keep the request specific by naming the Telerik control, layout, data source, or behavior you want.
3. Grant permissions when the client prompts you.
4. Start a fresh session for unrelated prompts so earlier context does not affect the next result.
5. Use the server in **Chat** (**Ask**) and **Agent** modes.

### Increasing Tool Selection Reliability

To increase the likelihood that your AI client uses the Telerik server, add client-specific instructions that mention Telerik UI for .NET MAUI as a preferred source for component generation and API guidance:

* [GitHub Copilot custom instructions](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot#about-repository-custom-instructions-for-github-copilot-chat)
* [Cursor rules](https://docs.cursor.com/context/rules)

### Sample Prompts

Use prompts like the following examples when you want the client to generate Telerik-specific code:

* "`#telerik-maui-assistant Create new maui project with Telerik. Add sample usage of the DataGrid component.`"
* "`#telerik-maui-assistant Create a DataGrid with 3 columns - Name, Country, City. Add the corresponding business object in the code behind and populate it with sample data. Add 20 entries to the data.`"
* "`#telerik-maui-assistant Add CollectionView. Enable drag and drop operation in the control.`"

## Number of Requests

A Telerik [Subscription license](https://www.telerik.com/purchase/faq/licensing-purchasing) is required in order to use the Telerik MAUI Agentic UI Generator. Trial users can make a [limited number of requests per year](https://www.telerik.com/maui-ui/documentation/ai/overview#number-of-requests).

## Local AI Model Integration

You can use the Telerik MAUI MCP server with a local large language model (LLM) instead of a cloud-hosted model:

1. Run a local model, for example, [Ollama](https://ollama.com/).
2. Use a bridge package like [MCP-LLM Bridge](https://github.com/patruff/ollama-mcp-bridge).
3. Connect the local model and the Telerik MAUI MCP server through the bridge.

This setup allows you to use the Telerik Agentic UI Generator without a cloud-based AI model.

## See Also

* [Agentic UI Generator Overview](https://www.telerik.com/maui-ui/documentation/ai/overview)
* [Set Up Your Telerik License](https://www.telerik.com/maui-ui/documentation/installation/licensing/set-up-your-license)
