This post covers the setup gotchas, what each property type does on write and read-back, and a test that forces the notPersisted outcome. The last part matters most if you are building anything that calls these tools unattended.
Test setup
- CMS 13.5.1, .NET 10, Alloy MVC template, SQL Server, no Opti ID (this applies to my local MCP setup only; Opti ID is only available for CMS 13 instances hosted on DXP)
Optimizely.Cms.Opal.Tools13.4.1, the latest version on the Optimizely feed at the time. It depends onEPiServer.Cms.Core[13.4.0, 14.0.0), so it resolved cleanly against 13.5.1- Client secret authentication, the only option without Opti ID
The platform formerly known as Opal is now the Optimizely Agent Platform, with Mark as the assistant you talk to. The NuGet package ID and the code still say Opal and have not changed.
Do not use client secret authentication in a production environment exposed to the internet. The Optimizely docs say the same. Everything below is for local development.
// Startup.cs
using Optimizely.Cms.Opal.Tools;
// ConfigureServices
services.AddCmsMcpServer()
.WithClientSecretAuthentication();
// Configure
app.UseEndpoints(endpoints =>
{
endpoints.MapContent();
endpoints.MapMcp("/mcp").RequireClientSecretAuthorization();
});
dotnet user-secrets set "Optimizely:Cms:Mcp:Secret" "YOUR_SECRET"
That single using Optimizely.Cms.Opal.Tools; is enough. I tried dropping the .Authentication and .Authentication.ClientSecret namespaces and the build still passed.
Four things that failed before I wrote any content
1. The app needs the Development environment
I started the site with dotnet run --no-launch-profile, which defaults to Production. It crashed with a NullReferenceException inside AddCmsAspNetIdentity. The message says nothing about configuration. My connection string lives in appsettings.Development.json, and user secrets also only load in Development, so neither the connection string nor the MCP secret was there. Set ASPNETCORE_ENVIRONMENT=Development when you skip the launch profile.
2. The secret goes in the header as is
I sent the same initialize request four ways:
| Authorization header | Result |
|---|---|
| none | 401 |
| wrong value | 401 |
Bearer YOUR_SECRET | 401 |
YOUR_SECRET | 200 |
None of the 401 responses carries a WWW-Authenticate header. A client that adds Bearer by default fails with nothing to explain why. The server is also stateless, as the docs state: there is no Mcp-Session-Id in the response, and serverInfo.name is your assembly name.
3. CmsAdmins has no content rights on a stock Alloy site
The docs say client secret authentication runs as the CmsAdmins role and that this grants full access to all CMS tools. In my test that was true for the content type tools only. Every content create failed with Access denied: You do not have permission to create content in this location.
Another developer has reported the same symptom: in their setup CmsAdmins was mapped to WebAdmins, and the MCP client was still denied even though WebAdmins had Create on the Start page. So the cause may be more nuanced than one missing row.
What I found in my database: in tblContentAccess, the Root node of a fresh Alloy database grants access to Everyone, SearchIndexer and WebAdmins, with no CmsAdmins row. The fix that worked for me was to insert a CmsAdmins row on Root with access mask 63, the same as WebAdmins, and restart. Granting the role on Root in Set Access Rights should be equivalent, but I did not test that route.
4. properties is a JSON string, not an object
The tool description says in capitals that Properties must be a JSON object and not a string. The input schema the server serves says type: string, while the parameter table in the Optimizely docs lists it as an object. I followed the schema. If you send an object the server throws a JsonException and the client sees only An error occurred invoking 'paas_cms_update_content_item'. with no detail.
While I was in the tool list: version 13.4.1 exposes 20 tools. The combined names, descriptions and schemas come to about 48,000 characters, and the update_content_item description alone is 17,192 of them. At roughly four characters per token that is around 12,000 tokens of context before the agent does anything. The current docs list a larger tool set (including blueprint and display template tools), so newer package versions will likely cost more.
Writing every property type
I created a block type with paas_cms_create_content_type holding one property of each of the 19 type names the tool accepts. The error message for a bad type lists them, which is the only place I found them. The table below shows 17 of them; linkcollection (an alias, see below) and url (see the edge cases) make up the rest. Then I created one item with a value for every property. All 19 came back written. The read-back is where the differences show.
| Sent | Stored type | Read back |
|---|---|---|
| string, longstring, boolean, number, float, stringlist, integerlist, dropdown | as named | same as sent |
| integer | Number | same as sent |
datetime ...45.123Z | Date | ...45.123+00:00 |
date 2026-11-19 | Date | 2026-11-19T00:00:00+00:00 |
| xhtmlstring, richtext | XhtmlString | same as sent |
contentreference cms://content/{guid} | ContentReference | "6", the internal ID |
contentarea [{"reference": "..."}] | ContentArea | the referenced page, fully expanded |
| linkitemcollection as a JSON array | LinkCollection | an HTML <ul><li><a> string |
checkboxlist "a,g" | CheckBoxList | "a,g" |
Several type names are aliases: integer and number both become Number, date and datetime both become Date, richtext becomes XhtmlString, and linkcollection and linkitemcollection both become LinkCollection. Options on dropdown and checkbox properties must be an object mapping labels to values. An array is rejected.
The read-back shapes are the ones to plan for. A content reference you write as a URI comes back as a number. A link collection you write as an array comes back as HTML. A content area with one reference came back as about 4 KB, because the referenced page and its own blocks are expanded inline. The tool accepts the values it returns (I sent "6" and the HTML string back and both were written), so a read-modify-write loop works. Just do not expect the two shapes to match.
Edge cases: what is converted and what is rejected
I sent each case as its own call against the same draft.
| Input | Result |
|---|---|
integer 3.7 and 3.2 | written as 4 and 3 |
integer "42", boolean "true", string 123 | written, converted silently |
datetime with +05:00 | written, converted to UTC |
url "not a url" | written exactly as sent |
rich text containing \n | written with the newlines kept, despite the description saying not to send them |
integer 9999999999 | rejected |
| string of 300 characters | rejected, 255 character limit |
datetime "next tuesday" | rejected |
| dropdown or checkbox value not in Options | rejected, error lists the allowed values |
| checkboxlist as an array | rejected, it only takes a comma separated string |
onclick attribute in rich text | rejected |
javascript: URL | rejected, error points at IllegalUriSchemes |
| content reference to a GUID that does not exist | rejected |
| unknown property name | rejected |
PageURLSegment, PageStopPublish, PageVisibleInMenu | rejected as CMS metadata properties |
Two things follow. First, validation is all or nothing. I sent one valid and one invalid property in the same call and the valid one was not saved. That is why notPersisted never appeared in any of these tests. Second, the metadata rejection means an agent cannot set a stop-publish date or change a URL segment after creating a page. The only chance for the URL segment is the routeSegment on create, which the docs confirm is used only when creating. A start-publish date can still be scheduled through the publish tool.
Every edit also overwrote the same draft version, and ChangedByName in the database was MCP Client every time. With client secret auth, version history cannot tell you who or what changed a page.
Forcing notPersisted
The description says notPersisted means the property is likely computed or read-only. To produce it I added a temporary block with four string properties and a SavingContent handler that interferes with two of them.
[ContentType(DisplayName = "McpTestDiscard", GUID = "6b0f1c1e-3a52-4f0e-9d65-2f1c7a9c4e11")]
public class McpTestDiscardBlock : BlockData
{
public virtual string Normal { get; set; }
public virtual string WipedByHandler { get; set; }
public virtual string UpperCasedByHandler { get; set; }
[Editable(false)]
public virtual string NotEditable { get; set; }
}
[InitializableModule]
[ModuleDependency(typeof(EPiServer.Web.InitializationModule))]
public class McpTestDiscardModule : IInitializableModule
{
public void Initialize(InitializationEngine context)
=> context.Services.GetRequiredService<IContentEvents>().SavingContent += OnSaving;
public void Uninitialize(InitializationEngine context)
=> context.Services.GetRequiredService<IContentEvents>().SavingContent -= OnSaving;
private static void OnSaving(object sender, ContentEventArgs e)
{
if (e.Content is not McpTestDiscardBlock) return;
e.Content.Property["WipedByHandler"].Value = null;
var upper = e.Content.Property["UpperCasedByHandler"];
if (upper.Value is string s) upper.Value = s.ToUpperInvariant();
}
}
InitializationEngine.Locate is obsolete, so the handler resolves IContentEvents through context.Services. I created one item with all four properties set:
| Property | Handler | Outcome | Stored |
|---|---|---|---|
Normal | none | written | as sent |
WipedByHandler | clears value | notPersisted | empty |
UpperCasedByHandler | upper-cases value | written | MAKE ME LOUD |
NotEditable | none | written | as sent |
The response had success: false and created: true, and the message told the caller that the item was saved and must not be created again. Four details are worth knowing.
- A modified value counts as written. I sent
make me loud, the CMS storedMAKE ME LOUD, and the outcome was stillwritten. The check asks whether a value is stored, not whether it matches what you sent. The docs say the same, and name rich text normalisation and reduced date precision as other cases that still reportwritten. - The MCP envelope does not flag it. The result object had only a
contentkey, with noisError. The failure exists only inside the JSON text. A client that checks the MCP error flag will treat the call as a success. - The other properties are saved.
Normalwas stored even thoughWipedByHandlerwas not. This is the opposite of the validation errors above, where nothing is saved. The docs describe this behaviour too. - A retry creates a second item. I repeated the identical create after the
success: falseresponse. It created a second block with the same name, and the database now holds two. The message warns against this, but a client that retries onsuccess: falsewill duplicate content every time. The docs do not mention this consequence.
Sending "" or null to the wiped property returned written with success: true, as the description promises, because emptying it is what you asked for.
One more result: [Editable(false)] had no effect. The tool wrote to the property, and get_content_type_details does not report the attribute. An agent has no way to learn that a property is meant to be read-only.
What I would do in a client or agent
- Parse the JSON in the tool result and check
successyourself. Do not rely on the MCPisErrorflag. - If
createdis true, store thecontentKeybefore looking atsuccess, and switch to an update on that key. Never repeat a create. - For properties that a handler or event might change, read the item back and compare.
writtenwill not tell you the value differs. - Send integers, booleans and dates in their real types. The server converts and rounds without telling you.
- Give the agent your own rules for read-only properties, URL validity and metadata fields. The tools do not expose them.
- Keep client secret authentication to local development, and plan for a real identity (Opti ID) before anything is exposed.
Limits of these tests
- One machine, one Alloy site, client secret authentication. Opti ID authentication runs as a real user, so the access rights result will differ.
- I used a save handler rather than a custom property type to get
notPersisted. It is a realistic case but not the only one. - I did not trigger
unverified. The docs define it as the stored value not being readable after the save, and report it as a success. My guess is that it needs the read-back to fail, for example when the principal cannot read the saved item, but I have not tested that. - The package was 13.4.1 on CMS 13.5.1. A newer package may behave differently, and the tool set and descriptions have been growing.
- The access rights diagnosis is what I found in my database, not a confirmed root cause for every setup.
The test scripts are a few lines of PowerShell that post JSON-RPC to /mcp with the secret header, so every result above is easy to reproduce.