--- title: Use 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/configure-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 provides guidance on working with the [Management MCP server](https://docs.kentico.com/documentation/developers-and-admins/api/management-api.md), including example prompts, CI integration, content versioning behavior, and troubleshooting. ## Use the MCP server Once the Management MCP server is [configured](https://docs.kentico.com/documentation/developers-and-admins/api/management-api/configure-management-mcp-server.md) and running, your AI agent automatically discovers and uses the available tools when processing relevant prompts. You interact with the server through your AI agent's interface. For details on how MCP tools work within your specific environment, refer to the official documentation of your IDE or AI client, for example: - [MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) - [MCP in Claude Code](https://code.claude.com/docs/en/mcp) - [MCP in Cursor](https://cursor.com/docs/context/mcp) - [MCP servers in Visual Studio](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=visualstudio) The tools of the Management MCP server carry standard [MCP tool annotations](https://modelcontextprotocol.io/specification/latest/server/tools) that describe their behavior. Tools that only retrieve data are marked as read-only, and tools that delete objects are marked as destructive. Depending on your AI client, you can use the annotations to decide which tool calls require your approval. > **Note:** If [Content versioning](https://docs.kentico.com/documentation/developers-and-admins/configuration/content-versioning-configuration.md) is enabled, each individual API call that modifies versioned content creates a separate version entry, which can lead to a long version history when performing a large number of operations. ### Continuous Integration [Continuous Integration](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-integration.md) (CI) serialization is automatically disabled for all management MCP requests to prevent issues with concurrent file operations. After completing a logical group of changes (a task, feature, or workflow), run CI store manually to serialize the changes to the repository: ```cmd title="Manually store CI data" dotnet run --no-build -- --kxp-ci-store ``` See [Store object data to the repository](https://docs.kentico.com/documentation/developers-and-admins/ci-cd/continuous-integration.md#store-object-data-to-the-repository) for more details. ### Upload assets To create or update a content item with a _Content item asset_ field, place your file in the [configured asset upload directory](https://docs.kentico.com/documentation/developers-and-admins/api/management-api/configure-management-mcp-server.md#configure-asset-uploads) and prompt the AI agent to create or update the content item using that file. The agent automatically handles the upload and references the asset in the content item. ### AI content marking When an AI agent creates or updates [content items](https://docs.kentico.com/documentation/business-users/content-hub/content-items.md) and [pages](https://docs.kentico.com/documentation/business-users/website-content.md), or adds and updates Page Builder widgets, it can set [AI content marking](https://docs.kentico.com/documentation/business-users/aira.md#ai-content-marking) for the content it writes. This is the same marking that editors set in the administration. The server doesn't detect AI-generated content on its own. The agent decides which marking to use based on how the content was created, and asks you when it's unsure. To help the agent choose correctly, say in your prompt whether the text you provide should be used as is or whether the agent can rewrite it. The agent can mark: - Fields that use the _Text input_, _Text area_, or _Rich text editor_ form component, or a [custom form component with the marking enabled](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components.md#enable-ai-content-marking). - Properties of Page Builder widgets with [AI content marking enabled](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/widget-properties.md#enable-ai-content-marking), such as the system _Rich text_ widget. The agent can still choose the wrong marking, so review the markings it sets. You're responsible for the final marking of your content. ## Example prompts Your AI agent can use the Management MCP server's tools when handling prompts related to the [supported objects](https://docs.kentico.com/documentation/developers-and-admins/api/management-api/reference-management-mcp-capabilities.md). For example: - "List all content types containing a field with the 'Content item asset' data type." - "Which content types use the 'Product SKU' reusable field schema?" - "Create a new workspace with code name 'marketing\_workspace' and display name 'Marketing workspace'." - "List all project languages and add 'French (France)' as a new language, with the 'fr-FR' Formatting culture and English as the fallback language." - "Create a new content type named 'Coffee cup' with fields 'Size', 'Color' and with the 'Product SKU' reusable field schema." - "On the 'Coffee Samples' landing page, add a testimonial widget before the existing one." - "Create a new content item of type 'Article' in the 'News' folder with the title 'Product Launch'." - "Write a short summary for the 'Product Launch' article and mark the field as AI generated." - "List all channels and their content type scopes." - "Create a new page under the 'About us' section using the 'Landing page' content type." - "Create a content item of type 'Image' and use sample.jpg as the file." - "Create a 'Newsletter signup' form with a required 'Email' field and a consent agreement field, and place it on the 'Contacts' page." ## Troubleshooting ### Certificate issues If your local application uses HTTPS and the MCP server reports certificate-related errors (for example, tool calls fail with the `Network.Tls` error code), configure Node.js to use the system certificate authority store. Set the following environment variable in the MCP server configuration: ```json title="mcp.json -- NODE_OPTIONS" "env": { "MANAGEMENT_API_URL": "http://localhost:5001/kentico-api/management", "MANAGEMENT_API_SECRET": "", "NODE_OPTIONS": "--use-system-ca" } ``` ### Server does not start If the Management MCP server does not start, make sure that: - A [supported version of Node.js](https://docs.kentico.com/documentation/developers-and-admins/installation/system-requirements.md#task-specific-requirements) is installed and available on your `PATH` so that `npx` can be executed. - The package name is `@kentico/management-api-mcp@latest`. - The MCP server configuration uses the correct format for your AI client or IDE. The provided [configuration examples](https://docs.kentico.com/documentation/developers-and-admins/api/management-api/configure-management-mcp-server.md#add-the-mcp-server) are suited for [VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers), [Claude Code](https://code.claude.com/docs/en/mcp#option-3-add-a-local-stdio-server), and [Cursor](https://cursor.com/docs/context/mcp). ### Authentication fails or no tools are shown If the MCP server starts but authentication fails or no tools appear, check the server's log for the reason, and verify the following: - The local Xperience application is running and the management API is [enabled](https://docs.kentico.com/documentation/developers-and-admins/api/management-api/configure-management-mcp-server.md#enable-the-management-api). - `MANAGEMENT_API_URL` points to the correct local URL and includes the `/kentico-api/management` path. - `MANAGEMENT_API_SECRET` matches the secret configured in `AddKenticoManagementApi()` and has at least 32 characters. If the secret is incorrect, tools are listed, but every tool call fails with the _401_ status code and the `Auth.InvalidToken` error code. - [Tool filtering options](https://docs.kentico.com/documentation/developers-and-admins/api/management-api/configure-management-mcp-server.md#limit-the-available-tools) do not hide all tools. - Group and tool names in the filtering options are spelled correctly. The server reports unknown names in its log and continues, so a typo results in fewer available tools instead of an error. Run the server with the `--list-groups` option to see the group names of your instance (see [Tool groups](https://docs.kentico.com/documentation/developers-and-admins/api/management-api/configure-management-mcp-server.md#tool-groups)). - Your AI client has been restarted after configuration changes. ### Tool calls fail When a tool call fails, the Management MCP server returns a structured error to the AI agent. The error contains the HTTP status code (if the management API responded), an error code that identifies the problem (for example, `Workspace.NotFound`), a description of the problem, and the method and URL of the failed request. If specific values in the request are invalid, the error also lists each invalid value and the reason. Agents use the error code to decide how to recover from the failure. The description of each tool lists the error codes that the tool can return. The prefix of the error code indicates the area of the problem: | Error code prefix | Meaning | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Auth` | The secret is missing or does not match the secret configured in the application. See [Authentication fails or no tools are shown](#authentication-fails-or-no-tools-are-shown). | | `Request` | The management API could not process the request, for example, because the request contains malformed data or properties that do not exist. | | `Internal` | An unexpected error occurred in the application. Check the [event log](https://docs.kentico.com/documentation/developers-and-admins/configuration/event-log.md) for details. | | `Mcp` | The MCP server rejected the tool call before sending a request to the management API, for example, because the arguments do not match the tool's input schema. The `Mcp.ToolCatalogEmpty` code indicates that the server has not yet loaded the available tools, usually because the Xperience application is not running. | | `Network` | The MCP server could not connect to the Xperience application, for example, `Network.ConnectionRefused` when the application is not running or `Network.Tls` for [certificate issues](#certificate-issues). | | Other | The management API refused the operation, for example, because an object does not exist (`Workspace.NotFound`), a code name is already taken (`Workspace.NameAlreadyExists`), or an object is still in use (`Workspace.InUse`). | Each error returned by the management API includes a trace identifier (`traceId`). The [event log](https://docs.kentico.com/documentation/developers-and-admins/configuration/event-log.md) entries related to the failed request contain the same identifier. Unexpected errors are always logged. Most other rejected requests are logged with the `Debug` level. To include them in the event log, add configuration for the `Kentico.Xperience.ManagementApi` namespace to the `XperienceEventLog` provider (see [Configure logging](https://docs.kentico.com/documentation/developers-and-admins/development/logging.md#configure-logging)). If the application runs in the `Development` environment, errors caused by unexpected exceptions also include the exception's type and message. ### Unexpected AI behavior If the AI agent selects unrelated tools or produces unfocused results, try reducing the number of available tools: - Use `--enabled-groups` to expose only the tool groups needed for the current scenario. - Use `--enabled-tools` and `--disabled-tools` to add or remove individual tools. - Use `--dynamic-tools` to reduce the initial tool footprint. - Use `--tool-search` if your AI client struggles with the number of tools and does not provide its own tool search. - Add project-specific AI instructions to guide the agent. - Ask the agent to summarize intended changes before executing them. See [Limit the available tools](https://docs.kentico.com/documentation/developers-and-admins/api/management-api/configure-management-mcp-server.md#limit-the-available-tools) for configuration details.