Sitecore Personalize

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. httpClient owns 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.log in this codebase — it will corrupt the JSON-RPC stream on the stdio transport.

Setup

npm install
cp .env.example .env
# edit .env with your tenant's client ID/secret and API URLs
npm run build
npm start

For local iteration with auto-reload: npm run dev (uses tsx watch).

Required environment variables

Variable	Description
SITECORE_PERSONALIZE_CLIENT_ID	OAuth2 client ID from Sitecore Cloud Portal
SITECORE_PERSONALIZE_CLIENT_SECRET	OAuth2 client secret
SITECORE_PERSONALIZE_AUTH_URL	Identity token endpoint
SITECORE_PERSONALIZE_API_URL	Personalize/CDP admin API base URL for your tenant/region
SITECORE_PERSONALIZE_DECISIONING_API_URL	(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.ts reflects 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
flow_list	read	List decisioning flows, filterable by status
flow_get	read	Get a single flow's definition
flow_publish	write	Publish a draft flow
flow_execute	write	Trigger real-time flow decisioning for a guest (callFlow)
experience_list	read	List experiences, filterable by type/status
experience_get	read	Get a single experience's definition
experience_publish	write	Publish a draft experience
audience_list	read	List audiences/segments
audience_get	read	Get a single audience's rules
audience_create	write	Create a new rule-based audience
guest_get	read	Get a CDP guest profile by reference
guest_upsert	write	Create or update a guest profile
guest_delete	write (destructive)	Permanently delete a guest profile
guest_search	read	Search guests by email or attribute
event_send	write	Ingest a behavioral event for a guest
dataset_list	read	List datasets
dataset_get	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 inputSchema before any service code runs.
• Auth failures raise AuthenticationError; a 401 from the API triggers one transparent token refresh + retry before failing.
• Transient failures (429, 5xx, network errors) are retried with exponential backoff + full jitter, up to MAX_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:

1. Add its request/response shape to the relevant src/schemas/*.schema.ts (or a new file for a new domain).
2. Add the route to src/config/constants.ts and the call to the matching src/services/*.ts.
3. Register a tool for it in src/tools/*.tools.ts, following the existing pattern (registerTool → service call → toolSuccess/toolError).
4. If it's a new domain, wire its registerXTools(server) into src/tools/index.ts.

Scripts

Command	Purpose
npm run build	Type-check and compile to dist/
npm start	Run the compiled server
npm run dev	Run with tsx watch for local development
npm run typecheck	Type-check without emitting
npm run clean	Remove dist/