--- 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.2/), 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, consider **limiting 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. ### 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: ### Suggested tool combinations The following table lists suggested tool combinations for common scenarios: > **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-tools", "list_content_types,get_content_type,create_content_type,update_content_type,delete_content_type,create_content_type_field,update_content_type_field,delete_content_type_field,list_form_components,list_data_types" ], "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-tools", "list_channels,list_content_types,get_content_type,list_web_pages,get_web_page,get_web_page_allowed_content_types,create_web_page,create_web_page_language_variant,delete_web_page_language_variant,upload_asset,get_page_builder_components,get_page_builder_page_templates,get_page_builder_configuration,get_page_builder_available_editable_areas,get_page_builder_widget,get_page_builder_section,get_page_builder_page_template,add_page_builder_section,remove_page_builder_section,add_page_builder_widget,remove_page_builder_widget,update_page_builder_widget_properties,change_page_builder_page_template" ], "env": { "MANAGEMENT_API_URL": "http://localhost:5001/kentico-api/management", "MANAGEMENT_API_SECRET": "" } } } } ``` ## 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.