Sitecore XM Cloud MCP Server — Complete Documentation

This repository is a Next.js application that exposes a Model Context Protocol (MCP) server for Sitecore XM Cloud. AI clients (Cursor, Sitecore Agentic Studio, Claude Desktop, etc.) can connect to it and invoke tools that perform Sitecore authoring operations — today, primarily creating data templates via the Sitecore Authoring GraphQL API.

The app is designed to run locally or on Vercel, and it implements the OAuth discovery and proxy routes required for Sitecore Agentic Studio to authenticate against the MCP endpoint.

Table of Contents

1. What problem does this solve?

2. High-level architecture

3. Two separate authentication systems

4. Project structure

5. Route reference — what each endpoint does and why it exists

6. MCP tools

7. Core library modules

8. Environment variables

9. Setup and running locally

10. End-to-end flows

11. Usage examples

12. Deployment notes

1. What problem does this solve?

Without this repo

• AI assistants have no native way to talk to Sitecore XM Cloud.

• Sitecore authoring operations (like creating templates) require authenticated GraphQL calls with XM Cloud Automation Client credentials.

• Sitecore Agentic Studio expects MCP servers to support OAuth 2.0 protected resource discovery — a standard way for clients to discover how to authenticate before calling /api/mcp.

With this repo

In short: this repo is a bridge between AI MCP clients and Sitecore XM Cloud, with OAuth plumbing so enterprise Sitecore tools can connect securely.

2. High-level architecture

flowchart TB
    subgraph clients [AI Clients]
        Cursor[Cursor / Claude Desktop]
        Agentic[Sitecore Agentic Studio]
        REST[Direct REST callers]
    end

    subgraph nextjs [Next.js App - sitecore-mcp]
        MCP["/api/mcp"]
        OAuth["OAuth routes<br/>/.well-known/*"]
        SitecoreAPI["/api/sitecore/*"]
        Lib["src/lib/sitecore/*"]
    end

    subgraph external [External Services]
        Auth0[Auth0]
        XMCloud["Sitecore XM Cloud<br/>auth.sitecorecloud.io"]
        GraphQL["Authoring GraphQL API"]
    end

    Cursor -->|MCP HTTP optional Bearer| MCP
    Agentic -->|OAuth discovery + MCP| OAuth
    Agentic --> MCP
    REST --> SitecoreAPI

    OAuth --> Auth0
    MCP --> Lib
    SitecoreAPI --> Lib
    Lib -->|client_credentials| XMCloud
    Lib -->|Bearer token| GraphQL

Data flow for a template creation:

1. MCP client calls createTemplate tool on /api/mcp.

2. MCP handler invokes createSitecoreTemplate() in the library layer.

3. Library obtains (or reuses cached) XM Cloud bearer token.

4. Library resolves parent folder path → GUID, then runs createItemTemplate GraphQL mutation.

5. Result is returned to the AI client as JSON text content.

3. Two separate authentication systems

This is the most important concept to understand. The repo uses two independent auth flows for two different purposes:

A. Sitecore XM Cloud auth (server → Sitecore)

• Who uses it: The Next.js server itself, when calling Sitecore GraphQL.

• How: OAuth 2.0 client_credentials with an XM Cloud Automation Client.

• Env vars: SITECORE_CLIENT_ID, SITECORE_CLIENT_SECRET, SITECORE_AUTHORING_ENDPOINT

• Token endpoint: https://auth.sitecorecloud.io/oauth/token

• Audience: https://api.sitecorecloud.io

• Implementation: src/lib/sitecore/auth.ts — tokens are cached in memory until near expiry.

This auth is never exposed to MCP clients. The server holds Sitecore credentials and acts on behalf of the connected AI user.

B. MCP client OAuth (client → this app)

• Who uses it: MCP clients like Sitecore Agentic Studio that require OAuth before accessing /api/mcp.

• How: OAuth 2.0 Authorization Code flow with PKCE, proxied through this app to Auth0.

• Env vars: AUTH0_DOMAIN, AUTH0_AUDIENCE, AUTH0_WEB_CLIENT_ID, AUTH0_WEB_CLIENT_SECRET, MCP_BASE_URL

• Implementation: OAuth routes under /oauth/* and /.well-known/*.

When a client hits /api/mcp without a Bearer token, withMcpOAuthChallenge returns 401 Unauthorized with a WWW-Authenticate header pointing to resource metadata — this triggers the client's OAuth discovery flow.

Note: The current OAuth middleware only checks that a Bearer token is present; it does not validate the JWT against Auth0. Full token verification would be a natural next hardening step.

4. Project structure

sitecore-mcp/
├── src/
│   ├── app/
│   │   ├── page.tsx                          # Landing page with setup hints
│   │   ├── layout.tsx                        # Root layout
│   │   ├── api/
│   │   │   ├── mcp/
│   │   │   │   ├── route.ts                  # Main MCP endpoint (auth-wrapped)
│   │   │   │   ├── mcpServer.ts              # MCP tool definitions
│   │   │   │   ├── sse/route.ts              # SSE transport (GET)
│   │   │   │   └── message/route.ts          # SSE message channel (POST)
│   │   │   └── sitecore/
│   │   │       ├── token/route.ts            # Debug: verify Sitecore auth
│   │   │       └── templates/route.ts        # REST alternative to MCP tool
│   │   ├── oauth/
│   │   │   ├── authorize/route.ts            # Start OAuth → redirect to Auth0
│   │   │   ├── callback/route.ts             # Auth0 callback → redirect to Sitecore
│   │   │   ├── token/route.ts                # Exchange code for Auth0 tokens
│   │   │   └── register/route.ts             # Dynamic client registration (stub)
│   │   └── .well-known/
│   │       ├── oauth-authorization-server/   # OAuth server metadata
│   │       └── oauth-protected-resource/     # Protected resource metadata
│   │           └── api/mcp/                  # Resource-specific metadata for MCP
│   └── lib/
│       └── sitecore/
│           ├── config.ts                     # Sitecore env config
│           ├── auth.ts                       # XM Cloud token acquisition + cache
│           ├── graphql.ts                    # GraphQL client with 401 retry
│           ├── createTemplate.ts             # Template creation business logic
│           ├── oauthMetadata.ts              # OAuth discovery JSON builders
│           └── withMcpOAuthChallenge.ts      # 401 + WWW-Authenticate middleware
├── .env.example
├── vercel.json                               # 60s maxDuration for MCP routes
└── package.json

Key dependencies:

5. Route reference — what each endpoint does and why it exists

MCP routes

Why three MCP routes?
The MCP spec supports multiple transports. mcp-handler splits SSE into an event stream (/sse) and a message POST endpoint (/message), while Streamable HTTP uses a single /mcp route. Supporting both maximizes client compatibility (Cursor, Claude, Agentic Studio, etc.).

OAuth discovery routes (.well-known)

Why these exist?
Sitecore Agentic Studio (and the MCP OAuth spec) require clients to auto-discover how to authenticate. When /api/mcp returns 401 with resource_metadata=".../.well-known/oauth-protected-resource/api/mcp", the client fetches that URL, learns the authorization server, and starts the OAuth flow — no manual OAuth config in the client.

OAuth proxy routes

Why a proxy instead of pointing Sitecore directly at Auth0?
Sitecore Agentic Studio expects the MCP server's own domain to be the OAuth issuer (per MCP protected-resource spec). This app acts as an OAuth facade: discovery endpoints live on your MCP domain, while Auth0 handles real identity. The callback route also contains a workaround for Sitecore's https://0.0.0.0:3000 localhost redirect issue.

Sitecore REST routes (testing / direct API)

Why REST routes when MCP exists?
They let developers debug Sitecore connectivity independently of MCP/OAuth complexity. If template creation fails, you can isolate whether the problem is Sitecore auth or MCP client auth.

UI

6. MCP tools

Currently one tool is registered in mcpServer.ts:

createTemplate

Creates a Sitecore data template under a parent folder using the createItemTemplate GraphQL mutation.

Input parameters:

Section/field shape:

{
  "sections": [
    {
      "name": "Content",
      "fields": [
        { "name": "Title", "type": "Single-Line Text" },
        { "name": "Body", "type": "Rich Text" }
      ]
    }
  ]
}

Success response:

{
  "success": true,
  "template": {
    "id": "{GUID}",
    "name": "My Template",
    "fields": [{ "name": "Title", "type": "Single-Line Text" }]
  }
}

Internal steps:

1. Resolve parentPath → parent GUID (path lookup via GraphQL, or normalize if already a GUID).

2. Build and execute createItemTemplate mutation against the Authoring GraphQL endpoint.

3. Return created template ID, name, and fields.

7. Core library modules

config.ts

Loads and validates Sitecore environment variables. Defaults auth endpoint and audience to standard XM Cloud values.

auth.ts

• Calls client_credentials against Sitecore auth endpoint.

• Caches token in memory with 60-second expiry buffer.

• Exposes clearSitecoreTokenCache() for retry on 401.

graphql.ts

• Generic GraphQL executor for the Authoring API.

• Automatically attaches Sitecore bearer token.

• Retries once on 401 after clearing token cache.

• Throws on HTTP errors or GraphQL errors array.

createTemplate.ts

• Business logic for template creation.

• Path → GUID resolution.

• GraphQL mutation builder with string escaping.

• Structured { success, template?, error? } result type.

oauthMetadata.ts

• Builds OAuth discovery JSON payloads.

• Reads AUTH0_AUDIENCE as the protected resource identifier.

• Points authorization server metadata back to this app's /.well-known/oauth-authorization-server.

withMcpOAuthChallenge.ts

• Middleware wrapper for MCP routes.

• Returns 401 + WWW-Authenticate: Bearer resource_metadata="..." when no Bearer token.

• Passes through to handler when Bearer is present.

8. Environment variables

Copy .env.example to .env.local for local development.

Sitecore XM Cloud (required for template operations)

Auth0 / MCP OAuth (required for Sitecore Agentic Studio)

App

9. Setup and running locally

Prerequisites

• Node.js 18+

• XM Cloud Automation Client credentials (from XM Cloud Deploy)

• Auth0 tenant (only if using Sitecore Agentic Studio OAuth)

Steps

# 1. Install dependencies
npm install

# 2. Configure environment
cp .env.example .env.local
# Edit .env.local with your credentials

# 3. Add MCP_BASE_URL to .env.local
# MCP_BASE_URL=http://localhost:3000

# 4. Start dev server
npm run dev

App runs at http://localhost:3000.

Verify Sitecore connectivity

curl http://localhost:3000/api/sitecore/token

Expected: { "success": true, "expiresIn": ..., ... }

Create a template via REST

curl -X POST http://localhost:3000/api/sitecore/templates \
  -H "Content-Type: application/json" \
  -d '{
    "templateName": "Test Template",
    "parentPath": "/sitecore/templates/Feature",
    "sections": [{
      "name": "Content",
      "fields": [{ "name": "Title", "type": "Single-Line Text" }]
    }]
  }'

10. End-to-end flows

Flow A: Cursor / local MCP client (no OAuth)

sequenceDiagram
    participant Cursor
    participant MCP as /api/mcp
    participant Sitecore as XM Cloud GraphQL

    Cursor->>MCP: MCP initialize (may skip auth locally)
    MCP-->>Cursor: tools/list → createTemplate
    Cursor->>MCP: tools/call createTemplate
    MCP->>Sitecore: client_credentials → Bearer token
    MCP->>Sitecore: createItemTemplate mutation
    Sitecore-->>MCP: template created
    MCP-->>Cursor: JSON result

For local dev, you may hit /api/mcp directly. In production with OAuth enabled, clients must present a Bearer token.

Flow B: Sitecore Agentic Studio (full OAuth)

sequenceDiagram
    participant Studio as Agentic Studio
    participant MCP as /api/mcp
    participant Meta as /.well-known/*
    participant OAuth as /oauth/*
    participant Auth0

    Studio->>MCP: GET /api/mcp (no token)
    MCP-->>Studio: 401 WWW-Authenticate + resource_metadata URL

    Studio->>Meta: GET /.well-known/oauth-protected-resource/api/mcp
    Meta-->>Studio: authorization_servers, scopes

    Studio->>Meta: GET /.well-known/oauth-authorization-server
    Meta-->>Studio: authorize, token, register endpoints

    Studio->>OAuth: POST /oauth/register
    OAuth-->>Studio: client_id + client_secret (stub)

    Studio->>OAuth: GET /oauth/authorize?code_challenge=...
    OAuth->>Auth0: redirect to Auth0 login
    Auth0-->>OAuth: GET /oauth/callback?code=...
    OAuth-->>Studio: redirect with Auth0 code

    Studio->>OAuth: POST /oauth/token (code)
    OAuth->>Auth0: exchange code
    Auth0-->>OAuth: access_token
    OAuth-->>Studio: tokens

    Studio->>MCP: MCP requests with Bearer token
    MCP-->>Studio: tool responses

Flow C: Template creation (internal)

sequenceDiagram
    participant Tool as createTemplate
    participant Auth as auth.ts
    participant GQL as graphql.ts
    participant SC as Sitecore API

    Tool->>Auth: getSitecoreAccessToken()
    alt token cached
        Auth-->>Tool: cached token
    else token expired
        Auth->>SC: POST client_credentials
        SC-->>Auth: access_token
        Auth-->>Tool: new token
    end

    Tool->>GQL: resolve parent path → GUID
    GQL->>SC: item query
    SC-->>GQL: itemId

    Tool->>GQL: createItemTemplate mutation
    GQL->>SC: mutation
    SC-->>GQL: templateId, name, fields
    GQL-->>Tool: result

11. Usage examples

Cursor MCP configuration

Add to Cursor MCP settings (local, no auth):

{
  "mcpServers": {
    "sitecore": {
      "url": "http://localhost:3000/api/mcp"
    }
  }
}

For production with OAuth, your client must support Bearer token auth and the MCP OAuth discovery flow.

Claude Desktop (stdio bridge)

If your client only supports stdio:

{
  "mcpServers": {
    "sitecore": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/api/mcp"]
    }
  }
}

Sitecore Agentic Studio

Point Agentic Studio at your deployed MCP URL:

https://your-app.vercel.app/api/mcp

Agentic Studio will automatically run the OAuth discovery flow using the /.well-known and /oauth routes.

12. Deployment notes

• Platform: Vercel (see .vercel/project.json).

• Function timeout: vercel.json sets maxDuration: 60 for MCP routes — MCP sessions and GraphQL calls can be long-running.

• Runtime: All API routes use export const runtime = "nodejs" (required for MCP and OAuth).

• Dynamic: All routes use dynamic = "force-dynamic" — no static caching.

After deploying, set all environment variables in the Vercel dashboard, especially:

• MCP_BASE_URL=https://your-app.vercel.app

• AUTH0_AUDIENCE=https://your-app.vercel.app

Auth0 callback URL must include:

https://your-app.vercel.app/oauth/callback

Quick reference — all endpoints

Summary

This repo is a Sitecore-aware MCP server built on Next.js. It lets AI tools create Sitecore data templates by handling XM Cloud authentication server-side, while exposing standard MCP and OAuth discovery endpoints so clients like Sitecore Agentic Studio can connect securely. The routes exist because MCP requires specific transport endpoints, OAuth clients require .well-known discovery documents, and Sitecore Agentic Studio requires an OAuth proxy layer in front of Auth0 — each route serves a distinct part of that end-to-end integration.