MCP server for CMS 13
Mark (Optimizely Agent Platform) is an agent orchestration platform that helps you work smarter in CMS 13. The Optimizely.Cms.Opal.Tools package includes a Model Context Protocol (MCP) server that exposes the same CMS tools available through Mark chat to any MCP-compatible AI client. Manage CMS content, content types, and display templates from your development environment with an MCP client such as Claude Code or Cursor. The MCP server puts these tools in the editor where you write code, so you can create content types and display templates while building the templates that render them.
The MCP server shares the same tools and descriptions as the Mark protocol. See Available tools for CMS 13 for the full tool reference.
Prerequisites
The MCP server requires the following:
- .NET 10.0 or later.
- Optimizely.Cms.Opal.Tools 13.2.0 or later. Optimizely Identity authentication requires 13.4.0 or later.
- Optimizely.Cms.Mcp.Tools.OptimizelyIdentity 13.4.0 or later, for Optimizely Identity authentication only. This package requires CMS 13.4.0 or later.
Choose an authentication method
The authentication method controls which identity the MCP server uses and which CMS permissions apply to each tool call. Choose the method that matches your environment.
Method | Use case | Permissions | Package |
|---|---|---|---|
Optimizely Identity | Production and multi-user environments | Each user's own CMS permissions, through Opti ID | Optimizely.Cms.Mcp.Tools.OptimizelyIdentity |
Client secret | Local development and trusted networks | Full administrator access (CmsAdmins role) | Included in Optimizely.Cms.Opal.Tools |
Configure Optimizely Identity authentication
Use Optimizely Identity authentication so that each user signs in with their own Opti ID account. Each tool call runs with that user's CMS permissions, so Optimizely recommends this method for production and multi-user environments.
The Optimizely.Cms.Mcp.Tools.OptimizelyIdentity package adds an OAuth 2.1 authorization server to your CMS site. This server handles sign-in between MCP clients and Opti ID and issues the access tokens that the clients use.
Prerequisites for Optimizely Identity
Optimizely Identity authentication requires the following:
- Opti ID configured for your CMS instance with services.AddOptimizelyIdentity(). Set Authority, ClientId, ClientSecret, and InstanceId under EPiServer:Cms:OptimizelyIdentity in appsettings.json.
- The redirect URI https://YOUR_CMS_HOST/_mcpauthz/callback allowed for your Opti ID client.
- A SQL Server database. The package creates its database tables at startup.
- HTTPS on all endpoints. The authorization endpoints return 403 with the https_required error for HTTP requests.
Install the package
Add the package to your CMS project:
dotnet add package Optimizely.Cms.Mcp.Tools.OptimizelyIdentityRegister services and map endpoints
Register the MCP server with Optimizely Identity authentication, and then map the endpoints in your application pipeline:
// In ConfigureServices
services.AddCmsMcpServer()
.WithOptimizelyIdentityAuthentication();
// In Configure
app.UseEndpoints(endpoints =>
{
endpoints.MapContent();
endpoints.MapMcpWithOptimizelyIdentity();
});MapMcpWithOptimizelyIdentity() maps the MCP endpoint and the authorization endpoints that MCP clients use to sign in. The MCP endpoint path is /mcp by default. To change the path, set ResourcePath in the Optimizely:Cms:Mcp:Authentication configuration section.
Configure signing credentials
The authorization server signs each access token that it issues. On Optimizely Digital Experience Platform (DXP), the server gets X.509 certificates from ICertificateProvider. It uses the certificate named oidc-signing. When that certificate does not exist, it uses the other available certificates.
For local development, add development signing credentials:
var mcpBuilder = services.AddCmsMcpServer()
.WithOptimizelyIdentityAuthentication();
if (env.IsDevelopment())
{
mcpBuilder.AddDevelopmentSigningCredentials();
}Configure the authorization server
Configure the authorization server in the Optimizely:Cms:Mcp:Authentication section of appsettings.json. The following example sets the public URL of the site and registers one MCP client:
{
"Optimizely": {
"Cms": {
"Mcp": {
"Authentication": {
"BaseUrl": "https://YOUR_CMS_HOST",
"PreRegisteredClients": [
{
"ClientId": "my-client",
"ClientName": "My MCP Client",
"RedirectUris": ["http://localhost:3000/callback"]
}
]
}
}
}
}
}BaseUrl is the public URL of your CMS site. The server builds the issuer and audience of each access token from this URL. When you do not set BaseUrl, the server uses the host of each request instead. Set BaseUrl in production so that tokens stay valid when the site has more than one hostname.
Use an absolute HTTPS URL without a path for BaseUrl. The site does not start if the value is not valid. BaseUrl does not limit which hosts serve the endpoints. To limit them, call RequireHost() on the MCP endpoint.
The section also supports the following settings:
- PathPrefix – Path of the authorization endpoints. The default is /_mcpauthz. When you change it, also allow the matching /callback redirect URI for your Opti ID client. Restart the site after you change it.
- ResourcePath – Path of the MCP endpoint. The default is /mcp. Restart the site after you change it.
- AccessTokenLifetime – How long an access token is valid. The default is 15 minutes.
- RefreshTokenLifetime – How long a refresh token is valid. The default is one day. Each refresh token works once, and the client gets a replacement token when it uses one.
- EnableClientIdMetadataDocuments – Lets clients identify themselves with a client ID metadata document. The default is true.
- PreRegisteredClients – MCP clients that you register in configuration. The default is an empty list.
Identify MCP clients
The authorization server identifies each MCP client in one of the following ways:
- Client ID metadata document – The default method. The client uses an HTTPS URL as its client ID. The server reads the client name and redirect uniform resource identifiers (URIs) from a metadata document at that URL. The server needs no configuration for this method. The MCP specification prefers this method. Claude Code, Claude Desktop, and other clients support it. During sign-in, the user approves the client on an Authorize Application page.
- Pre-registered client – The client uses a plain-text client ID, such as cursor. Add the client to PreRegisteredClients in the configuration. Pre-registered clients skip the Authorize Application page.
Each entry in PreRegisteredClients has the following properties:
- ClientId – Required. The client ID that the MCP client sends.
- RedirectUris – Required. The redirect URIs that the client uses. A localhost, 127.0.0.1, or [::1] URI matches any port. Any other URI must use HTTPS and match exactly.
- ClientName – Optional. The name that the MCP Sessions page displays. The default is the client ID.
The authorization server does not support Dynamic Client Registration (DCR), in which a client registers itself with the server. A client that relies on DCR must use a pre-registered client ID. When the client has no setting for a static client ID, connect it through an OAuth proxy.
User access and permissions
Only Opti ID users who have access to your CMS instance can sign in. Other users receive an access_denied error. The Opti ID roles of each user become CMS roles, so each tool runs with that user's CMS permissions. CMS checks the user's access with Opti ID again each time the client refreshes its token.
Use an OAuth proxy for unsupported clients
The following MCP clients cannot sign in to the authorization server directly:
- Clients that do not support OAuth 2.1.
- Clients that support OAuth 2.1 but not client ID metadata documents or a static client ID setting.
An OAuth proxy such as mcp-remote runs on the user's computer and completes the sign-in flow for the client. The proxy then connects to the client through standard input and output (stdio).
To connect a client through mcp-remote, complete the following steps:
- Add mcp-remote to the PreRegisteredClients configuration:
"PreRegisteredClients": [
{
"ClientId": "mcp-remote",
"ClientName": "mcp-remote",
"RedirectUris": [
"http://localhost/oauth/callback",
"http://127.0.0.1/oauth/callback"
]
}
]- In the MCP client configuration, pass the client ID to mcp-remote with the --static-oauth-client-info option:
{
"mcpServers": {
"optimizely-cms": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://YOUR_CMS_HOST/mcp",
"--static-oauth-client-info",
"{\"client_id\":\"mcp-remote\"}"
]
}
}
}Redirect URIs on localhost or 127.0.0.1 match any port. You do not need to set the port that mcp-remote uses for its callback. The host must match exactly, so register localhost and 127.0.0.1 as separate URIs.
Configure client secret authentication
Use client secret authentication for local development on a trusted network. The MCP client sends a shared secret in the Authorization header, and the server grants full administrator access.
Register services and map the endpoint
Register the MCP server with client secret authentication, and then map the MCP endpoint:
// In ConfigureServices
services.AddCmsMcpServer()
.WithClientSecretAuthentication();
// In Configure
app.UseEndpoints(endpoints =>
{
endpoints.MapContent();
endpoints.MapMcp("/mcp").RequireClientSecretAuthorization();
});Configure the secret
Add the secret to appsettings.json:
{
"Optimizely": {
"Cms": {
"Mcp": {
"Secret": "YOUR_SECRET"
}
}
}
}For local development, store the secret in user secrets instead so that it stays out of source control:
dotnet user-secrets set "Optimizely:Cms:Mcp:Secret" "YOUR_SECRET"The client secret handler creates an identity with the CmsAdmins role, which has full access to all CMS tools. Use this method only when you do not need per-user permissions.
Connect an MCP client
After you configure the MCP server, add it to your MCP client. The client configuration depends on the authentication method.
Connect with Optimizely Identity
A client that supports client ID metadata documents needs only the endpoint URL. When the client connects, it detects that the server requires authentication and opens a browser for Opti ID sign-in.
For example, in Claude Code, add the following to .mcp.json:
{
"mcpServers": {
"optimizely-cms": {
"type": "http",
"url": "https://YOUR_CMS_HOST/mcp"
}
}
}Cursor does not support client ID metadata documents, so it requires a pre-registered client. To connect Cursor, complete the following steps:
- Add the Cursor redirect URIs to the PreRegisteredClients configuration:
"PreRegisteredClients": [
{
"ClientId": "cursor",
"ClientName": "Cursor",
"RedirectUris": [
"http://localhost:8787/callback",
"https://www.cursor.com/agents/mcp/oauth/callback"
]
}
]Only Cursor Cloud Agents requires the https://www.cursor.com/agents/mcp/oauth/callback redirect URI.
- In .cursor/mcp.json, set the client ID in the auth block:
{
"mcpServers": {
"optimizely-cms": {
"url": "https://YOUR_CMS_HOST/mcp",
"auth": {
"CLIENT_ID": "cursor"
}
}
}
}For other clients that cannot sign in directly, see Use an OAuth proxy for unsupported clients.
Connect with client secret authentication
MCP clients send the secret in the Authorization header. In Claude Code or Cursor, add the following to .mcp.json or .cursor/mcp.json:
{
"mcpServers": {
"optimizely-cms": {
"type": "http",
"url": "https://YOUR_CMS_HOST/mcp",
"headers": {
"Authorization": "YOUR_SECRET"
}
}
}
}In Codex, add the following to ~/.codex/config.toml:
[mcp_servers.optimizely-cms]
type = "http"
url = "https://YOUR_CMS_HOST/mcp"
[mcp_servers.optimizely-cms.headers]
Authorization = "YOUR_SECRET"Connect other MCP clients
Any MCP client that supports the streamable HTTP transport can connect. Configure the client with the following settings:
- Endpoint URL – https://YOUR_CMS_HOST/mcp
- Transport – Streamable HTTP (stateless)
- Authentication – For Optimizely Identity, provide the endpoint URL, and the client completes sign-in. A client without client ID metadata document support also needs a pre-registered client ID or an OAuth proxy. For client secret authentication, set the secret in the Authorization header.
Manage MCP sessions
Review which users and clients connect to the MCP server through Optimizely Identity authentication, and revoke access when a user or client no longer needs it.
Go to Settings > Access Rights > MCP Sessions. The page has the following tabs:
- Active Sessions – Lists sessions by user and client. Click Revoke to end a session.
- Connected Clients – Lists the clients that users have connected. Click View Sessions to see the sessions of a client, or click Revoke All to end all of them.
Revoking a session prevents the client from getting new access tokens. An access token that CMS already issued stays valid until it expires, which is 15 minutes by default.
Tool permissions
Each MCP tool call runs CMS operations on behalf of the authenticated user. CMS applies its standard permission model, so a tool accesses only content that the user has permission to access. Some tools, such as content type management, require the CmsAdmins role. Other tools use the user's own content permissions.