---
title: "Set up your AI workbench for Contentstack"
url: "https://developers.contentstack.com/guides/set-up-your-ai-workbench-for-contentstack"
type: "guide"
level: "beginner"
intent: "build"
outcome: "Your AI tool has the Contentstack agent skills installed and is connected to MCP Profile Hub with a narrow profile, and you have run three tasks against your own stack."
prerequisites:
  - "A Contentstack account with access to at least one stack"
  - "An AI coding tool such as Claude Code, Cursor, Codex, GitHub Copilot or Gemini CLI"
  - "A browser on the same machine for the one-time sign-in"
tags:
  - "ai"
  - "agent_skills"
  - "mcp"
authors:
  - "Tim Benniks"
published: "2026-12-01T09:00:00.000Z"
updated: "2026-11-15T10:56:27.208Z"
---

# Set up your AI workbench for Contentstack

- **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.

