---
title: "Build with AI agents"
url: "https://developers.contentstack.com/paths/build-with-ai-agents"
type: "path_full"
level: "intermediate"
outcome: "An AI coding agent that knows Contentstack, connected through a narrow Profile Hub profile."
steps:
  - "https://developers.contentstack.com/guides/set-up-your-ai-workbench-for-contentstack"
  - "https://developers.contentstack.com/blog/pick-the-right-profile-hub-profile-for-the-job"
  - "https://developers.contentstack.com/blog/how-mcp-profile-hub-enriches-tools-for-your-stack"
  - "https://developers.contentstack.com/blog/responsibilities-of-skills-mcp-clis-and-apis"
  - "https://developers.contentstack.com/blog/contentstack-agent-skills-security-policy"
updated: "2026-11-15T11:47:30.125Z"
---

# Build with AI agents

- **Level:** Intermediate
- **Steps:** 5
- **Overview:** https://developers.contentstack.com/paths/build-with-ai-agents.md

---

Set up agent skills and MCP Profile Hub, pick the right profile for each job, and understand how the tools your agent uses are built.

**You'll end up with:** An AI coding agent that knows Contentstack, connected through a narrow Profile Hub profile.

## Table of Contents

1. Set up your AI workbench for Contentstack
2. Pick the right Profile Hub profile for the job
3. How MCP Profile Hub enriches tools for your stack
4. Responsibilities of Skills, MCP, CLIs, and APIs
5. Contentstack agent skills security policy


---

## Step 1: 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 2: Pick the right Profile Hub profile for the job

- **Source:** https://developers.contentstack.com/blog/pick-the-right-profile-hub-profile-for-the-job
- **Checkpoint:** You know which profile fits which job.

- **Authors:** Tim Benniks
- **Published:** 2026-12-08T09:00:00.000Z
- **Updated:** 2026-11-15T10:56:44.492Z
- **Level:** Intermediate
- **Intent:** Learn
- **Tags:** ai, mcp

---

The profile you connect decides what your agent can do on your stack, so it deserves more thought than the first item in the list. My rule is simple: pick the narrowest profile that can finish the job, and switch profiles when the job changes. This post maps everyday developer and content jobs to the MCP Profile Hub system profiles, explains why the narrow ones work better, and covers when to build your own.

If you haven't connected anything yet, start with [set up your AI workbench for Contentstack](/guides/set-up-your-ai-workbench-for-contentstack).

## The short version

- Start with Content Explorer. It is read-only, and it answers most "what's in this stack" questions.


- Use a job profile, such as Entry Author, Publishing Helper or Launch Deploy Helper, when you need to change something.


- Keep the product profiles (CMS, Launch, Personalize and the others) for people who really need full control of that product. They include destructive tools.


- Build a custom profile when a job needs one tool a system profile leaves out.


- A profile never grants more than your role. Destructive tools are marked, and clients ask before running them.



## Job to profile

These are the system profiles I reach for, with the profile_id you can put on the connector URL.

The job

Profile

profile_id

Can it change anything?

Find out what content types, entries and assets exist

Content Explorer

content_explorer

No

Read the content model to write code or docs

Content Modeler

content_modeler

No

Check what visitors actually get from the Delivery API

Published Content QA

published_content_qa

No

Find broken or orphaned references before a release

Broken Reference Checker

broken_reference_checker

No

Find entries missing a translation

Localization Gap Finder

localization_gap_finder

No

See who changed what and when

Governance Inspector

governance_inspector

No

Draft or edit entries

Entry Author

entry_author

Creates and updates drafts, never publishes

Publish or unpublish prepared content

Publishing Helper

publishing_helper

Publishes, doesn't edit

Ship a set of changes together

Release Manager

release_manager

Creates and deploys releases

Clean up taxonomies and terms

Taxonomy Librarian

taxonomy_librarian

Creates, moves and deletes terms

Tidy asset titles, tags and folders

Asset Librarian

asset_librarian

Updates metadata, can't delete or publish

List deployments, read build logs, redeploy

Launch Deploy Helper

launch_deploy_helper

Triggers deployments and cache revalidation

Watch API and CDN traffic, status codes and cache hits

Delivery Analytics

delivery_analytics

No

A few of these pair up well. Entry Author writes drafts and Publishing Helper takes them live, so the agent that drafts can't also publish. Content Modeler compares content types and global fields between branches, which is what I want open next to [a branch-based model change](/guides/safe-content-model-changes-with-branches-and-aliases).

## Why narrow beats broad

The CMS profile has over a hundred tools. Content Explorer has eight. For a question like "which content types reference the author type", both get you there, but they don't get you there the same way.

The agent picks the wrong tool less often. With eight tools there is little to confuse. With a hundred, many tools sound alike: list entries, get one entry, get its references, get its versions, get its variants. The Profile Hub docs say it plainly: smaller and older models misread tool descriptions more often.

Every request carries less. Tool definitions go into the context on every turn. In the evaluation behind [how MCP Profile Hub enriches tools for your stack](/blog/how-mcp-profile-hub-enriches-tools-for-your-stack), 77 CMA tools took about 10,000 tokens of tool definitions per request before enrichment. Eight tools take a fraction of that, which leaves room for your actual content.

Mistakes stay small. A read-only profile can't delete an entry because the tool isn't there. That's a stronger guarantee than hoping the model reads the confirmation prompt the way you meant it.

Enrichment stays focused. Profile Hub fills each tool with your stack's content types, locales and branches, but only for the products the profile uses. A narrow profile gets short, exact enums instead of every value from every product.

None of this makes the product profiles bad. If you are the platform admin and you need to restructure a stack, the CMS profile is the right tool. It's the wrong default.

## When to build your own

Build a custom profile in the MCP Profile Hub app when a system profile is almost right but misses one piece. Two examples I run into:

- Runtime logs for a Launch deployment. Launch Deploy Helper reads build logs, but not server logs. The full Launch profile has server logs, but also deletes projects and environments. A custom profile with Deploy Helper's tools plus the server log tool is the narrow version of what I want. I use exactly that setup in [debug a failing Launch deploy with an agent](/guides/debug-a-failing-launch-deploy-with-an-agent).


- A workflow across two products. Campaign Go-Live already combines publishing an entry with revalidating the Launch cache. If your flow is different, for example publishing a release and then revalidating, build a profile for that flow rather than connecting two product profiles.



Some rules I follow when I build one:

- One profile per job. A second focused profile is better than one profile that does two jobs.


- Pick tools by operation. The catalog tags every tool as Read, Create, Update, Delete, Action or Publishing, so you can see at a glance what you're adding.


- Fewer tools mean fewer OAuth scopes. Profile Hub derives the scopes from the tools you pick, so a read-only profile only asks for read scopes.


- Set the stack, and for write profiles a branch, in the profile's configuration. Then the agent doesn't have to ask, and it can't guess wrong.



## The destructive-tools rule

Every tool tells your client whether it only reads, changes something, or removes something. A tool counts as destructive when it deletes data, replaces it, or changes something live: publishing, a Launch deployment, a cache purge. Clients such as Claude Code use that mark to ask you before running the tool, and run read-only tools without asking.

That prompt is a hint for your client, not a permission system. Two things actually limit what happens:

- The profile. If the tool isn't in the profile, the agent can't call it.


- Your role. Every call runs with your own Contentstack account. If your role can't publish to production, the call fails, whatever profile you use.



So my rule is: if a job doesn't need a destructive tool, connect a profile that doesn't have one. If it does, read the confirmation before you approve it, and check which stack, branch and environment it names.

## Concluding

Pick the profile for the job you're doing right now, not for every job you might do later. Content Explorer for looking around, a job profile for changing something, a product profile only when you need the whole product. If the agent needs one tool more, build a custom profile with that tool added instead of jumping to the broad one.



---

## Do this with AI

Install the dx-mcp-server skill from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills). Then ask your agent:

> I want an agent to find blog posts that aren't translated into German yet and then draft the missing translations. Which MCP Profile Hub system profiles should I connect for each step, and which tools in them can change content?

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




---

## Frequently asked questions

### Which Profile Hub profile should I start with?

Content Explorer. It is read-only and covers content types, entries, assets and locales, which is enough for most questions about a stack.

### Why not just use the CMS profile for everything?

It exposes the full CMS toolset, over a hundred tools including delete and publish. The agent picks the wrong tool more often, every request carries more tool definitions, and a mistake can change live content.

### When should I build a custom profile?

When no system profile matches the job, for example when a job needs one tool a system profile leaves out, or spans two products in a way no system profile does.

### Can a profile let the agent do more than my role allows?

No. Every call runs with your own Contentstack roles. A profile can only narrow what the agent can do.


---

## Step 3: 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 understand why enriched tools make agents faster and more accurate.

- **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 4: Responsibilities of Skills, MCP, CLIs, and APIs

- **Source:** https://developers.contentstack.com/blog/responsibilities-of-skills-mcp-clis-and-apis
- **Checkpoint:** You know when to use a skill, MCP, the CLI or the API.

- **Authors:** Tim Benniks
- **Published:** 2026-07-03T12:16:16.882Z
- **Updated:** 2026-11-10T16:27:31.393Z
- **Level:** Advanced
- **Intent:** Learn
- **Tags:** agent_skills, mcp, cli, api, security, ai

---

When we build AI-enabled developer experiences, it is important to be clear about which layer is responsible for what. Skills, MCP servers, CLIs, and APIs can work together, but they should not all do the same job. Each layer has a different responsibility, especially when authentication and user permissions are involved.

The simplest way to think about it is this: 

> Skills describe how work should be done. 
> 
> MCP servers perform authenticated actions. 
> 
> CLIs support developer-controlled local workflows. 
> 
> APIs expose product capabilities with proper authorization.
> 
> 

## Skills: the workflow and instruction layer

Skills are best used to teach an AI system how to work in a specific domain.

A Skill can contain:

- product knowledge


- workflow instructions


- best practices


- validation rules


- examples


- templates


- decision trees


- conventions for how work should be done



A Skill should help the model understand the task and guide the user or system toward the correct outcome.

For example, a Contentstack Skill might explain how to plan a Studio project, what files should be generated, how to structure content models, or what checks should happen before publishing.

A Skill should not be responsible for holding access tokens, storing credentials, or directly calling authenticated APIs as the user.

If a Skill receives an access token, it effectively becomes an authenticated integration layer. That creates security, governance, auditability, and ownership problems.

A good rule of thumb: A Skill can request authenticated work, but it should not become the authenticated actor.

## MCP: the authenticated tool execution layer

MCP is the right place for AI-accessible tools that perform real actions.

An MCP server can expose a focused set of tools to an AI system, such as:

- list stacks


- create a Studio project


- fetch content types


- create branches


- install apps


- validate project setup


- generate environment configuration



The MCP server owns the execution boundary. It can handle authentication, scopes, authorization, token storage, rate limits, logging, and auditing.

This is especially important because AI systems should not need broad raw API access. They should get specific, well-named tools that perform intentional actions.

Instead of giving the model a generic token and saying “call whatever APIs you need,” we expose a tool like:

create_studio_project

That tool can validate inputs, call the right APIs, enforce permissions, and return a safe result.

A good rule of thumb:

MCP turns user intent into controlled, authenticated actions.

## CLI: the developer-controlled local workflow layer

A CLI is a developer-facing tool. It is useful when the user is intentionally working in their local environment or terminal.

A CLI can:

- log a user in


- store local auth state securely


- scaffold files


- run setup commands


- create projects


- validate local configuration


- call APIs on behalf of the user


- connect local development workflows to Contentstack



The CLI is a good place for workflows where the developer is actively in control.

For example:

```html
contentstack login
contentstack studio create-project
contentstack app scaffold
contentstack mcp --auth
```

However, CLI authentication should stay inside the CLI or the runtime it is explicitly authenticating. A CLI should not expose reusable session tokens to Skills or other layers just because they want to perform authenticated work.

A good rule of thumb:

The CLI may authenticate the developer, but it should not leak reusable credentials into instruction layers.

## APIs: the product capability layer

APIs expose the actual product capabilities. They are the system of record for what can be done.

APIs should provide:

- clear permissions


- OAuth support where needed


- scoped access


- stable contracts


- validation


- auditability


- predictable error handling


- product-level authorization



If an AI workflow needs to create a Studio project, install an app, or modify resources, the APIs need to support that flow with the correct auth model.

If the required APIs do not yet support the right OAuth or authorization pattern, the solution should be to improve the API/auth model or expose the right capability through MCP or CLI. The solution should not be to pass around a session token from another layer.

A good rule of thumb:

APIs define what is possible and enforce who is allowed to do it.

## How these layers should work together

A healthy flow looks like this:

- The Skill explains the workflow.


- The user asks the AI system to perform a task.


- The AI system calls a focused MCP tool.


- The MCP server handles auth and calls the required APIs.


- The APIs enforce permissions and perform the action.


- The result is returned to the user.



For local developer workflows, the flow may look like this:

- The user runs a CLI command.


- The CLI uses its own authenticated context.


- The CLI calls the required APIs.


- The CLI writes files, creates projects, or validates setup locally.



Both patterns are valid. What we should avoid is mixing responsibilities in a way that weakens the security model.

## What we should avoid

We should avoid patterns like:

- exposing MCP session tokens to Skills


- letting Skills store or reuse access tokens


- giving AI systems raw bearer tokens


- bypassing OAuth because another layer already has a session


- using Skills as hidden API clients


- treating CLI auth as a general-purpose token vending mechanism


- creating one-off shortcuts that are hard to govern later



These patterns may solve a short-term integration problem, but they create long-term risk.

They make it harder to answer basic questions like:

- Who is the authenticated actor?


- Which scopes were granted?


- Where is the token stored?


- Can the token be revoked?


- What actions can this layer perform?


- Can we audit what happened?


- Can we safely expose this to customers or partners?



If those questions are hard to answer, the boundary is probably wrong.

## Recommended ownership model

For Contentstack developer and AI surfaces, the responsibility split should be:

Layer

Primary responsibility

Should it hold reusable user auth tokens?

Skills

Instructions, workflows, examples, validation guidance

No

MCP

Controlled AI tool execution with auth

Yes, inside the MCP boundary

CLI

Developer-controlled local workflows

Yes, inside the CLI/local boundary

APIs

Product capabilities, permissions, authorization

Yes, as part of the product auth model

## Practical principle

When designing a new feature or integration, ask:

Is this layer describing the work, executing the work, or authorizing the work?

- If it is describing the work, it belongs in a Skill.


- If it is executing authenticated work on behalf of an AI system, it belongs in MCP.


- If it is executing developer-controlled local work, it belongs in the CLI.


- If it is defining product capability and permissions, it belongs in the API.



Keeping these boundaries clear helps us build AI experiences that are powerful, secure, supportable, and easier to explain.



---

## Frequently asked questions

### What is the primary responsibility of a Skill in an AI-enabled developer experience?

A Skill describes how work should be done using domain knowledge, workflow instructions, examples, and validation guidance. It should not execute authenticated actions or hold reusable credentials.

### Why should Skills not store or reuse access tokens?

If a Skill holds tokens, it becomes an authenticated integration layer, creating security, governance, auditability, and ownership issues. Skills can request authenticated work, but should not be the authenticated actor.

### What should an MCP server handle in this architecture?

An MCP server should expose focused, well-named tools that perform controlled actions. It owns the execution boundary, including authentication, authorization, token storage, rate limits, logging, and auditing.

### When is a CLI the right layer to use?

Use a CLI for developer-controlled local workflows such as logging in, scaffolding files, running setup, and validating local configuration. CLI auth should remain within the CLI/local runtime and not be leaked to instruction layers.

### What role do product APIs play compared to MCP and CLI?

APIs define product capabilities and enforce permissions and authorization with stable contracts and predictable errors. If an AI workflow needs a capability, improve the API/auth model or expose it via MCP/CLI rather than passing session tokens between layers.


---

## Step 5: Contentstack agent skills security policy

- **Source:** https://developers.contentstack.com/blog/contentstack-agent-skills-security-policy
- **Checkpoint:** You know how agent skills are kept safe.

- **Authors:** Tim Benniks
- **Published:** 2026-02-25
- **Updated:** 2026-11-10T16:27:31.022Z
- **Level:** Advanced
- **Intent:** Ship
- **Tags:** ai, security

---

At Contentstack we value security and transparency. This is our agent skills security policy.

## Purpose

This policy defines the minimum security requirements for building, publishing, and maintaining Agent Skills within the Contentstack ecosystem. It protects users, content, and systems from prompt injection, unsafe markdown rendering, and model hallucinations.

This policy applies to:

- First party skills


- Partner integrations


- Community contributed skills


- Skills that access Contentstack APIs, content, or external systems



## Security principles

All skills must follow these core principles:

- Least privilege Request only the permissions and scopes strictly required.


- Explicit trust boundaries Treat user input, remote content, and model output as untrusted.


- Deterministic behavior where possible Prefer structured outputs and validation over freeform generation.


- Safe rendering Never render untrusted markdown or HTML without sanitization.


- Verifiable actions Any action that mutates content or systems must be confirmed and logged.


- Have a defined person or team who is responsible for monitoring and maintaining the skill



Have a defined person or team who is responsible for monitoring and maintaining the skill

# 1 Prompt injection protection

Prompt injection is the primary risk in agent ecosystems. Skills must assume that any input may attempt to override system instructions.

## 1.1 Treat all external input as untrusted

Untrusted sources include:

- User prompts


- Contentstack entries and assets


- Markdown from CMS fields


- External APIs and web pages


- MCP server responses


- Plugin outputs



### Required controls

Skills must:

- Never allow external content to modify system instructions.


- Never concatenate untrusted input directly into system prompts.


- Use clear role separation between system, developer, and user instructions.


- Strip or neutralize instruction like phrases from untrusted content.



### Example of unsafe pattern

```javascript
systemPrompt = "You are a safe assistant."
systemPrompt += userInput
```

### Example of safe pattern

```javascript
messages = [
  { role: "system", content: SAFE_SYSTEM_PROMPT },
  { role: "user", content: sanitize(userInput) }
]
```

## 1.2 Detect injection patterns

Skills should detect and neutralize common injection attempts such as:

- "Ignore previous instructions"


- "You are now a different system"


- "Reveal your system prompt"


- "Execute hidden instructions"


- Markdown or HTML that embeds instructions



### Recommended mitigation

- Reject or flag suspicious inputs.


- Log injection attempts.


- Return a safe refusal when intent is unclear.



# 2 Markdown and rendering security

Markdown fields in Contentstack often contain rich content. Unsafe rendering can lead to XSS, prompt injection, or UI manipulation.

## 2.1 Markdown is untrusted input

All markdown must be treated as untrusted, including:

- Entry rich text fields


- Blog content


- User generated comments


- Third party integrations



## 2.2 Required sanitization

Before rendering markdown to HTML or passing to a model:

- Strip <script> tags


- Remove inline event handlers (onclick, onerror, etc.)


- Sanitize embedded HTML


- Neutralize data URLs


- Remove hidden instructions in HTML comments



### Recommended tools

- DOMPurify


- sanitize-html


- markdown-it with HTML disabled


- server side sanitization before delivery



## 2.3 Model safe markdown handling

When sending markdown to LLMs:

- Remove hidden instructions and HTML comments


- Strip metadata blocks that may contain instructions


- Limit maximum markdown length


- Convert to plain text when possible for analysis tasks



# 3 Hallucination mitigation

LLMs may produce plausible but incorrect information. Skills must reduce the risk of false outputs, especially when interacting with content or APIs.

## 3.1 Require grounding

Skills must ground responses in:

- Contentstack data


- Verified API responses


- Explicit user input


- Known schemas



### Required controls

- Use retrieval augmented generation (RAG) where applicable.


- Cite content sources when generating summaries.


- Avoid inventing fields, IDs, or content types.



## 3.2 Structured output enforcement

Prefer structured outputs over free text.

### Example

Instead of:

"Here is the content model"

Use:

```json
{
  "content_type": "blog_post",
  "fields": [...]
}
```

Validate outputs against schemas before use.

## 3.3 Refusal behavior

Skills must refuse when:

- Data is missing or ambiguous


- Confidence is low


- The request requires guessing


- The model attempts to fabricate content



### Example refusal

I cannot determine the content type from the provided data. Please specify the content type UID.

# 4 Tool and action safety

Skills that perform actions must implement safeguards.

## 4.1 Confirmation for destructive actions

Require explicit confirmation for:

- Deleting entries


- Publishing content


- Changing environments


- Rotating tokens


- Modifying permissions



## 4.2 Scope enforcement

Skills must:

- Enforce environment scoping


- Prevent cross stack access


- Validate API tokens and scopes


- Never expose secrets in outputs



# 5 Logging and observability

When possible, Skills must log:

- Injection attempts


- Refusals


- Destructive actions


- Permission errors


- External API failures



Repeated injection or manipulation attempts must send an alert and be investigated by the skill owner. Logs must not contain secrets or tokens.

If it is not possible to log Skill data, there must be a comment with the Skill noting why and how issues could be investigated.

# 6 Secure skill design checklist

Before publishing, skill authors must verify:

### Prompt safety checklist

- No untrusted input in system prompts


- Injection patterns detected and handled



Clear role separation in messages

### Markdown safety

- Markdown sanitized before rendering


- HTML disabled or sanitized


- Hidden instructions removed



### Hallucination controls

- Responses grounded in real data


- Structured outputs used where possible


- Refusal behavior implemented



### Action safety

- Confirmation required for destructive actions


- Permissions scoped correctly


- Secrets never exposed



### Observability

- Security events logged


- No sensitive data in logs



# 7 Inventory

Contentstack will maintain an inventory of Skills documented at . The inventory must list:

- The name of the skill


- What function the skill is performing


- Who the maintainer/contact person for the Skill is


- A link the Checklist from this policy signing off on the review



# 8 Non compliance

Skills that do not comply with this policy may be:

- Rejected from the marketplace


- Disabled or sandboxed


- Revoked from Contentstack integrations



# 9 Future considerations

This policy will evolve to address:

- Model level guardrails


- Signed skill manifests


- Runtime sandboxing


- Trust scoring for community skills




