--- title: Configure the Management MCP related: - https://docs.kentico.com/documentation/developers-and-admins/api/management-api.md - https://docs.kentico.com/documentation/developers-and-admins/api/management-api/use-management-mcp-server.md - https://docs.kentico.com/documentation/developers-and-admins/api/management-api/reference-management-mcp-capabilities.md --- > Agent instructions: > **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown. > > - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version. > - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt). This page describes how to set up and configure the [Management MCP server](https://docs.kentico.com/documentation/developers-and-admins/api/management-api.md) and underlying API. ## Enable the management API > **Warning:** **Only for local development purposes** > > The management API is only intended for use on local development instances. It currently only provides basic authentication and no authorization options for various types of operations. > > Do **not** enable the management API for production deployments or other publicly available instances. To enable the content management API for a development project: 1. Install the [Kentico.Xperience.ManagementApi](https://www.nuget.org/packages/Kentico.Xperience.ManagementApi) NuGet package into your Xperience project. ```cmd title="Install the Management API package" dotnet add package Kentico.Xperience.ManagementApi ``` 2. Adjust your application's startup code in _Program.cs_: 1. Call the `AddKenticoManagementApi()` extension method on your application's service collection. - Adds controllers used by the management API. Also registers and configures services for authentication, authorization, [Swagger generation](https://swagger.io/tools/swagger-codegen/), and API versioning. If you already configure such services, place the _AddKenticoManagementApi()_ call after your configuration. Most of the configuration is scoped only to the management API endpoints, but there are exceptions (see the method's remarks in your IDE for details). 2. In the method's `ManagementApiOptions` parameter, set the `Secret` property to a string with at least 32 characters. - The secret is required to authenticate all requests to the management API endpoints, and will be used in the configuration of your management API MCP server. 3. Add the following to the application's [middleware pipeline](https://docs.kentico.com/documentation/developers-and-admins/development/website-development-basics/configure-new-projects.md): - `UseAuthentication()` – adds authentication middleware. Must be called **before** _UseKentico()_. - `UseKenticoManagementApi()` – adds middleware required for the management API. - `UseAuthorization()` – adds authorization middleware. Must be called **after** _UseKentico()_. ```csharp title="Program.cs" using Microsoft.AspNetCore.Builder; using Microsoft.Extensions.Hosting; using Kentico.Xperience.ManagementApi; using Kentico.Web.Mvc; // ... var builder = WebApplication.CreateBuilder(args); // ... // Only enables the management API in the local development environment if (builder.Environment.IsDevelopment()) { builder.Services.AddKenticoManagementApi(options => { // Sets the secret required to authenticate all requests to the management API endpoints // Must be at least 32 characters options.Secret = ""; // Optionally set the directory from which asset upload files are read // Default: ~/assets/managementapiuploads (resolved relative to the application root) // An absolute path (e.g., "C:\\temp") is used as-is // options.AssetUploadDirectoryPath = "~/my/custom/upload-path"; }); } // ... var app = builder.Build(); app.InitKentico(); // ... // Adds authentication middleware app.UseAuthentication(); if (builder.Environment.IsDevelopment()) { // Adds middleware required for the management API app.UseKenticoManagementApi(); } app.UseKentico(); // Adds authorization middleware app.UseAuthorization(); // Maps routes used by Xperience by Kentico feature app.Kentico().MapRoutes(); ``` The management API is now available for your project. Agents can discover the API through an [OpenAPI specification](https://swagger.io/specification/v3.1/), available under the _/kentico-api/management/v1/openapi.json_ URL path when your project is running. ## Add the MCP server - Use the [@kentico/management-api-mcp](https://www.npmjs.com/package/@kentico/management-api-mcp) npm package. - We recommend using the `@kentico/management-api-mcp@latest` argument in your MCP server configuration. This ensures that the latest version of the package is installed automatically when the server starts. - You do not need to match the npm package version to your project's Xperience NuGet packages. The MCP server reads the management API schema from your local running project and adapts to the version. - Set the following environment variables in the server's configuration: - `MANAGEMENT_API_URL` – the URL of your locally running Xperience application, followed by the _kentico-api/management_ path. - `MANAGEMENT_API_SECRET` – the secret configured when [enabling the management API](#enable-the-management-api) for your application. See the documentation of your IDE or AI client for details on adding MCP servers. The following are guides for popular tools: - [Use MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) - [Add MCP servers for GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) - [Add a local MCP server in Claude Code](https://code.claude.com/docs/en/mcp#option-3-add-a-local-stdio-server) - [Connect to local MCP servers from Claude Desktop](https://modelcontextprotocol.io/docs/develop/connect-local-servers) - [Use MCP servers in Visual Studio](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=visualstudio) - [MCP guide for Cursor](https://cursor.com/docs/context/mcp) For example, to get the MCP server running in [VS Code](https://code.visualstudio.com/docs), [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers), [Claude Code](https://code.claude.com/docs/en/mcp#option-3-add-a-local-stdio-server), or [Cursor](https://cursor.com/docs/context/mcp): 1. Edit the MCP configuration file for your IDE or AI client. The server definition is the same for all tools, but the file location and the name of the top-level key may differ, for example: - **VS Code** – `.vscode/mcp.json`, uses `"servers"` as the top-level key - **GitHub Copilot CLI** – `~/.copilot/mcp-config.json`, uses `"mcpServers"` as the top-level key - **Claude Code** – `.mcp.json`, uses `"mcpServers"` as the top-level key - **Cursor** – `.cursor/mcp.json`, uses `"mcpServers"` as the top-level key 2. Add the following server configuration: ```json title="mcp.json" { "servers": { "xperience-management-mcp": { "type": "stdio", "command": "npx", "args": [ "@kentico/management-api-mcp@latest" ], "env": { "MANAGEMENT_API_URL": "http://localhost:5001/kentico-api/management", "MANAGEMENT_API_SECRET": "" } } } } ``` 3. Adjust the environment variables for your project: - `MANAGEMENT_API_URL` – change the port number to match the URL where your Xperience application is running. - `MANAGEMENT_API_SECRET` – set the value to the secret configured when [enabling the management API](#enable-the-management-api). 4. Start the MCP server in your IDE. 5. Run your Xperience application. See [Set up local hosting](https://docs.kentico.com/documentation/developers-and-admins/development/website-development-basics/set-up-local-hosting.md) for more information. The MCP server and your Xperience application can be started in either order. If the application is not running when the MCP server starts, the server will show no tools until the application becomes reachable – at which point the tools are loaded automatically without restarting the MCP server. > **Note:** **Restart the MCP server after updating NuGet packages** > > After updating your Xperience NuGet packages, restart the MCP server so it picks up any changes to the management API. The MCP server reads the available tools from the running application at startup, so a previously running instance will not automatically reflect changes introduced by an update. ![Tools provided by the MCP server](https://docs.kentico.com/docsassets/documentation/configure-management-mcp-server/management_api_mcp_tools.png "Tools provided by the MCP server") > **Tip:** Management access is part of preparing a project for AI-assisted development. To audit how ready your project is, see [Add KentiCopilot into your project](https://docs.kentico.com/guides/development/kenticopilot.md#add-kenticopilot-into-your-project). ## Limit the available tools For the best results from AI agents, **limit the enabled tools** of the MCP server to only those required for your current scenario. Disabling unrelated tools reduces noise, lowers token usage, and helps the AI agent focus on the task at hand. You can select the exposed tools on two levels – whole [tool groups](#tool-groups), each covering one type of object, or individual tools. Start with the groups that match your scenario and adjust the result with individual tools. ### Available CLI options You can limit tools from your IDE's UI (see your IDE's documentation), or use the MCP server's built-in command-line options: | | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Prints the [tool groups](#tool-groups) available on your instance, together with the number of tools in each. With this option, the MCP server application **exits immediately** after printing the tool groups.
Requires the connected Xperience application to be running. | | Exposes **only** the tools in the listed [groups](#tool-groups). Tools from all other groups are hidden. The option can be repeated multiple times, or `` can be a comma-separated list.
Group names are matched without regard to casing and word separators, so `ContentItem`, `contentitem`, and `content-item` all select the same group. | | | | | | Exposes only three dynamic meta-tools (`list_available_tools`, `get_tool_schema`, `call_tool`) instead of registering every tool individually. This significantly reduces the initial token footprint.
Group selection also applies in `--dynamic-tools` mode – the meta-tools list, describe, and call only the tools that the filters expose. | ### Tool groups Every tool of the MCP server belongs to a **tool group** that covers one type of object – for example `ContentType`, `ContentItem`, `WebPage`, `PageBuilder`, or `Taxonomy`. The groups come from the tags of the management API's [OpenAPI specification](https://swagger.io/specification/v3.1/), where each tag covers one area of the API. Selecting whole groups keeps your configuration short and stable. Unlike lists of individual tool names, group names remain valid when tools are added, renamed, or split. To see the groups available on your instance, together with the number of tools in each and the tools themselves, run the MCP server with the `--list-groups` option. The option reads the groups from your running application. **Start your Xperience application** and set the `MANAGEMENT_API_URL` and `MANAGEMENT_API_SECRET` environment variables before you run the command. The server prints the listing and exits without registering any tools. ```cmd title="List the available tool groups (with filtered server log output)" set "MANAGEMENT_API_URL=http://localhost:5001/kentico-api/management" set "MANAGEMENT_API_SECRET=" npx @kentico/management-api-mcp@latest --list-groups 2>nul ``` The `--enabled-groups`, `--enabled-tools`, and `--disabled-tools` options can be combined in a single configuration: - **Enabled groups and enabled tools add up.** When both options are set, a tool is exposed if it belongs to one of the enabled groups **or** is listed by name. This allows you to expose a group together with a few extra tools from other groups. - **Disabled tools always win.** `--disabled-tools` is applied last and hides the listed tools even when an enabled group or the `--enabled-tools` option exposes them. - **Groups have no exclusion option.** To hide a group, leave it out of `--enabled-groups`. To hide individual tools of an enabled group, list them in `--disabled-tools`. - **Unknown names are reported and ignored.** A misspelled group or tool name does not stop the server. The server writes unknown names to its log and continues, which results in fewer available tools than expected. ### Suggested tool combinations The following table lists suggested tool groups for common scenarios: See [Reference - Management MCP capabilities](https://docs.kentico.com/documentation/developers-and-admins/api/management-api/reference-management-mcp-capabilities.md) for the groups that cover each supported object, and the tools in them. > **Tip:** You can define multiple entries pointing to the same MCP server package, each with a different name and toolset. This lets you switch between toolsets for different scenarios directly from your IDE, without editing the tool list each time. ### Example configuration ```json title="MCP configuration file -- limiting tools via CLI options" { "servers": { "xperience-management-mcp-content-types": { "type": "stdio", "command": "npx", "args": [ "@kentico/management-api-mcp@latest", "--enabled-groups", "ContentType,ReusableSchema,FormComponent,DataType", "--disabled-tools", "delete_content_type" ], "env": { "MANAGEMENT_API_URL": "http://localhost:5001/kentico-api/management", "MANAGEMENT_API_SECRET": "" } }, "xperience-management-mcp-pages": { "type": "stdio", "command": "npx", "args": [ "@kentico/management-api-mcp@latest", "--enabled-groups", "WebPage,WebPagePageBuilder,PageBuilder,ContentType,Channel,Asset", "--enabled-tools", "list_content_folders" ], "env": { "MANAGEMENT_API_URL": "http://localhost:5001/kentico-api/management", "MANAGEMENT_API_SECRET": "" } } } } ``` The two example servers show both ways of combining the options: - _xperience-management-mcp-content-types_ exposes four groups and then hides a single destructive tool from one of them. - _xperience-management-mcp-pages_ exposes six groups and adds only `list_content_folders` from the `ContentFolder` group, so the agent can pick a folder for uploaded assets. ## Manage the agent's context Management MCP tools return verbose results, and the context they consume grows with every call. Sessions that work with the server get compacted sooner – the agent summarizes the conversation and loses detail from earlier steps. We recommend delegating the work that drives these tools to subagents instead of running it in the main session. Each subagent calls the tools in its own context and reports back a short summary, so the main session keeps the plan and the decisions rather than raw tool output. Bulk changes, such as creating many content items or rebuilding a page structure, benefit the most. See your AI tool's documentation for how it exposes delegated sessions. ## Configure asset uploads The Management MCP server can upload files to _Content item asset_ fields. By default, the server reads files from the _\~/assets/managementapiuploads_ directory relative to the application root. The upload directory path can be customized via the `AssetUploadDirectoryPath` property of `ManagementApiOptions` (see [Enable the management API](#enable-the-management-api)). The property accepts two formats: - Application-relative paths (starting with `~/` or `~\`) – resolved against the application root (e.g., `~/my/upload-folder`). - Absolute paths – used as-is and can point to any location on the file system (e.g., `C:\temp`). Subfolders within the upload directory are supported.