ESAI MCP
How it works

The tools and knowledge base, together.

Whether a person types a question or an agent calls a tool, every path through the ESAI MCP ends at the same consolidated Optimizely knowledge base. Here's what's running, and what each piece does.

The interaction spine

one path, four hops
Your agent / IDE→ MCP client (Claude, Copilot, Cursor)→ ESAI MCP tools→ Consolidated Opti knowledge (.acs modules)→ Grounded, cited answer

✓ Live today

The 16 live tools

reads vs. writes

Reads

ToolWhat it does
list-modulesLists the knowledge modules available to your key
get-moduleFetches a module's manifest; pass includeProfileIndex to also list every profile in it
get-module-docFetches a module's supporting doc file
get-profilesFetches one or more (1+) knowledge profiles in a single call
search-profilesFull-text keyword search across every profile's headings and body text — use when you don't already know a profile's name
list-skillsLists the skills available to your key
get-skillFetches a skill's SKILL.md. For gated skills (the upgrade, build and audit skills) it returns a short stub until a run is started; pass the runToken from record-skill-start to get the full skill. The “I’m stuck” skill, cms-upgrade-help, is never gated: it is always served, so it stays reachable even from a stub.
get-skill-fileFetches a supporting file from a skill; for gated skills pass the same runToken (a skill's token also covers the files of the companion skills it declares)
get-knowledge-versionReturns a module's (or pack's) current freshness marker
what-changedReports what changed in the knowledge base since a prior call, and which profiles are stale
list-context-packsLists the named context packs available
get-context-packResolves a named pack against the live module registry and returns its knowledge slice

Writes

ToolWhat it does
record-signalLogs a usage or feedback signal
record-skill-startStarts a skill run: pass the skill slug and your exact model ID (logged as reported, never rated or rejected). Returns the runToken that get-skill and get-skill-file need for gated skills, and opens a tracked run when a skill-run store is configured (a short-lived provisional token is issued if the store is unavailable). Not a source of the signalToken record-signal needs (that comes from get-module, get-profiles, get-module-doc, search-profiles, or get-context-pack)
record-skill-progressOptional: appends an ordered phase/step event to a run (takes the runToken, or the runId from record-skill-start for a run of your own key when your client cannot send a token; if record-skill-start returned none, skip this call). Skills do not call it by default
record-skill-endCloses a run with completed, halted or failed (takes the runToken, or the runId from record-skill-start for a run of your own key when your client cannot send a token; if record-skill-start returned none, skip this call) — a skill’s final step and every hard stop

11 more tools exist in the full registry (27 total) but aren't shown here: record-knowledge and export-knowledge are role-gated (contributor/admin); get-contributions, get-learning-status, get-skill-run, list-skill-runs, list-signals, dismiss-signal, promote-signal, ask-opal, and opal-doc-watch are internal-admin-only (denylisted here too). None of the 11 are reachable from a partner integration.

How a skill run works. Skills such as the upgrade, build and audit skills are served only after a run is started. In order: (1) get-skill on one of them returns a short stub that names the next call; (2) record-skill-start with the skill slug and your exact model ID — the model is logged as you report it and is never rated, validated or rejected, so no model is turned away; (3) get-skill again with the returned runToken returns the full skill, and every get-skill-file call carries the same runToken (a skill started from inside another passes parentRunToken; an expired token is replaced by a new run with resumeOf); (4) the skill finishes, and stops for any reason, with record-skill-end (completed, halted or failed). Outdated tool list. If your get-skill / get-skill-file tool has no runToken parameter, your MCP client is using an outdated tool list: reconnect the MCP server or connector (or start a new session) and retry. As a safety net the server still serves a gated skill that has no runToken when your API key has a run of that skill that is still running, was started within the last 24 hours (2 hours for a provisional run) and has had activity within the last 2 hours (for get-skill-file, a running run of a skill that lists this one as a companion also counts), and record-skill-progress / record-skill-end accept the runId from record-skill-start for a run of your own key. The stub itself only carries the reconnect advice above; it does not mention these fallbacks. If record-skill-start returns no runToken, this server is not enforcing telemetry: continue without one, omit runToken from later calls, and skip record-skill-end. Honest limits: the server only controls what it serves — a locally installed copy of a skill that is pure instructions never calls it and records nothing; the model ID is whatever the agent reports and is not verified; record-skill-end is measured, not enforced (a run with no end is recorded as abandoned); and attributing tool calls to a run is approximate. cms-upgrade-help (the “I’m stuck” skill) is the one upgrade skill that is never gated: it is always served, with or without a run.

Ask Opti anything

✓ Live today

optimizely-cms-expert is the steady-state expert module for Optimizely CMS, covering both the versioned PaaS CMS 13 and the versionless SaaS CMS, plus the surrounding platform — Graph, Opti ID, Forms, DAM, Visual Builder, and Opal. It doesn't run migrations; it answers "how does this work" and "is this supported" questions, and hands off to the upgrade skills when the real question turns out to be "how do I migrate."

consult-cms-expertRead-only
in: a CMS product question → out: a cited answer (profile + source + confidence), or an honest "not documented"

See the full prompt library →

Building something new

CMS coding assistant

Writes Optimizely CMS code across CMS 11–13 (PaaS) to current best practice.

See how →

SaaS coding assistant

Builds TypeScript / Next.js front-ends against Optimizely SaaS CMS, hydrated from Graph.

See how →

Integrate your own agent

Wire Claude, Copilot, Cursor, or a custom agent into the MCP's 16 live tools.

See how →

Index any codebase

Scans any stack and produces a compact, token-efficient index for AI context.

See how →