Kontent.ai MCP Server

[![NPM Version][npm-shield]][npm-url]
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
[![Discord][discord-shield]][discord-url]

> Transform your content operations with AI-powered tools for Kontent.ai. Create, manage, and explore your structured content through natural language conversations in your favorite AI-enabled editor.

Kontent.ai MCP Server implements the Model Context Protocol to connect your Kontent.ai projects with AI tools like Claude, Cursor, and VS Code. It enables AI models to understand your content structure and perform operations through natural language instructions.

✨ Key Features

🚀 Rapid prototyping: Transform your diagrams into live content models in seconds
📈 Data Visualisation: Visualise your content model in any format you want

Table of Contents

- ✨ Key Features
- 🔌 Quickstart
- 🛠️ Available Tools
- ⚙️ Configuration
- 🔒 Security
- 🚀 Transport Options
- 💻 Development
- 🛠 Local Installation
- 📂 Project Structure
- 🔍 Debugging
- 📦 Release Process
- License

🔌 Quickstart

🔑 Prerequisites

Before you can use the MCP server, you need:

1. A Kontent.ai account - Sign up if you don't have an account.
1. A project - Create a project to work with.
1. Management API key - Create a key with appropriate permissions.
1. Environment ID - Get your environment ID.

🛠 Setup Options

You can run the Kontent.ai MCP Server with npx:

STDIO Transport

npx @kontent-ai/mcp-server@latest stdio

Streamable HTTP Transport

npx @kontent-ai/mcp-server@latest shttp

🛠️ Available Tools

Patch Operations Guide

get-patch-guide – 🚨 REQUIRED before any patch operation. Get patch operations guide for Kontent.ai by entity type

get-content-type – Get Kontent.ai content type by ID
list-content-types – Get all Kontent.ai content types
create-content-type – Create new Kontent.ai content type
patch-content-type – Update an existing Kontent.ai content type by codename using patch operations (move, addInto, remove, replace)
delete-content-type – Delete a Kontent.ai content type by ID

Content Type Snippet Management

get-content-type-snippet – Get Kontent.ai content type snippet by ID
list-content-type-snippets – Get all Kontent.ai content type snippets
create-content-type-snippet – Create new Kontent.ai content type snippet
patch-content-type-snippet – Update an existing Kontent.ai content type snippet by ID using patch operations (move, addInto, remove, replace)
delete-content-type-snippet – Delete a Kontent.ai content type snippet by ID

get-taxonomy-group – Get Kontent.ai taxonomy group by ID
list-taxonomy-groups – Get all Kontent.ai taxonomy groups
create-taxonomy-group – Create new Kontent.ai taxonomy group
patch-taxonomy-group – Update Kontent.ai taxonomy group using patch operations (addInto, move, remove, replace)
delete-taxonomy-group – Delete Kontent.ai taxonomy group by ID

Content Item Management

get-content-item – Get Kontent.ai content item by ID
get-content-item-variant – Retrieve Kontent.ai content item variant (language version/translation). Returns the current version — draft if one exists, otherwise published
get-published-content-item-variant-version – Retrieve the published version of a Kontent.ai content item variant. Use when a newer draft version exists but you need the currently published (live) content
get-content-item-translations – Get all Kontent.ai content item translations — every language version (variant) of a specific content item
list-content-item-variants – List, filter, search Kontent.ai content items with content item variants (language versions/translations)
create-content-item – Create new Kontent.ai content item (creates the container only, use create-content-item-variant to add language versions/translations)
update-content-item – Update existing Kontent.ai content item by ID. The content item must already exist - this tool will not create new items
delete-content-item – Delete Kontent.ai content item by ID
create-content-item-variant – Create Kontent.ai content item variant assigning current user as contributor. Element values must fulfill limitations and guidelines defined in content type. Send only the elements you want to set; omitted ones initialize empty
update-content-item-variant – Update Kontent.ai content item variant of a content item. Element values must fulfill limitations and guidelines defined in content type. Send only the elements you want to change — omitted elements are left untouched. For rich-text elements with components, submit the full element (value plus the complete components array, including components that are left untouched)
create-new-content-item-variant-version – Create new version of Kontent.ai content item variant. This operation creates a new version of an existing content item variant, useful for content versioning and creating new drafts from published content
delete-content-item-variant – Delete Kontent.ai content item variant
bulk-get-content-item-variants – Bulk get Kontent.ai content items with their content item variants by item and language reference pairs. Use after list-content-item-variants to retrieve full content data for specific item+language pairs. Items without a variant in the requested language return the item without the variant property. Returns paginated results with continuation token
search-content-item-variants – AI-powered semantic search for finding content by meaning and concepts in a specific content item variant. Use for: conceptual searches when you don't know exact keywords. Limited filtering options (variant ID only)

Asset Management

get-asset – Get a specific Kontent.ai asset by ID
list-assets – Get all Kontent.ai assets
update-asset – Update Kontent.ai asset by ID

list-asset-folders – List all Kontent.ai asset folders
patch-asset-folders – Modify Kontent.ai asset folders using patch operations (addInto to add new folders, rename to change names, remove to delete folders)

list-languages – Get all Kontent.ai languages (includes both active and inactive - check is_active property)
create-language – Create new Kontent.ai language (languages are always created as active)
patch-language – Update Kontent.ai language using replace operations (only active languages can be modified - to activate/deactivate, use the Kontent.ai web UI)

Collection Management

list-collections – Get all Kontent.ai collections. Collections set boundaries for content items in your environment and help organize content by team, brand, or project
patch-collections – Update Kontent.ai collections using patch operations (addInto to add new collections, move to reorder, remove to delete empty collections, replace to rename)

Space Management

list-spaces – Get all Kontent.ai spaces
create-space – Create new Kontent.ai space for managing a website or channel
patch-space – Patch Kontent.ai space using replace operations
delete-space – Delete Kontent.ai space

Role Management

list-roles – Get all Kontent.ai roles. Requires Enterprise or Flex plan with "Manage custom roles" permission

list-workflows – Get all Kontent.ai workflows. Workflows define the content lifecycle stages and transitions between them
create-workflow – Create new Kontent.ai workflow with custom steps, transitions, scopes, and role permissions
update-workflow – Update an existing Kontent.ai workflow by ID. Modify steps, transitions, scopes, and role permissions. Cannot remove steps that are in use
delete-workflow – Delete a Kontent.ai workflow by ID. The workflow must not be in use by any content items
change-content-item-variant-workflow-step – Change the workflow step of a content item variant in Kontent.ai. This operation moves a content item variant to a different step in the workflow, enabling content lifecycle management such as moving content from draft to review, review to published, etc.
publish-content-item-variant – Publish or schedule a content item variant of a content item in Kontent.ai. This operation can either immediately publish the variant or schedule it for publication at a specific future date and time with optional timezone specification
unpublish-content-item-variant – Unpublish or schedule unpublishing of a content item variant of a content item in Kontent.ai. This operation can either immediately unpublish the variant (making it unavailable through the Delivery API) or schedule it for unpublishing at a specific future date and time with optional timezone specification

⚙️ Configuration

The server supports two modes, each tied to its transport:

| Transport | Mode | Authentication | Use Case |
|-----------|------|----------------|----------|
| STDIO | Single-tenant | Environment variables | Local communication with a single Kontent.ai environment |
| Streamable HTTP | Multi-tenant | Bearer token per request | Remote/shared server handling multiple environments |

Single-Tenant Mode (STDIO)

Configure credentials via environment variables:

| Variable | Description | Required |
|----------|-------------|----------|
| KONTENT_API_KEY | Your Kontent.ai key | ✅ |
| KONTENT_ENVIRONMENT_ID | Your environment ID | ✅ |
| appInsightsConnectionString | Application Insights connection string for telemetry | ❌ |
| projectLocation | Project location identifier for telemetry tracking | ❌ |
| manageApiUrl | Custom base URL (for preview environments) | ❌ |

Multi-Tenant Mode (Streamable HTTP)

For the Streamable HTTP transport, credentials are provided per request:
- Environment ID as a URL path parameter: /{environmentId}/mcp
- API Key via Bearer token in the Authorization header: Authorization: Bearer <api-key>

This allows a single server instance to handle requests for multiple Kontent.ai environments without requiring credential environment variables.

| Variable | Description | Required |
|----------|-------------|----------|
| PORT | Port for HTTP transport (defaults to 3001) | ❌ |
| appInsightsConnectionString | Application Insights connection string for telemetry | ❌ |
| projectLocation | Project location identifier for telemetry tracking | ❌ |
| manageApiUrl | Custom base URL (for preview environments) | ❌ |

🔒 Security

Indirect prompt injection

Content returned by this server (for example, an element written by an editor) can contain text that a connected LLM interprets as instructions — indirect prompt injection. A hijacked agent could be steered into destructive tool calls (delete / unpublish / overwrite) or into leaking unpublished drafts. This is an industry-wide, unsolved problem that the server cannot reliably fix by transforming the content it returns, so defense is layered:

- Use a least-privilege Management API key. The server acts with whatever key it is given. With a read-only key, a hijacked agent's destructive call simply fails at the API boundary — the strongest control, since it holds regardless of model behaviour.
- Keep a human in the loop. Every tool carries MCP annotations — reads are readOnlyHint, create-only tools are additive, and tools that overwrite or remove data are destructiveHint — which compliant clients use to auto-approve reads and prompt before destructive calls. Run the server with such a client and avoid headless auto-approve setups against a write-capable key.
- Add a client-side gate if your client supports one. Some clients (for example, Claude Code hooks) let you deterministically prompt before a destructive tool runs, independent of the model. This is configured locally; a server cannot enforce it.

These are hints, not guarantees. Report security issues privately to security@kontent.ai.

🚀 Transport Options

📟 STDIO Transport

To run the server with STDIO transport, configure your MCP client with:

{
  "kontent-ai-stdio": {
      "command": "npx",
      "args": ["@kontent-ai/mcp-server@latest", "stdio"],
      "env": {
        "KONTENT_API_KEY": "<management-api-key>",
        "KONTENT_ENVIRONMENT_ID": "<environment-id>"
      }
    }
}

🌊 Streamable HTTP Transport (Multi-Tenant)

Streamable HTTP transport serves multiple Kontent.ai environments from a single server instance. Each request provides credentials via URL path parameters and Bearer authentication.

First start the server:

npx @kontent-ai/mcp-server@latest shttp

<details>
<summary><strong>VS Code</strong></summary>

Create a .vscode/mcp.json file in your workspace:

{
  "servers": {
    "kontent-ai-multi": {
      "uri": "http://localhost:3001/<environment-id>/mcp",
      "headers": {
        "Authorization": "Bearer <management-api-key>"
      }
    }
  }
}

For secure configuration with input prompts:

{
  "inputs": [
    {
      "id": "apiKey",
      "type": "password",
      "description": "Kontent.ai API Key"
    },
    {
      "id": "environmentId",
      "type": "text",
      "description": "Environment ID"
    }
  ],
  "servers": {
    "kontent-ai-multi": {
      "uri": "http://localhost:3001/${inputs.environmentId}/mcp",
      "headers": {
        "Authorization": "Bearer ${inputs.apiKey}"
      }
    }
  }
}

</details>

<details>
<summary><strong>Claude Desktop</strong></summary>

Update your Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json

Use mcp-remote as a proxy to add authentication headers:

{
  "mcpServers": {
    "kontent-ai-multi": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3001/<environment-id>/mcp",
        "--header",
        "Authorization: Bearer <management-api-key>"
      ]
    }
  }
}

</details>

<details>
<summary><strong>Claude Code</strong></summary>

Add the server using the CLI:

claude mcp add --transport http kontent-ai-multi \
  "http://localhost:3001/<environment-id>/mcp" \
  --header "Authorization: Bearer <management-api-key>"

> Note: You can also configure this in your Claude Code settings JSON with the url and headers properties.

</details>

> [!IMPORTANT]
> Replace <environment-id> with your Kontent.ai environment ID (GUID) and <management-api-key> with your key.

💻 Development

🛠 Local Installation

```bash