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. Repo details

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. Usage examples

11. Quick reference — all endpoints

Related MCP server: SitecoreMCP

1. Repo Details

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

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. Usage examples

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.

11. Quick reference — all endpoints