Contentstack MCP Server

Experimental: This MCP server is still experimental. Features and tool schemas may change without notice. Use it in production at your own risk.

A complete guide for setting up, configuring, and using the Contentstack MCP Server with AI agents and tools.

What is the Contentstack MCP Server?

The Model Context Protocol

The Model Context Protocol (MCP) is an open standard that lets AI agents (Claude, Cursor, and others) connect to external systems through a common interface. Instead of writing bespoke integration code every time you want an AI to talk to an API, you run an MCP server that exposes those APIs as structured, typed tools. The agent calls those tools and interprets the results in natural language.

What this server does

The Contentstack MCP Server bridges your Contentstack stack and related services, the Content Management API, Content Delivery API, Analytics, Launch, BrandKit, Personalize, Developer Hub, and Lytics to any MCP-compatible AI agent.

Once configured, your AI agent can:

• Read, create, update, publish, and unpublish entries and assets in plain language
• Inspect audit logs, version history, and workflow stages
• Trigger deployments, check logs, and revalidate CDN caches in Launch
• Generate on-brand content via BrandKit AI using voice profiles and a knowledge vault
• Query audience segments, user profiles, and A/B test results in Personalize and Lytics
• Manage Marketplace apps and OAuth settings in Developer Hub
• Pull API usage, cache hit rates, and SDK adoption metrics from Analytics

Who it's for

• Developers building AI-powered content workflows or automations
• Content architects who want an agent to help audit, model, or migrate content
• DevRel and solutions engineers demonstrating Contentstack capabilities with AI
• AI workflow builders connecting Contentstack to agent frameworks and pipelines

Prerequisites

Before you start, make sure you have:

• An active Contentstack account
• Node.js 18 or later installed locally (required to run npx)
• A supported MCP client:
  • Claude Desktop (macOS / Windows)
  • Cursor
  • Claude Code (CLI)
  • Any other MCP client that supports stdio transport

Authentication

Most API groups require OAuth authentication. Run this command once before using the server:

npx @contentstack/mcp --auth

This opens a browser window. You will:

• Log in to your Contentstack account
• Select your region (US, EU, AU, etc.)
• Select your organisation
• Grant the MCP server access

The resulting OAuth tokens are saved locally on your machine. They are reused automatically by the server on subsequent runs — you do not need to re-authenticate unless your tokens expire.

Which groups require OAuth?

CDA and Lytics do not use OAuth. They authenticate with static tokens you provide in environment variables.

Installation

No installation or repository cloning is needed. The server runs on demand via npx:

npx @contentstack/mcp

The -y flag (used in MCP client configs) automatically confirms the npx prompt, so the agent can start the server without human input:

npx -y @contentstack/mcp

npx pulls the latest published version of @contentstack/mcp from npm each time it runs. This means you always get the latest tool definitions without a manual upgrade step.

Configuration

The server is configured through environment variables or equivalent CLI arguments. Both work identically, use whichever your MCP client supports.

Environment variables

You only need to provide the variables relevant to the groups you are enabling. For example, if you load only cma, you need only CONTENTSTACK_API_KEY. If you add cda, you also need CONTENTSTACK_DELIVERY_TOKEN.

Where to find your credentials

• Stack API Key: Contentstack Dashboard → Settings → API Credentials
• Delivery Token: Contentstack Dashboard → Settings → Tokens → Delivery Tokens → create one for your target environment
• Brand Kit ID: BrandKit Dashboard → your brand kit's settings page
• Launch Project ID: Launch Dashboard → your project's URL or settings
• Personalize Project ID: Personalize Dashboard → your project's settings
• Lytics Access Token: Lytics account settings → API Tokens

The GROUPS variable

The GROUPS variable controls which API toolsets are exposed to the agent. Loading only what you need is good practice — it reduces the volume of tool definitions sent to the model on every turn, keeping context windows lean and responses focused.

Examples:

GROUPS=cma


GROUPS=cma,cma-extended


GROUPS=cma,cda


GROUPS=all

MCP Client Setup

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows.

Option A — Environment variables (recommended):

{
  "mcpServers": {
    "contentstack": {
      "command": "npx",
      "args": ["-y", "@contentstack/mcp"],
      "env": {
        "CONTENTSTACK_API_KEY": "<YOUR_STACK_API_KEY>",
        "CONTENTSTACK_DELIVERY_TOKEN": "<YOUR_DELIVERY_TOKEN>",
        "CONTENTSTACK_BRAND_KIT_ID": "<YOUR_BRAND_KIT_ID>",
        "CONTENTSTACK_LAUNCH_PROJECT_ID": "<YOUR_LAUNCH_PROJECT_ID>",
        "CONTENTSTACK_PERSONALIZE_PROJECT_ID": "<YOUR_PERSONALIZE_PROJECT_ID>",
        "LYTICS_ACCESS_TOKEN": "<YOUR_LYTICS_TOKEN>",
        "GROUPS": "cma"
      }
    }
  }
}

Only include the env vars relevant to the groups you are enabling. Remove keys you do not need.

Option B — CLI arguments (use if your client does not support env vars):

{
  "mcpServers": {
    "contentstack": {
      "command": "npx",
      "args": [
        "-y",
        "@contentstack/mcp",
        "--stack-api-key",
        "<YOUR_STACK_API_KEY>",
        "--delivery-token",
        "<YOUR_DELIVERY_TOKEN>",
        "--brand-kit-id",
        "<YOUR_BRAND_KIT_ID>",
        "--launch-project-id",
        "<YOUR_LAUNCH_PROJECT_ID>",
        "--lytics-access-token",
        "<YOUR_LYTICS_TOKEN>",
        "--personalize-project-id",
        "<YOUR_PERSONALIZE_PROJECT_ID>",
        "--groups",
        "cma"
      ]
    }
  }
}

After editing the file, restart Claude Desktop to pick up the changes.

Cursor

Edit ~/.cursor/mcp.json (create it if it does not exist):

{
  "mcpServers": {
    "contentstack": {
      "command": "npx",
      "args": ["-y", "@contentstack/mcp"],
      "env": {
        "CONTENTSTACK_API_KEY": "<YOUR_STACK_API_KEY>",
        "GROUPS": "cma"
      }
    }
  }
}

Restart Cursor after saving.

Claude Code (CLI)

Use the claude mcp add command to register the server:

claude mcp add contentstack \
  --command "npx" \
  --args "-y,@contentstack/mcp" \
  --env "CONTENTSTACK_API_KEY=<YOUR_API_KEY>,GROUPS=cma"

Other MCP clients

The Contentstack MCP Server uses stdio transport, which is the standard for locally-run MCP servers. Any MCP client that supports stdio should work with the same configuration pattern: point the client at npx -y @contentstack/mcp and pass your credentials via environment variables or CLI arguments.

API Groups - what to load and when

Group Requirements Summary

Common Workflows

Once configured, you interact with Contentstack entirely through natural language. Here are examples of what agents can do with different groups enabled.

Content management (CMA):

• "Get all entries for the article content type that were published in the last 30 days"
• "Create a new entry in blog_post with the title 'Getting started with MCP' and publish it to the production environment"
• "Show me all entries that reference the asset with UID blt1234abcd"
• "Create a branch called feature/new-homepage from main and add the hero entry to a release"
• "What environments does this stack have, and which locales are configured?"

Auditing and investigation (CMA, CMA-extended):

• "Show me the audit log for the last 24 hours - who changed what?"
• "What versions exist for entry blt9abc in the product content type? Label version 4 as 'Pre-launch approved'"
• "Which workflow stages require approval before an entry can be published?"

Content delivery (CDA):

• "Fetch the latest published entries from the homepage_banner content type on the production environment"
• "What does the live version of entry blt5678efgh look like right now?"

Deployments (Launch):

• "What's the current deployment status of the staging environment?"
• "Fetch the build logs from the last deployment — did it fail anywhere?"
• "Trigger the deploy hook for the production environment"
• "Revalidate the CDN cache after I update the hero entry"

Brand content (Brandkit):

• "Generate a product description for a new running shoe using the 'Active lifestyle' voice profile"
• "Add the updated brand guidelines document to the Knowledge Vault"
• "What voice profiles are available in my Brand Kit?"

Personalization (Personalize):

• "Show me all active A/B test experiences and their current conversion rates"
• "Create a new audience segment for users in Germany who have viewed more than 3 product pages"
• "What's the analytics summary for experience version ver_abc123 over the last 7 days?"

Troubleshooting

Tool Catalog

Full reference for every tool exposed by each group.

Content Management API (CMA)

Content Management API Extended (CMA Extended)

Load alongside cma with GROUPS=cma,cma-extended.

Content Delivery API (CDA)

Analytics API

All analytics tools are asynchronous: they return a jobId that you pass to get_job_data to retrieve results.

BrandKit AI

Launch API

Developer Hub

Lytics Analytics

Personalize API