---
title: "Production, performance and AI"
url: "https://developers.contentstack.com/paths/production-performance-and-ai"
type: "path_full"
level: "advanced"
outcome: "A fast, well-cached production setup with a migration plan, AI agents connected to your stack and a personalization architecture"
steps:
  - "https://developers.contentstack.com/guides/reducing-api-calls-to-boost-performance-and-stay-within-rate-limits"
  - "https://developers.contentstack.com/livestreams/cache-priming-magic"
  - "https://developers.contentstack.com/guides/migrating-from-the-javascript-delivery-sdk-to-the-typescript-delivery-sdk"
  - "https://developers.contentstack.com/guides/migrating-from-contentful-to-contentstack-in-depth"
  - "https://developers.contentstack.com/guides/set-up-your-ai-workbench-for-contentstack"
  - "https://developers.contentstack.com/guides/how-to-build-your-own-mcp-server-with-contentstack-s-tools-api"
  - "https://developers.contentstack.com/blog/how-mcp-profile-hub-enriches-tools-for-your-stack"
  - "https://developers.contentstack.com/blog/understanding-how-contentstack-cms-personalize-and-lytics-work-together"
  - "https://developers.contentstack.com/guides/lytics-use-cases-and-technical-implementation-guide"
updated: "2026-11-16T13:32:25.303Z"
---

# Production, performance and AI

- **Level:** Advanced
- **Steps:** 9
- **Overview:** https://developers.contentstack.com/paths/production-performance-and-ai.md

---

For teams running Contentstack in production: keep API usage and latency in check, migrate safely, and connect AI tooling and personalization.

**You'll end up with:** A fast, well-cached production setup with a migration plan, AI agents connected to your stack and a personalization architecture

## Table of Contents

1. Reducing API Calls to Boost Performance and Stay Within Rate Limits
2. Cache Priming Magic!
3. Migrating from the JavaScript Delivery SDK to the TypeScript Delivery SDK
4. Migrating from Contentful to Contentstack in depth
5. Set up your AI workbench for Contentstack
6. How to build your own MCP server with Contentstack's tools API
7. How MCP Profile Hub enriches tools for your stack
8. Understanding how Contentstack CMS, Personalize, and Lytics work together
9. Lytics use cases and technical implementation guide


---

## Step 1: Reducing API Calls to Boost Performance and Stay Within Rate Limits

- **Source:** https://developers.contentstack.com/guides/reducing-api-calls-to-boost-performance-and-stay-within-rate-limits
- **Checkpoint:** Your site serves most traffic from cache and stays within rate limits

- **Authors:** Lo Etheridge
- **Published:** 2026-01-22
- **Updated:** 2026-11-10T16:27:25.575Z
- **Level:** Advanced
- **Intent:** Ship
- **Tags:** headless, api, sdk

---

In this post, we discussed a website that was making an excessive millions of API calls per day, completely negating all the benefits of having a cutting-edge [Next.js](http://next.js) website powered by Contentstack as the headless CMS. Our team at XCentium was able to demonstrate our knowledge and expertise around the issue and implement a new strategy centered around CDN caching and automation to bring them down to thousands of API calls per day. Showing how working with an expert can prevent costly pitfalls and unlock the full value of a headless CMS architecture.

## Key Takeaways

- Identifying Insufficiencies is Crucial: A lack of understanding and unchecked features like Link prefetching and SSR configurations can inadvertently drive up API requests and costs.


- Caching Leveraging CDN Cache and Automation: Serving pages from the CDN cache and revalidating through Contentstack’s automations sharply reduced the API usage and increased performance.


- Expert Implementation Pays Off: Implementing the right technical solutions and best practices is essential to success with a headless CMS and it is not all about technology choice.



## The Motivation

In today’s digital landscape, transitioning from a traditional CMS to a headless CMS promises big gains in efficiency, scalability, and flexibility. This move enables organizations to deliver content seamlessly across multiple platforms, boost site performance, and future-proof their digital strategy. However, it’s essential to approach implementation with the right expertise and planning to avoid common pitfalls that can negate these benefits. I want to discuss a situation where a site with Next.js was making roughly millions of API calls per day, and how we were able to get that down to just thousands of calls per day!

![](https://images.contentstack.io/v3/assets/blt77d44a06c81b1730/bltfaf6f2bc6b228ff2/696a58827d6f880008c57cd0/Waller-api-calls.png)

You can easily see when our optimizations took effect.

This was a critical issue for the website because they were making way too many redundant and unnecessary API calls, which were compromising the performance and scalability of the site as driving up the costs.

## Understanding the problem

- [Next.js Link Pre-Fetching:](http://next.js) Normally, Next.js Links optimize the user experience, making navigation near instantaneous and smooth. It does this by prefetching the pages for each link in the background, which in this case, was leading to all those excessive and redundant API calls.


- SSR and SSG Confusion: Prefetching pages really only optimizes Static Site Generation (SSG) pages. Because when using SSR, the API calls must be made every time a page is fetched. With SSG, the API only needs to be called once per page on build.


- ISR Incompatibility: Incremental Static Generation sounds like it would be the perfect solution here, but there are some issues with on-demand revalidation (topic for another day)



What the problem looked like in practice is, anywhere on the page, there was a link that was visible. Next.js would go and fetch that page in the background, and in doing so, it would also make any API calls found on that page as well. Leading to not just the api calls needed for the page you are on being made, but any page linked on that page as well. So, in our case, a homepage that should only be making 6 API calls is making more than 150 API calls, which was a major concern. 

![](https://images.contentstack.io/v3/assets/blt77d44a06c81b1730/bltdcfaec4a0cf1138c/696a5d086a4a390008c1cf7c/nextjs_prefetch.png)

Our solution was to refine our SSR approach to leverage our CDN and deliver pages through the CDN cache. This means now every time a page is called, instead of hitting the API directly, if it's already cached then we will just serve that page directly from the CDN. Now this solves the redundant API calls we were making but also introduces a new issue. If new content is published in Contentstack we need to know, to invalidate the cache for those specific pages and serve the new content and not old content.

![](https://images.contentstack.io/v3/assets/blt77d44a06c81b1730/bltcb7fff9e62548561/696a5e704d142b0008298370/Screenshot_2026-01-16_at_10.48.18.png)

For this issue, we created an automation recipe in Contentstack that triggered on publish of any content entry and will revalidate the cache in the CDN. You can think of it as similar to using ISR and having a webhook revalidate the cache on publish.

![](https://images.contentstack.io/v3/assets/blt77d44a06c81b1730/blt9d9986fd500a7f1b/696a606b5d36f600087261f2/contentstack_automate.png)

## Conclusion

The transition to a headless architecture with Next.js and Contentstack offers immense potential, but as this case demonstrates, the "how" is just as important as the "what". By identifying the specific conflict between Next.js prefetching and SSR, and implementing a robust strategy centered on CDN caching and automated revalidation, we turned a critical performance bottleneck into a scalable success. Reducing API calls from millions to thousands isn't just a technical victory; it proves that expert implementation is key to unlocking the true efficiency and ROI of your digital strategy.




---

## Frequently asked questions

### How did optimizing CDN caching reduce API calls on the website?

By leveraging CDN caching and only revalidating caches when new content was published, the site ensured pages were served from cache, drastically reducing the number of direct API calls made for each page load.

### What caused the excessive API calls in the original Next.js setup?

Unchecked features like Next.js Link prefetching and confusion between SSR and SSG resulted in many redundant API requests, as every visible link triggered background fetches causing unnecessary API usage.

### Why is expert implementation important for headless CMS architectures?

Expert implementation helps avoid common technical pitfalls, ensures optimal performance, and allows organizations to fully realize the efficiency, flexibility, and cost benefits of a headless CMS.



---

> **Originally written here:** [https://www.contentstack.com/blog/partner-solutions/reducing-api-calls-to-boost-performance-and-stay-within-rate-limits](https://www.contentstack.com/blog/partner-solutions/reducing-api-calls-to-boost-performance-and-stay-within-rate-limits)

---

## Step 2: Cache Priming Magic!

- **Source:** https://developers.contentstack.com/livestreams/cache-priming-magic
- **Checkpoint:** You know how to warm caches after a deploy

- **Hosts:** Lo Etheridge, Tim Benniks
- **Published:** 2025-06-24T22:00:00.000Z
- **Updated:** 2026-11-10T15:04:30.284Z
- **Level:** Advanced
- **Intent:** Ship
- **Tags:** headless
- **Watch:** https://www.youtube.com/watch?v=j9NPo_ba2Po

---

Join Tim & Lo with special guest Dean Haddock, Group PM for Platform and Hosting, for an in-depth conversation about implementing caching to reduce server lo...



---

## About this livestream

Join Tim & Lo with special guest Dean Haddock, Group PM for Platform and Hosting, for an in-depth conversation about implementing caching to reduce server lo...



---

> **Originally written here:** [https://www.youtube.com/watch?v=j9NPo_ba2Po](https://www.youtube.com/watch?v=j9NPo_ba2Po)

---

## Step 3: Migrating from the JavaScript Delivery SDK to the TypeScript Delivery SDK

- **Source:** https://developers.contentstack.com/guides/migrating-from-the-javascript-delivery-sdk-to-the-typescript-delivery-sdk
- **Checkpoint:** You are on the TypeScript Delivery SDK

- **Authors:** Tim Benniks
- **Published:** 2026-04-27
- **Updated:** 2026-11-10T16:27:24.044Z
- **Level:** Intermediate
- **Intent:** Build
- **Tags:** sdk, api

---

> **Full guide available:** [View all 8 chapters in one document](https://developers.contentstack.com/guides/migrating-from-the-javascript-delivery-sdk-to-the-typescript-delivery-sdk/full.md)

## What this guide is for

This guide is for developers who already use the Contentstack JavaScript Delivery SDK and want to move to the TypeScript Delivery SDK without rewriting their entire website.

The migration is mostly an SDK API migration, not a language migration. You will update imports, initialization, stack calls, entry calls, asset calls, query chains, caching setup, and utility package usage. If your frontend is written in JavaScript, you can still use the TypeScript Delivery SDK from JavaScript files.

## Why this guide exists

The TypeScript Delivery SDK gives teams a modern Contentstack delivery client with stronger typing for projects that want it, a cleaner chainable API, and current package boundaries for caching and utility behavior.

That does not mean every project has to become a TypeScript project on day one. A JavaScript codebase can install and call @contentstack/delivery-sdk just like any other npm package. TypeScript support is available when you want it, but it is not a requirement for running the SDK.

Use this guide as a practical migration path:

- start by replacing the package and stack initialization


- migrate reads behind a small Contentstack wrapper


- update entries, assets, content types, and queries in predictable groups


- handle caching and utilities as separate packages when your app needs them


- verify behavior with existing pages before removing the old SDK



Useful references:

- [TypeScript Delivery SDK reference](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/typescript/reference)


- [JavaScript Delivery SDK reference](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/javascript-browser/reference)


- [Migration from JavaScript to TypeScript Delivery SDK](https://www.contentstack.com/docs/developers/sdks/content-delivery-sdk/typescript/migrate-from-javascript-to-typescript)



## How to use this guide

- If you are planning the migration, start with chapters 1 and 2.


- If you are already editing code, chapters 3 and 4 are the main translation map.


- If your app uses cache policies, Live Preview, rich text utilities, or Visual Builder helpers, read chapter 5 before you merge.


- If your team is worried that the new SDK forces a full TypeScript conversion, read chapter 6 first.


- If you want an AI coding agent to help with the migration, point it at chapter 8.






---

## Frequently asked questions

### Do I need to convert my entire project to TypeScript to use the TypeScript Delivery SDK?

No. You can install and use @contentstack/delivery-sdk from JavaScript files; TypeScript typing is optional.

### What changes are typically required when migrating to the TypeScript Delivery SDK?

Expect updates to imports, SDK initialization, stack calls, entry and asset reads, query chains, caching setup, and utility package usage.

### Is this migration primarily a language migration or an SDK API migration?

It is primarily an SDK API migration. The goal is to translate calls and patterns without rewriting the site.

### What is a practical approach to migrating without breaking existing pages?

Replace the package and stack initialization first, migrate reads behind a small wrapper, update entries/assets/queries in groups, then verify pages before removing the old SDK.

### When should I review caching, Live Preview, rich text utilities, or Visual Builder helpers during the migration?

Review these before merging if your app depends on cache policies, Live Preview, rich text utilities, or Visual Builder helpers, since they may move to separate packages or change usage.


---

## Step 4: Migrating from Contentful to Contentstack in depth

- **Source:** https://developers.contentstack.com/guides/migrating-from-contentful-to-contentstack-in-depth
- **Checkpoint:** You can plan and verify a Contentful to Contentstack migration

- **Authors:** Tim Benniks
- **Published:** 2026-06-11
- **Updated:** 2026-11-10T16:27:21.341Z
- **Level:** Advanced
- **Intent:** Build
- **Tags:** cli, automation, ai

---

> **Full guide available:** [View all 7 chapters in one document](https://developers.contentstack.com/guides/migrating-from-contentful-to-contentstack-in-depth/full.md)

## What this guide is for

This guide is for developers moving a project from Contentful to Contentstack. It covers both the content migration (content types, entries, assets, locales, and more) and the application code that reads from the CMS.

There are two ways to run the migration, and this guide documents both. The guided path uses an AI skill that runs in an agentic chat window and orchestrates the migration for you. The expert path uses the Contentstack CLI plugin directly, one command at a time. Both paths run the same underlying tooling, so you can switch between them.

## How to use this guide

- If you want the fastest route, read chapters [The guided path: migrate with the AI skill](/guides/migrating-from-contentful-to-contentstack-in-depth/the-guided-path-migrate-with-the-ai-skill) and [The expert path: migrate with CLI commands](/guides/migrating-from-contentful-to-contentstack-in-depth/the-expert-path-migrate-with-cli-commands) and let the AI skill drive.


- If you want full control over each step, read chapters [The guided path: migrate with the AI skill](/guides/migrating-from-contentful-to-contentstack-in-depth/the-guided-path-migrate-with-the-ai-skill) and [Migrating your application code](/guides/migrating-from-contentful-to-contentstack-in-depth/migrating-your-application-code) for the CLI commands and flags.


- If you need to migrate application code, read chapter [What migrates, what needs manual work, and how to verify](/guides/migrating-from-contentful-to-contentstack-in-depth/what-migrates-what-needs-manual-work-and-how-to-verify).


- Before you treat the migration as done, read chapter [Troubleshooting and next steps](/guides/migrating-from-contentful-to-contentstack-in-depth/troubleshooting-and-next-steps) for the validation checklist and the known limitations.



## What this tool does and how it works

The migration is built from two pieces that work together: an AI skill and a Contentstack CLI plugin called @contentstack/cli-external-migrate. The skill handles orchestration and explanation. The plugin handles the actual data work.

One principle governs the whole design: the AI guides, the tooling executes. The AI never transforms your content. It reads your environment, decides which steps to run, executes trusted CLI commands, explains each decision, and validates the result. The export, conversion, and import all run through deterministic CLI tooling. This keeps the migration transparent and repeatable, which matters when you point it at a real space.

## What you'll learn

- How the AI skill and the CLI plugin divide responsibilities


- Which platform differences the migration handles for you


- What a full run produces on disk


- When to choose the guided path over the expert path



## The two paths

The guided path runs inside an agentic chat window. You describe what you want to migrate, and the skill checks prerequisites, runs the migration, shows progress, and produces a summary. It executes the same commands you would run by hand, so nothing is hidden.

The expert path runs the CLI commands yourself. You get the same export, conversion, audit, and import steps as discrete commands with flags you control. Use this path when you want to inspect intermediate output, script the migration, or run a subset of steps.

## How platform differences are handled

Contentful and Contentstack model some things differently, and the tooling translates between them:

- Contentful environments map to Contentstack branches (master maps to main).


- Contentful rich text converts to Contentstack JSON Rich Text Editor (RTE) format, with embedded entries and assets preserved as references.


- Contentful references resolve to Contentstack reference fields, which return arrays rather than single objects.


- Contentful roles map to built-in Contentstack roles where they match, and to custom roles where they do not.


- DAM marketplace app fields (Cloudinary, Bynder, Brandfolder, Frontify, Digizuite, Aprimo) map to the correct Contentstack asset shape.



## What a run produces

A full content run creates a fresh Contentstack stack in your organization and writes a set of artifacts to your workspace directory: the Contentful export JSON, a Contentstack import bundle, a mapper.json that records the field-UID mapping between source and target, a metadata.json with the new stack's credentials, and import logs. The code migration uses the mapper and metadata files, so keep the workspace directory until the whole migration is done.

## Key takeaways

- The AI skill orchestrates; the CLI plugin does the data work.


- The AI never transforms content directly, which keeps the migration safe and repeatable.


- The tooling translates platform differences such as environments, rich text, references, and roles.


- A run produces an export, a bundle, a field mapper, stack credentials, and logs.






---

## Frequently asked questions

### What are the two ways to run the migration from Contentful to Contentstack?

Use the guided path in an agentic chat window (AI skill orchestration) or the expert path by running @contentstack/cli-external-migrate commands directly.

### Does the AI skill transform or modify content during the migration?

No. The AI guides and orchestrates deterministic CLI commands; export, conversion, and import are executed by the CLI tooling for repeatable results.

### How are common platform differences handled during migration?

The tooling translates key differences, including environments to branches, rich text to Contentstack JSON RTE, references to reference fields, and role mappings.

### What files and artifacts does a full migration run produce?

It creates a new Contentstack stack and writes artifacts such as the Contentful export JSON, a Contentstack import bundle, mapper.json, metadata.json, and import logs.

### Why should you keep the workspace directory after the content migration completes?

The code migration relies on mapper.json and metadata.json to map fields and access the new stack, so the workspace is required until the full migration is done.


---

## Step 5: Set up your AI workbench for Contentstack

- **Source:** https://developers.contentstack.com/guides/set-up-your-ai-workbench-for-contentstack
- **Checkpoint:** Your agent has the Contentstack skills and a Profile Hub profile connected

- **Authors:** Tim Benniks
- **Published:** 2026-12-01T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:27.208Z
- **Level:** Beginner
- **Intent:** Build
- **Tags:** ai, agent_skills, mcp

---

An AI agent that writes Contentstack code from memory guesses. It invents SDK methods, assumes a product content type you don't have, and confuses delivery and preview tokens. Two things fix that. Agent skills give the agent Contentstack knowledge, and MCP Profile Hub gives it tools to look at your actual stack.

This guide sets up both in about ten minutes. Every "Do this with AI" tip on this site assumes the setup below, so it's the page to come back to when a tip asks you to install a skill or connect a profile.

## What you'll learn

- What skills and profiles each do, and why you want both


- How to install the Contentstack agent skills in your AI tool


- How to connect MCP Profile Hub with a narrow, read-only profile


- How to check that everything works


- Three first tasks to try


- The safety rules that apply to every profile



## Skills and profiles do different jobs

Contentstack concept: a skill is a folder with a SKILL.md file that teaches an agent how to do one kind of Contentstack task. The agent sees each skill's name and description, and loads the full instructions when your request matches. Skills contain knowledge and rules. They don't call any API.

Contentstack concept: a profile is a named set of tools in MCP Profile Hub, served from one hosted URL over the Model Context Protocol (MCP). A profile decides which tools the agent can call. When the agent connects, Profile Hub fills those tools with your real content types, locales, environments and branches.

If you know VS Code, think of skills as the language extension that knows the syntax, and the profile as the debugger that can inspect the running program. You can use one without the other, but the agent is much more useful with both.


Agent skills

MCP Profile Hub

Gives the agent

Contentstack knowledge and rules

Tools that read or change your stack

Lives

In your AI tool, as a plugin or extension

Hosted at mcp-profile-hub.contentstack.com

Needs a Contentstack login

No

Yes, OAuth in the browser

Example

dx-delivery-sdk knows the correct query chain order

Content Explorer lists your content types

## Step 1: install the skills

The skills live in one public repository, [contentstack/contentstack-agent-skills](https://github.com/contentstack/contentstack-agent-skills). Every tool installs the whole bundle, and the agent picks the right skill based on what you ask.

Claude Code. In a session, run:

```text
/plugin marketplace add contentstack/contentstack-agent-skills
/plugin install contentstack-skills@contentstack-skills
```

claude.ai and Claude Cowork. Go to Customize → Plugins → Add marketplace and enter contentstack/contentstack-agent-skills. The skills sync to Claude Code too.

Cursor. Open Settings → Plugins, choose Add from GitHub repository, and enter https://github.com/contentstack/contentstack-agent-skills.

Codex.

```bash
codex plugin marketplace add contentstack/contentstack-agent-skills
codex plugin add contentstack-skills@contentstack-skills
```

GitHub Copilot CLI.

```bash
copilot plugin marketplace add contentstack/contentstack-agent-skills
copilot plugin install contentstack-skills@contentstack-skills
```

In VS Code, add "contentstack/contentstack-agent-skills" to the chat.plugins.marketplaces setting, then install contentstack-skills from the Extensions view.

Gemini CLI.

```bash
gemini extensions install https://github.com/contentstack/contentstack-agent-skills
```

If you only want one or two skills, the skills CLI installs them into the right folder for most agents:

```bash
npx skills add contentstack/contentstack-agent-skills --skill dx-delivery-sdk --skill cms-entries
```

Some skills only run when you ask for them by name, such as the Launch deployment skill. In Claude Code you call those as slash commands, for example /contentstack-skills:launch-trigger-and-monitor-launch-deployments.

## Step 2: connect MCP Profile Hub

The plugin install already adds Profile Hub as an MCP server named contentstack, pointing at the public URL:

```text
https://mcp-profile-hub.contentstack.com/api/mcp
```

The public URL carries no profile or stack, so the first time the agent uses a tool, a browser opens and asks for them:

- Under Select your region, choose where your organization is hosted, for example AWS Europe.


- Sign in to Contentstack and approve access.


- Check that the connect screen names your AI tool, for example Connect Cursor to Contentstack. If you didn't start this connection, close the window.


- Confirm the Organization and pick a Profile from Standard profiles. Pick Content Explorer.


- Choose the Stack, then click Connect.



The connection keeps that profile and stack until you remove and re-add the server.

### Pick a narrow profile, not CMS

The standard profiles include the product profiles: CMS, Launch, Personalize and so on. Those expose a product's whole toolset, including tools that delete and publish. Start with Content Explorer instead. It reads content types, entries, assets and locales, and can't change anything. When you need more, switch to a profile made for that job, such as Entry Author for drafts or Launch Deploy Helper for deployments. The post on [picking the right Profile Hub profile](/blog/pick-the-right-profile-hub-profile-for-the-job) maps everyday jobs to profiles.

### Or put the profile on the URL

If you installed only the skills, or you want a second connection with a fixed profile, add the server yourself and name the profile on the URL. In Claude Code:

```bash
claude mcp add --transport http contentstack-explorer \
  "https://mcp-profile-hub.contentstack.com/api/mcp?profile_id=content_explorer&region=eu"
```

Keep the URL in quotes, or the shell reads ? and & as shell syntax. Add --scope user to make the server available in every project. Then run /mcp, pick the server and finish the browser sign-in.

In Cursor, add it to .cursor/mcp.json:

```json
{
  "mcpServers": {
    "contentstack-explorer": {
      "type": "http",
      "url": "https://mcp-profile-hub.contentstack.com/api/mcp?profile_id=content_explorer"
    }
  }
}
```

In Codex, add a block to ~/.codex/config.toml:

```toml
[mcp_servers.contentstack-explorer]
url = "https://mcp-profile-hub.contentstack.com/api/mcp?profile_id=content_explorer"
```

Other useful URL parameters are apikey (the stack), branch, environment and locale. They are configuration, not credentials. A stack API key on the URL grants nothing without your sign-in. region takes na, eu, au, azure-na, azure-eu, gcp-na or gcp-eu, and skips the region picker.

No API keys, management tokens or delivery tokens go into the client configuration. Sign-in is OAuth with PKCE, and the client refreshes its token on its own.

## Step 3: check that it works

Ask your agent two things.

> Which Contentstack skills do you have available?

It should list skills such as Delivery SDK, Entries and Data Modeling. A generic answer means the plugin isn't loaded or enabled.

> List the content types in my stack.

It should call a tool and return your content types, not examples. In Claude Code, /mcp should show the server as connected with its tools listed. In Cursor, check Cursor Settings → MCP.

## Three first tasks

These all work with skills plus Content Explorer, and none of them change your stack.

1. Explain your content model.

> Read my content types and explain how they reference each other. Point out any content type that nothing references.

The agent calls the content type tools, and the data modeling skill helps it say whether a reference, a global field or a modular block would fit better.

2. Write typed delivery code against your real schema.

> Read the blog_post content type and write a TypeScript function with @contentstack/delivery-sdk that fetches the 10 latest posts with their author reference. Use only fields that exist in the schema.

The dx-delivery-sdk skill knows the query chain order, and the tool gives it your actual field UIDs. That combination is what stops invented fields.

3. Diagnose something without touching the stack.

> My Live Preview iframe is blank on localhost. What should I check first?

This one is mostly skill. The Live Preview skill walks through the checks in order, the same ones as in our [Live Preview symptom index](/guides/live-preview-not-working-a-symptom-index).

## Safety rules that apply to every profile

- A profile narrows, it never widens. Every call runs with your own Contentstack account and roles. If your role can't publish, no profile lets the agent publish.


- Destructive tools ask first. Each tool tells your client whether it reads, changes or removes data. Clients such as Claude Code use that to ask before a tool deletes, updates, publishes or unpublishes something. Treat this as a prompt for you to read, not as a permission system. Your role is the real limit.


- Use one profile per job. A read-only profile for exploring, a separate one when you need to write. Don't connect the CMS profile because it's convenient.


- Skills are advisory by default. The CLI and Launch skills suggest commands and ask before anything that writes. Read the command before you approve it.


- Point write profiles at a branch or a dev stack first. Put branch= on the URL so drafts and experiments don't land in main.



If you install the MCP Profile Hub Marketplace app, its Executions view lists every tool call with its status, profile and error message. It's the first place to look when a call fails. For how the skills handle secrets and destructive actions, read the [Contentstack agent skills security policy](/blog/contentstack-agent-skills-security-policy).

## When it doesn't connect

Symptom

Fix

The server shows, but no tools

Sign-in wasn't finished. Run /mcp in Claude Code, or reconnect in your tool, and complete the browser flow

Sign-in fails for your account

You picked the wrong region. Reconnect, or add region=<id> to the URL

"Authorization session expired"

The connect screen was open longer than 15 minutes. Start again from your AI tool

"No stack selected"

Reconnect and choose a stack, or add apikey=<stack_api_key> to the URL

"Permission denied" on a tool

Your role can't do that. This is least privilege working

## Key takeaways

- Skills give the agent Contentstack knowledge, Profile Hub gives it tools on your stack. Install both.


- The plugin install for Claude Code, Cursor, Codex, Copilot and Gemini adds the skills and the contentstack MCP server in one step.


- Start with the Content Explorer profile, or put ?profile_id=content_explorer on the URL. Leave the CMS profile for when you really need full control.


- Verify with "Which Contentstack skills do you have available?" and "List the content types in my stack."


- Profiles never grant more than your role, and destructive tools ask before they run.



## Next steps

- Read [pick the right Profile Hub profile for the job](/blog/pick-the-right-profile-hub-profile-for-the-job) before you connect a profile that can write.


- Try a real workflow: [debug a failing Launch deploy with an agent](/guides/debug-a-failing-launch-deploy-with-an-agent).


- See how Profile Hub fills tool schemas with your stack's values in [how MCP Profile Hub enriches tools for your stack](/blog/how-mcp-profile-hub-enriches-tools-for-your-stack).


- Browse the full skill list on the [Contentstack agent skills](/contentstack-agent-skills) page.





---

## Do this with AI

Install the dx-mcp-server skill from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Content Explorer profile in MCP Profile Hub. Then ask your agent:

> List the Contentstack tools you can call, tell me which MCP Profile Hub profile they belong to and whether any of them can change content, then list the content types in my stack.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## Frequently asked questions

### Do I need an API key or management token to connect MCP Profile Hub?

No. You sign in with OAuth in the browser, and every tool call runs with your own Contentstack account and roles.

### Do I need both the skills and Profile Hub?

No, each works on its own. Skills give the agent Contentstack knowledge, Profile Hub gives it tools on your stack. Together the agent knows what to do and can check it against your real content.

### Which profile should I start with?

Content Explorer. It is read-only and covers content types, entries, assets and locales, so the agent can look around your stack without changing anything.

### Can a profile give the agent more access than I have?

No. A profile can only narrow what is available. If a tool call goes beyond your role, it fails.

### How do I switch to a different profile?

Remove the server from your AI tool and add it again to pick a new profile at sign-in, or add a separate server with profile_id set on the URL.


---

## Step 6: How to build your own MCP server with Contentstack's tools API

- **Source:** https://developers.contentstack.com/guides/how-to-build-your-own-mcp-server-with-contentstack-s-tools-api
- **Checkpoint:** You can build a custom MCP server when a Profile Hub profile isn't enough

- **Authors:** Tim Benniks
- **Published:** 2026-06-17T08:47:01.164Z
- **Updated:** 2026-11-16T13:32:21.066Z
- **Level:** Advanced
- **Intent:** Build
- **Tags:** mcp, api, ai, automation, security

---

> **Full guide available:** [View all 5 chapters in one document](https://developers.contentstack.com/guides/how-to-build-your-own-mcp-server-with-contentstack-s-tools-api/full.md)

Contentstack runs a hosted MCP server, [MCP Profile Hub](/contentstack-mcp). You add one URL to your AI client, sign in with OAuth and pick a profile that gives the agent only the tools a job needs. For most teams that's the fastest way to connect an agent to Contentstack.

However, there are situations where you may want to build your own MCP server instead.

You might want to:

- expose only a small set of Contentstack tools


- add custom approval flows before write operations


- connect Contentstack tools with your own internal APIs


- add logging, monitoring, or compliance checks


- manage authentication in your own infrastructure


- build a specialized MCP server for one stack, organization, or workflow



This guide shows you how to build a custom MCP server that uses Contentstack tool definitions.

The idea is simple:

- Fetch Contentstack tool definitions from public endpoints.


- Register those definitions as MCP tools.


- Let an MCP client call those tools.


- Convert each tool call into a Contentstack API request.


- Return the Contentstack API response to the MCP client.



The full flow looks like this:

```
MCP client
  -> calls a Contentstack tool
  -> your MCP server validates the tool arguments
  -> your MCP server reads the Contentstack tool mapper
  -> your MCP server builds a Contentstack REST or GraphQL request
  -> Contentstack returns a response
  -> your MCP server returns the result to the MCP client
```

By the end of this guide, you will have a working custom MCP server that can expose Contentstack tools to an AI client.

## Prerequisites

Before you start, make sure you have:

- Node.js 18 or later


- a Contentstack account


- access to a Contentstack stack


- a stack API key, if your tools need stack-level access


- a delivery token, if you want to use Content Delivery API tools


- a management token or OAuth access, if you want to use Content Management API tools


- an MCP-compatible client, such as Claude Desktop, Cursor, Claude Code, or another agent runtime



For OAuth-based workflows, you also need a Developer Hub app with OAuth configured.

Use OAuth when your MCP server should let users authorize access through Contentstack instead of relying on static tokens. You can create and configure the OAuth app in Developer Hub, where you define redirect URLs and the scopes your server needs.



---

## Frequently asked questions

### When should I build a custom MCP server instead of using MCP Profile Hub?

Use a custom server when you need your own hosting, custom approval flows, internal API integrations, added compliance controls or custom auth handling. If you only need a smaller set of tools, a Profile Hub profile already does that.

### How does the custom MCP server map MCP tool calls to Contentstack APIs?

It fetches Contentstack tool definitions, registers them as MCP tools, validates arguments, then builds and executes the corresponding Contentstack REST or GraphQL request.

### What do I need to run this guide’s MCP server implementation?

You need Node.js 18+, a Contentstack account with stack access, and an MCP-compatible client such as Claude Desktop, Cursor, or Claude Code.

### Which Contentstack credentials are required for different tool types?

Delivery API tools typically require a delivery token. Management API tools require a management token or OAuth access; some tools may also require a stack API key.

### When should I use OAuth instead of static tokens?

Use OAuth when users should authorize access through Contentstack rather than relying on shared static tokens; you’ll need a Developer Hub app with redirect URLs and scopes configured.


---

## Step 7: How MCP Profile Hub enriches tools for your stack

- **Source:** https://developers.contentstack.com/blog/how-mcp-profile-hub-enriches-tools-for-your-stack
- **Checkpoint:** You know how Profile Hub fills MCP tools with your stack context

- **Authors:** Tim Benniks
- **Published:** 2026-11-25T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:42.815Z
- **Level:** Advanced
- **Intent:** Learn
- **Tags:** mcp, ai, api

---

When you connect an AI agent to a profile in MCP Profile Hub, the tools it gets back from tools/list already know your stack. The content_type_uid argument lists your content types. The branch argument lists your real branches, and it only gets a default when the profile sets one. We built this into Profile Hub, and in this post I explain how it works, what can go wrong, and what it costs in tokens.

## The short version

- On tools/list, Profile Hub patches generic tool schemas with enums, descriptions and context from the account you connected. The API request behind each tool doesn't change.


- It enriches CMS, Launch, Brand Kit, Personalize and Developer Hub tools, per product, and only for the products the profile uses. A product that fails doesn't take the others down.


- It works inside an 8-second budget, caches for 5 minutes without tokens in the cache key, and falls back to the generic definitions if anything fails.


- In our evaluation it cut tool calls from 48 to 18 and latency from 159s to 105s, for about 3,700 extra tool-definition tokens per request.


- The public tool definitions carry optional x-enrich keys, so you can do the same thing in your own runtime, or ignore them.



## The problem with generic tools

Say you ask an agent to fetch the latest products. It calls a get-entries tool with content_type_uid: "product". Your stack doesn't have a product content type. It has guide, blogpost and page.

The call fails, so the agent lists the content types, picks one, and retries. That's three round trips for a request that needed one.

The model did what the schema told it to. The description said a content type UID looks like product, so it sent product. You see the same detour with environments, locales, branches, Personalize audiences and Brand Kit voice profiles. Any argument that takes an account-specific identifier makes the model guess.

## What changes in tools/list

When your MCP client sends tools/list, Profile Hub reads the relevant values from your connected account and patches the input schemas before it returns them. The stored definitions stay generic. Only the copy your client receives carries your account's values.

This is the content_type_uid and locale part of a get-entries tool before enrichment:

```json
{
  "content_type_uid": {
    "type": "string",
    "description": "A content type UID, for example product."
  },
  "locale": {
    "type": "string",
    "description": "The locale code of the entries to fetch."
  }
}
```

And this is the same part for a stack with three content types and two locales:

```json
{
  "content_type_uid": {
    "type": "string",
    "enum": ["guide", "blogpost", "page"],
    "description": "A content type UID. Stack content types: guide (Guide), blogpost (Blog Post), page (Page)."
  },
  "locale": {
    "type": "string",
    "enum": ["en-us", "fr-fr"],
    "description": "The locale code of the entries to fetch. Stack locales: en-us, fr-fr."
  }
}
```

The locales here are an example. Your stack's values are what you get.

With an enum, the model can only pick a value that exists. Tool descriptions get the same context, with one rule to keep the cost down: when the tool already has the matching parameter, the description gives the count and points at that parameter instead of repeating every value. Otherwise every tools/list response would carry each list twice.

Lists are also bounded. An enum holds at most 50 values. When a stack has more, the description says the list was truncated and tells the agent which list tool returns the complete set.

If the profile sets an environment, locale or branch, that value becomes the schema default. That is how a profile scoped to one stack and one locale stops the agent from asking which one you meant.

### Why defaults get removed

Enrichment also removes schema hints that are wrong for your account.

All 37 branch-aware tools used to declare main as their default branch. Some stacks don't have a main branch, or renamed it. A client that respects the schema sends branch=main to those stacks and gets a 422. In a trace that looks like a model error, but the model only followed the default it was given.

Profile Hub now removes that inherited default unless the profile sets a branch on purpose. The branch argument still gets an enum of the stack's real branches, just no default. What I took from this bug is that models treat the schema as the interface. Defaults, examples, enums and descriptions all change what the model sends, so each of them has to be correct for the account the agent is working in.

## What gets enriched per product

A profile can mix tools from several Contentstack products. Profile Hub enriches each product separately:

Product

Enriched values

CMS (Delivery and Management)

Content types, environments, locales, branches

Launch

Projects and environments

Brand Kit

Voice profiles and Knowledge Vault content

Personalize

Attributes, audiences, experiences, events

Developer Hub

Marketplace apps and organization

## Safeguards in production

Enrichment runs inside tools/list, so every client connection waits for it. If it were slow or fragile, every profile would feel slow or fragile. These are the safeguards that keep that from happening:

- Time budget. Full enrichment gets 8 seconds. A slow product can't block tools/list past that.


- Short cache. Results are cached for 5 minutes, and access tokens are not part of the cache key.


- Request coalescing. Concurrent identical requests share one lookup instead of calling the same APIs in parallel.


- Per-product failure isolation. If the Personalize lookup fails, your CMS and Launch tools are still enriched.


- Fallback. If enrichment fails completely, you get the generic definitions. Every tool still works, with less context.


- Clean output. The x-enrich keys that drive enrichment are stripped before the definitions reach your client, so the model never sees them.



flowchart LR  A[Client sends tools/list] --> B{Cached for this account?}  B -- yes --> F[Return enriched tools]  B -- no --> C[Fetch context per product in parallel]  C --> D{Product answered within budget?}  D -- yes --> E[Patch that product's schemas]  D -- no --> G[Keep that product's generic schemas]  E --> H[Strip x-enrich keys]  G --> H  H --> F## What it costs in tokens

Bigger enums and longer descriptions make tool definitions bigger, so we measured whether that pays off. We ran 18 CMS tasks three times each against 77 Content Management API tools, once with enrichment and once without. These are the low reasoning effort results:

Metric

Generic

Enriched

Change

Tool calls

48

18

62% fewer

Latency

159s

105s

34% lower

Reasoning tokens

871

168

81% fewer

Tool-error runs

6

3

50% fewer

Tool-definition tokens per request

10.0k

13.6k

37% more

The last row is the cost: about 3,700 extra tokens per request. Across the run, the agent made 30 fewer tool calls and finished 54 seconds sooner. A prompt like "entries from the content type that stores blog posts" went from nine calls to one, and counting entries went from sixteen calls to one.

We also included control prompts for areas enrichment doesn't touch, such as assets, taxonomies and releases. Those showed no difference, which tells us the gains come from the added context and not from run-to-run noise.

> Caveat: About 93% of prompt tokens were cache hits, so the raw prompt-token totals say little about real cost. Watch tool calls and latency instead, because a cache hit doesn't save you a round trip.

For how we test agent behavior on profiles in general, read [we don't test our MCP profiles, we test the agent](/blog/we-don-t-test-our-mcp-profiles-we-test-the-agent).

## Reasoning effort made it slower

We ran the same tasks at high reasoning effort. Enrichment still helped (tool calls went from 66 to 43, latency from 258s to 194s), but high effort was slower than low effort in both variants. It was also the only setting that failed a task: it distrusted a correct result and checked content types one at a time until it hit the turn limit.

For bounded CMS work with enriched tools, low effort did better. The full numbers are in [part 3 of my Profile Hub series](https://timbenniks.dev/writing/building-mcp-profile-hub-part-3-when-more-reasoning-makes-the-agent-worse).

## Profiles narrow the catalog, enrichment adds context

A profile decides which tools the model sees. A content editor's profile might have entry search, content model inspection and a few safe updates, while a release manager's profile has environments, releases, branches and deployments. With fewer tools to choose from, the model picks the wrong one less often. I explain why the profile is the right unit of configuration in [part 2 of the series](https://timbenniks.dev/writing/building-mcp-profile-hub-part-2-one-mcp-server-is-the-wrong-abstraction).

Enrichment then gives each of those tools your account's real values. A small profile with generic tools still sends the agent off to look up identifiers, and a large catalog with enriched tools still leaves it searching for the right tool. You need both to get short, correct traces. That's the same argument I made in [build context-aware MCPs, not API wrappers](/blog/build-context-aware-mcps-not-api-wrappers).

## Doing this in your own runtime

Contentstack publishes the tool definitions behind Profile Hub at public, unauthenticated endpoints, one per catalog, at https://mcp.contentstack.com/<catalog>/tools. They contain metadata only: names, descriptions, input schemas and request mappings. You bring your own tokens.

```bash
curl -s https://mcp.contentstack.com/cda/tools | jq 'keys'
```

The definitions can carry three optional extension keys:

Key

Where it lives

What it tells your runtime

x-enrich

On a property in inputSchema.properties

Patch this argument's enum, description or default

x-enrich-description

On the tool

Append account context to the tool description

x-enrich-group

On the tool

Apply a named set of property rules instead of repeating them per field

None of these keys change how a tool call maps to an API request.

If you don't want enrichment, strip every key that starts with x-enrich before you pass the tools to your model. Every tool works with standard JSON Schema. If you do want it, fetch the values from the account, patch the marked properties, and then strip the keys. Copy the safeguards as well: a time budget, a short cache without tokens in the key, per-product isolation and a fallback to the generic schema.

The guide on [building your own MCP server with Contentstack's tools API](/guides/how-to-build-your-own-mcp-server-with-contentstack-s-tools-api) shows how to fetch and execute these definitions. Enrichment is one extra step in your tools/list handler on top of that.

## Concluding

Profile Hub does the account lookups once, when the client asks for tools, instead of letting the agent repeat them in every conversation. It also removes defaults that would send the agent to a branch that doesn't exist. In our runs that cost about 3,700 tokens per request and saved 30 tool calls and 54 seconds, and I'd take that trade for any CMS profile.

The background, the profile model and the reasoning-effort results are in my three-part series: [stop making the agent ask](https://timbenniks.dev/writing/building-mcp-profile-hub-part-1-stop-making-the-agent-ask), [one MCP server is the wrong abstraction](https://timbenniks.dev/writing/building-mcp-profile-hub-part-2-one-mcp-server-is-the-wrong-abstraction), and [when more reasoning makes the agent worse](https://timbenniks.dev/writing/building-mcp-profile-hub-part-3-when-more-reasoning-makes-the-agent-worse).



---

## Do this with AI

Install the dx-mcp-server skill from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills) and connect the Content Explorer profile in MCP Profile Hub. Then ask your agent:

> List the content types, locales and branches your tools know about for my stack, then show me the fields you would expect when reading a blog_post entry.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## Frequently asked questions

### What does enrichment change in an MCP tool?

Only the schema the model reads. Profile Hub adds enums, descriptions and context from your connected account to tool arguments on tools/list, while the underlying API request stays exactly the same.

### What happens if enrichment fails or is slow?

Profile Hub isolates failures per product and works within a time budget. If enrichment fails entirely, you get the generic tool definitions and every tool still works.

### Does enrichment make prompts more expensive?

Tool definitions grew by about 37 percent, roughly 3,700 tokens per request, in our evaluation. That cost was repaid by 62 percent fewer tool calls and 34 percent lower latency at low reasoning effort.

### Can I use enrichment if I build my own MCP server?

Yes. The public tool definitions can carry optional x-enrich extension keys that describe which arguments to fill. A runtime that ignores them still works with the standard schemas.


---

## Step 8: Understanding how Contentstack CMS, Personalize, and Lytics work together

- **Source:** https://developers.contentstack.com/blog/understanding-how-contentstack-cms-personalize-and-lytics-work-together
- **Checkpoint:** You understand how CMS, Personalize and Lytics fit together

- **Authors:** Tim Benniks
- **Published:** 2026-04-14
- **Updated:** 2026-11-10T16:27:34.825Z
- **Level:** Intermediate
- **Intent:** Learn
- **Tags:** headless, personalization

---

Digital experiences are no longer just about publishing content. They are about delivering the right content to the right user at the right moment. Contentstack approaches this by combining three distinct but tightly connected capabilities:

- Content management


- Customer data and insights


- Real-time personalization



To understand how these fit together, it helps to think in terms of three layers:

- Content: what you can show


- Data: who the user is


- Decisioning: what should be shown right now



## A simple mental model

At a high level, the system looks like this:

flowchart LR

    User -->|Behavior, clicks, context| Lytics

    Lytics -->|Audience segments, profiles| Personalize

    CMS -->|Content, entries, variants| Personalize

    Personalize -->|Which variant?| Edge

    Edge -->|Fetch content| CMS

    CMS -->|Rendered content| User

This diagram captures the core idea: content, data, and decisioning are separate concerns that come together at runtime.

## The role of each product

### Contentstack CMS: the content system of record

Contentstack CMS is responsible for managing structured content. It stores entries, assets, and content models, and delivers them via APIs to any channel.

Its responsibility is straightforward: define and deliver what content exists.

What it does well:

- Structured content modeling


- Omnichannel delivery via APIs


- Versioning and governance



What it does not do:

- It does not track user behavior


- It does not decide which content variant to show



The CMS is intentionally user-agnostic. It provides content, not context.

### Lytics: the customer data platform

Lytics serves as the data and insights layer. It collects behavioral data from users and builds unified customer profiles in real time.

Its responsibility is to answer the question: who is this user?

What it does:

- Tracks events such as page views, clicks, and interactions


- Builds persistent user profiles


- Creates audience segments based on behavior and attributes



Examples of segments:

- Returning visitors


- High-intent users


- Users interested in a specific category



What it does not do:

- It does not render content


- It does not control presentation



Lytics transforms raw behavioral data into actionable audience intelligence.

### Contentstack Personalize: the decision engine

Contentstack Personalize sits between content and data. It is responsible for making real-time decisions about which content variant should be delivered to a user.

Its responsibility is to answer: what should this user see right now?

What it does:

- Evaluates audience membership (from Lytics)


- Matches users to experiences or variants


- Executes decisions at the edge for low latency



What it does not do:

- It does not store content


- It does not build user profiles



Personalize is the orchestration layer that connects content with context.

## How the pieces connect

The integration between these systems is often referred to as a data activation layer. This is not a single product, but rather the flow that connects:

- Content from the CMS


- User data from Lytics


- Decisions from Personalize



The result is a runtime system where each request can be tailored dynamically.

## End-to-end request flow

To make this concrete, consider what happens when a user visits a site:

sequenceDiagram

    participant User

    participant Site

    participant Lytics

    participant Personalize

    participant CMS


    User->>Site: Visits page

    Site->>Lytics: Send behavior (tracking)

    Lytics->>Lytics: Update profile and audiences


    Site->>Personalize: Request personalization decision

    Personalize->>Lytics: Retrieve audience membership

    Personalize->>Personalize: Select variant


    Site->>CMS: Fetch content

    CMS->>Site: Return content

    Site->>User: Render personalized experience

This flow highlights an important point: personalization decisions are made at request time, using both stored content and real-time user context.

## The feedback loop

One of the most important aspects of this architecture is that it forms a continuous feedback loop:

- Content is delivered to the user


- The user interacts with that content


- Lytics captures and processes the behavior


- Audience membership evolves


- Personalize adjusts future decisions



Over time, the system becomes more accurate and more relevant without requiring manual intervention for every change.

## Clear differentiation between the three

A useful way to explain the system is to map each product to a specific responsibility:

Layer

Product

Responsibility

Question it answers

Content

CMS

Store and deliver content

What content do we have?

Data

Lytics

Build user profiles and segments

Who is this user?

Decisioning

Personalize

Select the right variant

What should they see right now?

Keeping these responsibilities separate is what enables flexibility and composability.

## Why all three are necessary

Each component plays a distinct role, and removing one creates a gap:

- Without the CMS, there is no structured content to deliver


- Without Lytics, there is no understanding of the user


- Without Personalize, there is no real-time decision-making



Together, they form a complete system for delivering adaptive digital experiences.

## A simple analogy

For a non-technical audience, the system can be compared to a streaming platform:

- The CMS is the content library


- Lytics is the viewer profile and history


- Personalize is the recommendation engine



Each part is essential, and the experience depends on all three working together.

## Summary

Contentstack CMS, Lytics, and Personalize are designed as separate but complementary systems:

- The CMS manages content


- Lytics understands users


- Personalize makes real-time decisions



Combined, they enable a composable architecture where content delivery is no longer static, but continuously adapted based on user behavior and context.



---

## Frequently asked questions

### What does Contentstack CMS do in this architecture?

Contentstack CMS is the content system of record. It stores structured entries and assets and delivers them via APIs, but it does not track users or choose variants.

### What role does Lytics play with Contentstack Personalize?

Lytics collects behavioral events and builds unified user profiles and audience segments. Personalize uses that audience membership as input for runtime decisions.

### How does Contentstack Personalize decide which content variant to show?

Personalize evaluates audience membership (from Lytics) and matches the user to an experience or variant. Decisions are executed at the edge to reduce latency.

### What happens during an end-to-end personalized page request?

The site sends tracking data to Lytics, requests a decision from Personalize, and then fetches the needed content from the CMS. The site renders the selected variant for the user.

### Why keep content, data, and decisioning as separate layers?

Separating responsibilities improves composability and flexibility. You can evolve content models, audience logic, and decision rules independently while still combining them at runtime.



---

## Next step




- [Middleware Magic: Personalize and Visual builder in a complex setup](/livestreams/middleware-magic-personalize-and-visual-builder-in-a-complex-setup)


---

## Step 9: Lytics use cases and technical implementation guide

- **Source:** https://developers.contentstack.com/guides/lytics-use-cases-and-technical-implementation-guide
- **Checkpoint:** You can implement the main Lytics use cases

- **Authors:** Andrew Seatter, Eric Huiza, Lo Etheridge
- **Published:** 2026-06-17T13:30:10.000Z
- **Updated:** 2026-11-10T16:27:16.936Z
- **Level:** Advanced
- **Intent:** Learn
- **Tags:** personalization, taxonomy

---

> **Full guide available:** [View all 5 chapters in one document](https://developers.contentstack.com/guides/lytics-use-cases-and-technical-implementation-guide/full.md)


> What you'll build (time-to-value): A working personalization pipeline where Lytics audiences and attributes activate Contentstack Personalize experiences (A/B tests, segmented experiences, and identity-based personalization) using data captured from your site and/or first-party sources.

## This Guide is for

- Customer developers implementing Contentstack + Contentstack Personalize + Lytics (Data & Insights).
- Solution engineers / technical teams supporting implementation.

## Learning Outcomes (What You'll Be Able to Do)

By the end of this guide, you can:

- Explain when to use each of the four Lytics-powered use cases and their respective value.
- Configure prerequisites (Stack, Personalize, Lytics account, Data Activation Layer, JSTag/SDK).
- Implement and validate:
- A/B Testing (and Multi-Armed Bandit)
- Anonymous Behavior-based Segmentation
- Identity Resolution
- First-Party Data Activation

- Verify that data is flowing and experiences are activated, using clear checkpoints.

## How to Use This Guide

Pick one of these paths:

- Path A (End-to-end): Complete prerequisites, then do Use Cases 1–4 in order.
- Path B (Jump-in): If prerequisites are already complete, jump directly to a use case and follow the "Validate" steps to confirm your environment is ready.

## Architecture Overview (Conceptual)

- Your website/app sends behavioral and identifier signals via Lytics JSTag/SDK. 
- Lytics uses those signals (plus optional first-party data sources) to build profiles and audiences/segments. 
- Data Activation Layer (DAL) connects your Contentstack Stack, Contentstack Personalize project, and Lytics account to sync audiences and live attributes. 
- Contentstack Personalize then uses the synced audiences and attributes to deliver experiences and distribute variants (A/B, MAB, segmented experiences).

> Validation checkpoint: Before building experiences, confirm you can: (1) see signals arriving in Lytics and (2) target a Lytics segment inside Contentstack Personalize.

## Setting Up for Success (Prerequisites)

Ensure the following are set up before you begin:

- Contentstack Stack: Your content container with taxonomies created and linked to content types.
- Contentstack Personalize: Prepared to handle variant distribution.
- Lytics Account: Ready to provide near real-time user data.
- Data Activation Layer: Connects your Stack, Personalize project, and Lytics account for audience syncing.
- Lytics JSTag/SDK: Installed on the front-end to capture user behavior.

## A Closer Look at the Required Components

Component

Requirement

Stack

Container for all your content and configuration inside Contentstack with taxonomies created and added to a certain content type. Refer to this documentation on creating taxonomies and linking them to a content type.

• [Create a taxonomy](https://www.contentstack.com/docs/developers/taxonomy/create-a-taxonomy)

• [Add a taxonomy to a content type](https://www.contentstack.com/docs/developers/taxonomy/add-taxonomy-to-a-content-type)

Contentstack Personalize

Handles Variant distribution tied to segments from data and insights

Lytics account

Provides Near Real-Time Data on users that is synced to Contentstack Personalize, handling variant distribution

Data Activation Layer (DAL)

Prerequisites: Stack, Personalize Project and tied to your Lytics account. This will sync audiences to your Personalize project. Refer to this documentation for setup: [Data Activation Layer Creation](https://www.contentstack.com/docs/data-and-insights/create-data-and-insights-lytics-integration).

You will need a Stack, a Personalize Project and a website hosted and accessible.

The Data Activation Layer is necessary for ensuring segments built in Lytics are synced to your Personalize project, along with live user attributes being synced to your Personalize project when a user is browsing.

Lytics jstag/SDK

Installed on the front end of your site. [Lytics JavaScript Tag](https://docs.lytics.com/docs/lytics-javascript-tag). 

(If using the Event Tracking feature in your launch project refer to this documentation to automatically add the tag to your deployed site: [Event Tracking in Launch](https://www.contentstack.com/docs/launch/event-tracking-in-contentstack-launch). You will need to have a consent handler in place to enable user tracking when using this feature.)

Learn how to create a Data Activation Layer in Contentstack: [Data Activation Layer Creation](https://www.contentstack.com/docs/data-and-insights/create-data-and-insights-lytics-integration)

