sitecore-personalize-mcp
Provides tools for interacting with Sitecore Personalize/CDP, enabling management of decisioning flows, experiences, audiences, guest profiles, behavioral events, and datasets.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sitecore-personalize-mcp list all decisioning flows"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP for Sitecore Personalize and CDP
A production-ready Model Context Protocol server for Sitecore
Personalize / CDP, built with the official @modelcontextprotocol/sdk, TypeScript, Zod, and Axios.
Every Sitecore Personalize API operation is exposed as its own MCP tool, so an MCP client (Claude
Desktop, Claude Code, or any other MCP host) can list/manage decisioning flows and experiences, read
and update CDP guest profiles, send behavioral events, and work with audiences and datasets.
Architecture
src/
index.ts Process entry point: stdio transport wiring, signal handling
server.ts McpServer construction + tool registration
config/
env.ts Zod-validated environment configuration (fails fast at startup)
constants.ts API route table, server metadata, retry-status set
auth/
tokenManager.ts OAuth2 client_credentials flow, in-memory cache, refresh locking
services/
httpClient.ts Shared axios factory: auth injection, retry/backoff, error normalization
flowService.ts Flow list/get/publish/execute
experienceService.ts Experience list/get/publish
audienceService.ts Audience (segment) list/get/create
guestService.ts CDP guest get/upsert/delete/search
eventService.ts CDP event ingestion
datasetService.ts Dataset list/get
schemas/ One Zod schema module per domain (shared between tool input
validation and typed service calls)
tools/ One MCP tool per API operation, grouped by domain, registered
from tools/index.ts
utils/
logger.ts pino structured logger (stderr only — stdout is reserved for
MCP protocol frames)
errors.ts Typed error hierarchy (ValidationError, AuthenticationError,
SitecoreApiError, RetryExhaustedError, ConfigurationError)
retry.ts Exponential backoff w/ full jitter, used by httpClient
responseFormatter.ts Wraps service results into MCP CallToolResult (success/isError)Design principles:
Clean separation of concerns. Tools only translate MCP calls into service calls and format results — they contain no HTTP or business logic. Services own API contracts.
httpClientowns cross-cutting HTTP concerns (auth, retry, logging, error shape) so every service gets them for free.Every operation is its own tool. No multiplexed "do anything" tool — each is independently discoverable, documented, and schema-validated, which is what lets an MCP client (or the model driving it) reason about what's safe to call.
Fail fast, fail loud. Environment variables are validated once at startup with Zod; a misconfigured deployment never gets as far as accepting a tool call.
stdout is sacred. All logging goes to stderr via pino. Never
console.login this codebase — it will corrupt the JSON-RPC stream on the stdio transport.
Related MCP server: mcp-sitecore-server
Setup
npm install
cp .env.example .env
# edit .env with your tenant's client ID/secret and API URLs
npm run build
npm startFor local iteration with auto-reload: npm run dev (uses tsx watch).
Required environment variables
Variable | Description |
| OAuth2 client ID from Sitecore Cloud Portal |
| OAuth2 client secret |
| Identity token endpoint |
| Personalize/CDP admin API base URL for your tenant/region |
| (optional) Interactive decisioning/edge API base, if it differs from the admin API |
See .env.example for the full list, including HTTP timeout/retry tuning and log level.
Verify API routes before production use. Sitecore Personalize's REST surface is versioned and tenant/region-hosted. The route table in
src/config/constants.tsreflects the commonly documented v2/v3 shapes, but you should confirm exact paths against your tenant's current API reference before relying on this in production, and adjust that one file if anything differs.
Connecting to Claude Desktop / Claude Code
Add to your MCP client config (e.g. claude_desktop_config.json):
{
"mcpServers": {
"sitecore-personalize": {
"command": "node",
"args": ["/absolute/path/to/sitecore-personalize-mcp/dist/index.js"],
"env": {
"SITECORE_PERSONALIZE_CLIENT_ID": "...",
"SITECORE_PERSONALIZE_CLIENT_SECRET": "...",
"SITECORE_PERSONALIZE_AUTH_URL": "...",
"SITECORE_PERSONALIZE_API_URL": "...",
"SITECORE_CDP_CLIENT_KEY": "...",
"SITECORE_CDP_API_TOKEN": "...",
"SITECORE_CDP_API_URL": "..."
}
}
}
}Tools
All tool names are prefixed sitecore_personalize_.
Tool | Type | Description |
| read | List decisioning flows, filterable by status |
| read | Get a single flow's definition |
| write | Publish a draft flow |
| write | Trigger real-time flow decisioning for a guest ( |
| read | List experiences, filterable by type/status |
| read | Get a single experience's definition |
| write | Publish a draft experience |
| read | List audiences/segments |
| read | Get a single audience's rules |
| write | Create a new rule-based audience |
| read | Get a CDP guest profile by reference |
| write | Create or update a guest profile |
| write (destructive) | Permanently delete a guest profile |
| read | Search guests by email or attribute |
| write | Ingest a behavioral event for a guest |
| read | List datasets |
| read | Get a single dataset's metadata |
Every write tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint) so
clients can apply appropriate confirmation UX — guest_delete in particular is flagged destructive
and irreversible.
Error handling & resilience
Validation happens at the MCP layer via each tool's Zod
inputSchemabefore any service code runs.Auth failures raise
AuthenticationError; a401from the API triggers one transparent token refresh + retry before failing.Transient failures (
429,5xx, network errors) are retried with exponential backoff + full jitter, up toMAX_RETRIES(default 3).All failures are normalized into typed errors and returned to the MCP client as
{ isError: true, content: [...] }— never as an uncaught exception that would kill the process or return an opaque transport error.
Extending
To add a new API operation:
Add its request/response shape to the relevant
src/schemas/*.schema.ts(or a new file for a new domain).Add the route to
src/config/constants.tsand the call to the matchingsrc/services/*.ts.Register a tool for it in
src/tools/*.tools.ts, following the existing pattern (registerTool→ service call →toolSuccess/toolError).If it's a new domain, wire its
registerXTools(server)intosrc/tools/index.ts.
Scripts
Command | Purpose |
| Type-check and compile to |
| Run the compiled server |
| Run with |
| Type-check without emitting |
| Remove |
Available Tools
17 toolssitecore_personalize_audience_createCreate Personalize AudienceA
Creates a new audience/segment from a set of attribute rules. This is a write operation that adds a new segment to the tenant.
Inputs: name (required), rules (required), matchType, description.
sitecore_personalize_audience_getGet Personalize AudienceA
Retrieves the definition and membership rules of a single audience/segment by ID.
Inputs: audienceId (required).
sitecore_personalize_audience_listList Personalize AudiencesA
Lists audiences (segments) configured in Sitecore Personalize/CDP. Supports pagination.
Inputs: limit, offset.
sitecore_personalize_dataset_getGet Personalize DatasetA
Retrieves metadata and schema information for a single dataset by ID.
Inputs: datasetId (required).
sitecore_personalize_dataset_listList Personalize DatasetsB
Lists datasets (e.g. product catalogs, custom reference data) available in the tenant.
Inputs: limit, offset.
sitecore_personalize_event_sendSend CDP EventA
Ingests a behavioral event (e.g. PRODUCT_VIEW, ADD_TO_CART, ORDER) into Sitecore CDP for a guest, feeding real-time and batch decisioning. This is a write operation.
Inputs: type (required), guestRef (required), channel, currency, +3 more.
sitecore_personalize_experience_getGet Personalize ExperienceA
Retrieves a single experience (flow definition with subtype EXPERIENCE) by its ref. Equivalent to sitecore_personalize_flow_get — provided as a named convenience for experience-specific workflows.
Inputs: flowRef (required).
sitecore_personalize_experience_listList Personalize ExperiencesA
Lists experiences (flow definitions with subtype EXPERIENCE) configured in Sitecore Personalize. Equivalent to sitecore_personalize_flow_list with subtype='EXPERIENCE' pre-applied. Supports offset/limit pagination.
Inputs: limit, offset.
sitecore_personalize_flow_executeExecute Personalize Flow (callFlows)A
Triggers real-time decisioning execution of a published flow, identified by friendlyId, for a guest identified by exactly one of browserId, email, or identifiers — returning the flow's decision output. Equivalent to the Personalize interactive callFlows API.
Inputs: friendlyId (required), email, params, browserId, +1 more.
sitecore_personalize_flow_getGet Personalize Flow DefinitionA
Retrieves the full definition of a single flow (experiment or experience) by its ref.
Inputs: flowRef (required).
sitecore_personalize_flow_listList Personalize Flow DefinitionsA
Lists flow definitions (experiments and experiences) configured in Sitecore Personalize. Filter by subtype ('EXPERIMENT' or 'EXPERIENCE') to distinguish A/B tests from experiences. Supports offset/limit pagination.
Inputs: limit, offset, subtype.
sitecore_personalize_flow_set_statusSet Personalize Flow Status (publish/pause)AIdempotent
Changes a flow definition's status (e.g. to 'PRODUCTION' or 'LIVE' to publish, 'PAUSED' to pause). Sitecore has no dedicated publish endpoint — this reads the current flow definition and writes it back with the new status, since updates are a full replace. This is a write operation with production impact.
Inputs: status (required), flowRef (required).
sitecore_personalize_guest_deleteDelete CDP Guest ProfileADestructiveIdempotent
Permanently deletes a guest profile and its associated data from Sitecore CDP. This is a destructive, irreversible operation — typically used for privacy/right-to-be-forgotten requests. NOTE: this endpoint is unverified against Sitecore's docs — confirm with curl/Postman before relying on it.
Inputs: guestRef (required).
sitecore_personalize_guest_getGet CDP Guest ProfileA
Retrieves a single guest (visitor/contact) profile from Sitecore CDP by guest reference.
Inputs: guestRef (required).
sitecore_personalize_guest_searchSearch CDP Guest ProfilesB
Searches for guest profiles by email. Supports pagination. NOTE: this endpoint is unverified against Sitecore's docs — confirm with curl/Postman before relying on it.
Inputs: email, limit, offset.
sitecore_personalize_guest_set_data_extensionSet CDP Guest Data Extension (custom attributes)BIdempotent
Sets arbitrary custom key/value attributes on a guest via Sitecore's Guest data extension mechanism (one of 6 fixed groups: ext, ext1-ext5). This call REPLACES the entire named group — any existing key not included gets deleted. NOTE: the exact URL path shape for this endpoint is unverified against Sitecore's docs (they render inconsistently across doc pages) — confirm with curl/Postman against your tenant before relying on it in production.
Inputs: guestRef (required), attributes (required), extensionGroup.
sitecore_personalize_guest_upsertCreate or Update CDP Guest ProfileAIdempotent
Creates a new guest profile (POST), or updates an existing one (PUT) when guestRef is provided. Covers the base guest object fields (name, contact info, address, etc.) — for arbitrary custom key/value attributes, use sitecore_personalize_guest_set_data_extension instead, which is a separate Sitecore mechanism.
Inputs: city, state, title, emails, +13 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
The core resources (flow, audience, guest, dataset, event) are clearly separated, but flow and experience overlap heavily: experience_list/get are documented as exact equivalents of flow_list/get with a subtype pre-applied. This duplication is explained, but an agent could reasonably select either path for the same operation.
All tools follow a consistent sitecore_personalize_<resource>_<action> snake_case convention, such as flow_list, audience_get, guest_upsert, and event_send. The action verbs are predictable and there are no mixed casing or naming styles.
17 tools is at the upper edge but reasonable for a server spanning flows, experiences, audiences, guests, datasets, and events. The experience_list/get convenience duplicates add slight bloat, but most tools map to a distinct domain operation.
The guest lifecycle is well covered with get, upsert, delete, search, and data extension handling, and flows support listing, retrieving, status changes, and execution. However, audiences have create and read but no update/delete, flows cannot be created or updated beyond status, and datasets are read-only, leaving notable lifecycle gaps.
Maintenance
Related MCP Connectors
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Related MCP Servers
- AlicenseCqualityDmaintenanceA SitecoreMCP version that can be used in enterprises100Apache 2.0
- AlicenseBqualityBmaintenanceMCP server for Sitecore that provides tools to interact with Sitecore via GraphQL, Item Service API, and Sitecore PowerShell Extensions, enabling content and security management.121167 npm52Apache 2.0
- AlicenseBqualityDmaintenanceMCP server for Salesforce Interaction Studio that enables listing and managing datasets, campaigns, segments, and performance stats via natural language.22MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides AI agents with direct read/write access to Sitecore CMS through 100+ tools across Item Service, GraphQL, and PowerShell APIs.Apache 2.0