Release notes ClusterControl MCP
The ClusterControl MCP Server is versioned and released independently of the main ClusterControl components, as clustercontrol-mcp-1.0.0-N builds. This page is the running release history for the MCP Server. The initial launch (clustercontrol-mcp-1.0.0-5, May 4th, 2026) is documented in the v2.4.0 release notes.
Feature Release: An optional TLS listener, and plugin-first client setup
- Build:
- clustercontrol-mcp-1.0.0-246
This release lets the MCP Server accept clients over TLS on its own, without a reverse proxy, and makes the Claude Code and Codex plugins the recommended way to connect. An optional second listener serves the same endpoints over TLS beside the existing plain one, which keeps working unchanged, so clients that reach the server over an SSH tunnel need no change. The tools, their arguments and the resource surfaces are unchanged from 1.0.0-241.
⚠ Read before upgrading
No setting was removed or renamed.
- An
MCP_APPROVAL_BIND_ADDRESSthat overlapsMCP_BIND_ADDRESSnow stops the server at startup with exit code 78, naming both settings, instead of failing when it binds the port. Two addresses overlap when they use the same port with the same host, a wildcard host on either side, orlocalhostagainst its loopback address. - The earlier HTTP-mode setup example bound the server to
0.0.0.0and connected overhttp://, which sends the bearer token in cleartext. If you followed it, bind HTTP mode to127.0.0.1and reach it over an SSH tunnel, a TLS reverse proxy or the new TLS listener, and remove anyMCP_BASE_URLleft from that example.
- Optional TLS listener. Set
MCP_TLS_BIND_ADDRESS,MCP_TLS_CERT_FILEandMCP_TLS_KEY_FILE(or-tls-bind-address,-tls-cert-fileand-tls-key-file) to serve/mcp,/sseand/messageover TLS on a second address, with the same authentication and session checks as the plain listener. The plain listener onMCP_BIND_ADDRESSkeeps serving beside it, and TLS 1.2 is the minimum version. Set all three settings or none. The listener needsMCP_AUTH_TOKENor an identity map, does not run in stdio mode, and its address must not overlap the plain or the approval listener. The key must be a regular file owned by the user the server runs as, with no group or other permissions (chmod 0600). The certificate and key are read once at startup, so restart the server after renewing them. Each of these problems stops the server at startup with exit code 78, naming the setting. (CLUS-9344) - Plugin-first client setup. The setup instructions now start with the Claude Code and Codex plugins from the
severalnines/ai-pluginsmarketplace, which connect to the server in HTTP mode with a timeout longer than the longest approval window. Claude Code connects to/mcp(streamable HTTP) rather than/sse, which an identity map turns off. Codex gets a completeconfig.tomlentry, and the Claude Code stdio setup passes its settings as environment variables with a key file instead of a password on the command line. See Claude Code and Codex Plugins. (CLUS-9343)
- A request refused with 401 now has its connection closed after a one-second grace period for the request body, so a client that withholds the body can no longer hold connections open. The bearer token is compared in constant time. (CLUS-9344)
Feature Release: Galera health and recovery, a fleet digest, approvals from the command line and an agent activity summary
- Build:
- clustercontrol-mcp-1.0.0-241
This release brings Galera clusters into the advisors and procedures, tells you what changed across your fleet, and accounts for what an agent asked to do. A new advisor says whether a Galera cluster is whole, in sync and keeping up, and a new procedure brings back a Galera cluster whose every node is down from its most advanced node, with a person confirming each host. The fleet view adds Galera health and workload, a fleet digest reports what changed since a time you give, a daily review collects both into paste-ready text, and a summary of the server's own audit log says what the agent requested. Independent approvers can decide from the command line within an approval window you set, and the server can start from a deployment profile by name, so an upgrade brings the profile's new tools with it.
⚠ Read before upgrading
No tool, argument or setting was removed or renamed, but some calls now refuse what they used to accept, some answers change shape, and four new settings stop the server at startup on a value they do not accept. Each change is described under Behaviour changes below. Match a refusal's code, not its sentence.
MCP_PROFILE,MCP_APPROVAL_TTL,MCP_ACTIVITY_OPERATOR_IDENTITIESandMCP_GALERA_BOOTSTRAP_REQUIRE_OOBstop the server at startup with exit code 78 on a malformed value.MCP_PROFILEtakes only empty,agentic-observeoragentic-operate, andMCP_APPROVAL_TTLa duration from1mto30m.- On a Galera cluster,
create_jobrefuses the routes that let the controller choose a bootstrap donor:start_clusterwithoutjob_data,stopstart_clusterandcluster_recoveryalways, and turning automatic recovery on while a member is down.set_controller_config,kill_job,remove_maintenance_windows_by_filterand a forcedremove_clusterrefuse in that state too, when they would hand the cluster to the controller's own recovery. remove_clustermust name the same cluster incluster_idandjob_data.clusterid. A hostname argument holding a character other than ASCII letters, digits and. _ : % [ ] * -is refused, and hostname filters are no longer trimmed.set_controller_configrefuses a parameter name that is not letters, digits and underscores.get_controller_confignow lists only the parameters that differ from their default. Passchanged_only=falseandwith_descriptions=truefor the earlier output.- With
MCP_TOOL_ALLOWset, the three new tools are out of scope until you add them. A profile copied into/etc/default/cmon-mcpkeeps refusingadvise_galera_health,get_fleet_digestandlist_alarms, and anagentic-operatecopy keeps refusing thebootstrap_clusterandfind_most_advancedjob commands, until you copy the new assignments or name the profile withMCP_PROFILEinstead. - Under
out_of_band, the requesting call waits up toMCP_APPROVAL_TTLwithout progress messages, and Claude Code and Codex give up after 60 seconds by default. Raise the client's timeout above the window; see Client Timeouts. - The guided procedures that change a cluster end with one more step, a closing verdict, and a finding's list-valued evidence is cut to its first 20 items. The finding catalog moves from version 24 to 28.
- The server now contacts the controller at startup and every 15 minutes, with one unauthenticated version check.
advise_galera_health— is a Galera cluster whole, in sync and keeping up? Seven codes, each node-level finding naming its node:GALERA_SIZE_BELOW_EXPECTED,GALERA_PARTITIONandGALERA_STATE_MISMATCH(critical),GALERA_NODE_NOT_SYNCEDandGALERA_FLOW_CONTROL(warn), andGALERA_CERT_FAILURESandGALERA_DATA_UNAVAILABLE(info). It admits Percona XtraDB Cluster 8.0 and 8.4 and MariaDB Galera 10.11 and 11.4, and refuses every other engine and series withUNSUPPORTED_ENGINE. Flow control is judged from two reads 5 seconds apart, so every call takes at least 5 seconds, and certification failures count from each node's start. When every member is stopped, its finding namessop_galera_recoveryas the next action. (CLUS-9073, CLUS-9094, CLUS-9102)sop_galera_recovery— brings back a Galera cluster whose every member is down, from its most advanced node. It checks that every member reads not running and that both automatic recovery settings are off, runsfind_most_advancedand takes the donor from that job's log only, then previews and submitsbootstrap_clusterwith that donor and watches each member reach Synced, for at most 30 minutes. It stops before any preview, naminggrastate.datand wsrep-recover, when a member has no position or the log gives no verdict. The approval asks a person to confirm, host by host, that mysqld is shut down, and a submission without a confirmation for every member is refused, even when every read shows the members down.create_jobadmitsbootstrap_cluster, and a Galerastart_clusterthat carriesjob_data, only through the same checks, refusing withGALERA_BOOTSTRAP_NOT_ADMITTED. (CLUS-9074, CLUS-9103)sop_failover_drill_postgresql— the failover drill for a PostgreSQL 14 to 18POSTGRESQL_SINGLEcluster of the community vendor. It followssop_switchover_postgresql's steps and rules, but chooses the standby fromadvise_failover_readinessinstead of being given one; when more than one qualifies, the person picks in the approval step. A switch back is a second run with its own approval.sop_failover_drillnow routes PostgreSQL clusters to it. (CLUS-9076, CLUS-9107)get_fleet_digest— what changed across the clusters you can read since a time you give. It takes a requiredsince, within the last 72 hours, and reports new, cleared and current findings from the fleet view's eight advisors, with recorded alarms, failed jobs, stored package upgrades and end-of-life boundaries. New and cleared findings need a baseline: pass thenext_sincethat a completed digest returned as the next call'ssince. Baselines are held in memory only, at most eight per identity for up to 72 hours, so a restart loses them. A missing baseline, advisor or source never turns a missing finding into a cleared one, and backup misses are always reported as unknown in this release. Read every page with the samesinceand the returned cursor. (CLUS-9079)sop_daily_review— a read-only procedure that collects the fleet digest, the active alarms and the fleet view into one paste-ready summary, quoting cluster names and messages as data. It submits nothing and asks for no approval.summarize_agent_activity— what agents requested over an interval: unique calls, reads, previews, execution requests (refused ones included), outcomes, refusals and independent approval decisions, read from this server's own audit log with no controller request. It takes a requiredsinceanduntil, and optional identity, tool and cluster filters. An identity sees its own records; only the identities named inMCP_ACTIVITY_OPERATOR_IDENTITIES(empty by default) can read another identity's, or all. It reads the first 16 MiB or 100,000 records of the log, and always reports the summary as partial, because nothing proves the log's history complete. An execution request does not show that the controller changed anything. (CLUS-9080)- Capacity forecasts —
check_capacityestimates when each mount fills at its recent growth:CAPACITY_TIME_TO_FULL(warn, under 14 days),CAPACITY_FORECAST_ESTIMATE(info, 14 days or more) orCAPACITY_FORECAST_UNAVAILABLEwith the reason there is no estimate. The fit reads the last 36 hours and needs samples spanning at least 6 hours, so a newly added host has no estimate at first. The current-usage findings are unchanged. (CLUS-9081, CLUS-9176) - The fleet view runs eight advisors —
get_fleet_postureaddsadvise_galera_healthon the Galera series it admits andadvise_workloadon MySQL-family and PostgreSQL clusters, and names an advisornot_applicableon an engine it does not take. Workload data that could not be read stays visible asWORKLOAD_DATA_UNAVAILABLEand counts as unknown, never as clean. A call still has a 45-second budget, and every fleet call the server serves shares eight concurrent controller requests, at most four of them for one identity. (CLUS-9082) cmon-mcp approve— an independent approver decidesout_of_bandrequests from the command line, withlist,show,approveanddeclineand a short request id. The token comes fromMCP_APPROVER_TOKEN_FILEorMCP_APPROVER_TOKEN, never the command line, and the command talks to the loopback approval listener; from another host, forward it withssh -L. A Galera bootstrap's approval takes--confirm-shutdown <host:port>once per member. (CLUS-9067, CLUS-9074)- An approval window you set —
MCP_APPROVAL_TTL, a duration from1mto30m(default2m, the fixed window of earlier releases), applies to both approval modes and is logged at startup asapproval window:. With the execution guard on, a confirmation that admitted a call stays valid for as long as the call can wait for its approval. (CLUS-9067) - Deployment profiles by name —
MCP_PROFILE=agentic-observeorMCP_PROFILE=agentic-operate(or-profile) reads the shipped profile in place, so an upgrade brings the release's tool and job command lists with no edit. Your own settings win over the profile's, and the journal andget_session_infosay which profile is in use and which of its keys you overrode. Copying a profile into/etc/default/cmon-mcpstill works. (CLUS-9069) - Independent approval for Galera bootstraps —
MCP_GALERA_BOOTSTRAP_REQUIRE_OOB=truerefuses a Galera bootstrap under any approval mode butout_of_band, even with the execution guard off. It is off by default. (CLUS-9105) - Output controls —
list_db_users,list_alarms,list_all_alarms,list_backup_schedules,list_cluster_logs,list_nodes,list_cmon_users,list_maintenance,list_all_maintenance,list_schemasandlist_available_upgradestakelimitandcursor; without them their output is unchanged.get_fleet_posturetakescursorfor the clusters past its response cap, andget_controller_config,get_cluster_configandget_node_configtakenames, with globs. (CLUS-9068, CLUS-9088) - The controller version floor — every tool works against ClusterControl 2.3.1 and later. The server checks the controller's version at startup and every 15 minutes, journals one line when it changes, and reports it in
get_session_info. A controller below the floor is warned about, naming the tools that will fail, and never refused. (CLUS-9070) - The tool registry grows from 86 to 89 tools (60 pure-read, 26 CMON-mutating, 3 local-filesystem-writing; 22 flagged destructive), adding the three read-only tools above, and the procedure prompts grow from ten to thirteen. The 21 resource surfaces are unchanged. The finding catalog moves from version 24 to 28.
- On Galera, the routes that let the controller choose the bootstrap donor are refused.
start_clusterwith nojob_data, an empty string or an empty object,stopstart_clusterandcluster_recoveryare refused in every mode withGALERA_BOOTSTRAP_NOT_ADMITTED, namingbootstrap_clusterwith an explicitdonor_addressinstead. While any member does not read Primary and online, these are refused too:create_jobenable_recoveryandenable_node_recovery;set_controller_configturningenable_cluster_autorecoveryorenable_node_autorecoveryon;remove_maintenance_windows_by_filterending a cluster-wide window while either switch is on;kill_jobon a job that holds the cluster in maintenance, such as a restore, an upgrade or a rolling restart; and a forcedremove_clusterwhile such a job has not ended. Each refusal comes before any confirmation, approval or write, and a cluster that cannot be read refuses. A healthy cluster and other engines are unchanged. (CLUS-9101, CLUS-9176) get_controller_configlists less by default. It lists the parameters whose value differs from their default, without descriptions, and ends with a line counting what it left out.changed_only=falsewithwith_descriptions=truereturns the earlier output, and givennames,changed_onlydefaults to false. Thecontroller-configresource is unchanged. (CLUS-9068)- Four new settings refuse malformed values at startup, with exit code 78.
MCP_PROFILEis checked before the flags are parsed, so-hand-versionreport it too, and a path or file name is refused like any other unknown name.MCP_APPROVAL_TTLis checked whateverMCP_HUMAN_APPROVALis.MCP_ACTIVITY_OPERATOR_IDENTITIESrefuses wildcards, duplicates and surrounding whitespace, andMCP_GALERA_BOOTSTRAP_REQUIRE_OOBtakes the same boolean spellings asMCP_READ_ONLY. (CLUS-9067, CLUS-9069, CLUS-9080, CLUS-9105) - The server checks the controller's version. It sends one unauthenticated
/v2/infopingat startup and every 15 minutes, or every minute while the version is unknown, bounded at 5 seconds and off the startup path, so a slow or absent controller never delays startup. Earlier releases contacted the controller only to serve a call. (CLUS-9070) - The guided procedures that change a cluster end with a closing verdict. A last step names the read to run again and one of
VERDICT_SUCCESS,VERDICT_FAILUREorVERDICT_UNKNOWN, so each has one more numbered step. A client that counts steps, or treats the exit branch as the last step, must expect it. (CLUS-9075) - A finding's list-valued evidence is cut to its first 20 items, with
evidence.truncationcounting what was cut and naming the tool that lists it whole. Evidence within the cap is unchanged. (CLUS-9087) - The deployment profiles allow more. Both add
advise_galera_health,get_fleet_digestandlist_alarms, andagentic-operate's job commands addbootstrap_clusterandfind_most_advanced. Neither allowssummarize_agent_activity; add it deliberately. A host started withMCP_PROFILEgets the new lists at its next start, and a copy needs the new lines. (CLUS-9069, CLUS-9074, CLUS-9079) - Answers change shape.
get_session_infogainscontroller_versionand, on a server started from a profile,profile.get_fleet_posturenamesadvise_galera_healthandadvise_workloadamong an engine'snot_applicableadvisors, and its cursor retries clusters the time budget left incomplete. A PostgreSQL standby'sFAILOVER_READYnamessop_failover_drill_postgresql.list_jobsshows a job's recurrence, and backup-schedule lists say when the controller's 100-instance window is reached. (CLUS-9069, CLUS-9070, CLUS-9082, CLUS-9088, CLUS-9107) - Approval steps say who decides. Under
elicitation, the calling session; underout_of_band, an independent approver on the approval listener, never the requester, and a decline or an expiry parks the procedure. An independent PostgreSQL promotion request carries the procedure's advice on what to refuse to the approver. (CLUS-9106, CLUS-9110, CLUS-9111, CLUS-9170)
remove_clusterauthorizes the cluster it removes. The controller files the job under cluster 0, removesjob_data.clusteridand checks access only on the request's cluster, so a removal could name a cluster the caller cannot read. Aclusteridother thancluster_id, or one the controller would read as a different cluster, is now refused, and the preview and approval name the cluster removed. (CLUS-9176)- Names and hostnames are checked against how the controller reads them. The controller's request parser drops or rewrites some escaped characters, so a re-spelled name could be shown as one thing and acted on as another: a credential such as
wsrep_sst_authwritten while its value was shown, or a recovery switch turned on past the refusal above.set_controller_confignames must be letters, digits and underscores,set_node_configandunset_node_confignames and groups follow the controller's configuration grammar, and every hostname argument must be ASCII letters, digits and. _ : % [ ] * -. (CLUS-9176) kill_jobreads the job first. A job on a cluster the caller cannot read is answered as a missing job. (CLUS-9176)
- Finished approval requests no longer lock out independent approval. Decided and expired requests counted towards the limit on stored requests, so a burst could refuse new requests for up to two approval windows. A full table now drops the oldest finished request instead. (CLUS-9083)
- A preview nobody executed releases its slot after 10 minutes again, with the execution guard and approval on. (CLUS-9083)
- An invalid shutdown confirmation explains itself. The approval API answers 400 naming the missing, extra or duplicated nodes, and the request stays pending for a correct decision. (CLUS-9103)
- Galera health keeps what it knows. A missing unrelated key no longer erases a known partition, members without a host id are matched by hostname, and
GALERA_FLOW_CONTROLlabels senders and receivers. In the fleet view, the 5-second Galera wait releases its worker for other clusters. (CLUS-9094, CLUS-9095) - Paging and query fixes. Configuration
namespatterns are limited to 1,024 bytes each, a blanklimitreads as absent,get_fleet_posture's 50-finding cap applies after the clusters of a page are chosen, and resource queries accept a raw*, reordered parameters and a trailing&. (CLUS-9088) check_capacityforecasts over 36 hours, not 30 minutes, so a short bulk load no longer raises an hours-scaleCAPACITY_TIME_TO_FULL. (CLUS-9176)- The fleet digest no longer withholds whole advisors on a collision. SSL certificate findings are told apart by certificate kind and workload gaps by scope, and a forecast with no estimate for a decided reason no longer withholds every capacity change. (CLUS-9176)
- The HTTP transport logs its listening address only after the bind succeeds. (CLUS-9176)
- Galera health and recovery were run live on Percona XtraDB Cluster 8.4 only, with ClusterControl 2.5.1. Percona XtraDB Cluster 8.0 and MariaDB Galera 10.11 and 11.4 are admitted without a live run, and the advisor reports no SST or IST progress.
- Under
elicitation, the requester's own client answers the per-node shutdown confirmations, so the server cannot tell whether a person checked any host. Useout_of_band, and setMCP_GALERA_BOOTSTRAP_REQUIRE_OOB=trueto require it. - The controller accepts any bootstrap donor. The server's checks are the only guard, and only for calls made through it. A cluster maintenance window that expires, or a cluster-locking job that ends on its own, ends the maintenance with no call to refuse: turn both automatic recovery settings off before such a job starts or such a window ends. Concurrent bootstraps are serialised within one server process, not across two. (CLUS-9092)
- The fleet digest's history is held in memory. A restart, or eviction under its memory limits, loses a baseline, and the digest assumes rather than proves that a cluster id still names the same cluster; restart the server after pointing it at another controller. Backup misses are always unknown, and the digest was qualified over a same-day comparison, not overnight.
- The activity summary is never complete. It reads the first 16 MiB or 100,000 records of the audit log, cannot tell whether earlier rotations existed, and counts requests, not controller changes.
- The PostgreSQL failover drill was run live on PostgreSQL 16 and 17; 14, 15 and 18 are admitted without a live run. External failover managers such as Patroni are not detected; the procedure asks.
- Only the official MCP Python SDK has been shown approving over
elicitation. If your client cannot show an approval request to a person, useout_of_bandwithcmon-mcp approve. - The fleet view takes at least 5 seconds over each Galera cluster, because flow control is judged from two reads 5 seconds apart. Clusters the 45-second budget does not reach are reported as out of time and assessed on the next page.
- Packages are
x86_64only in this release.
Feature Release: Workload advice, PostgreSQL switchover, minor upgrades and guarded point-in-time recovery
- Build:
- clustercontrol-mcp-1.0.0-213
This release lets an agent go from finding a problem to recovering from it. A new advisor names what in a cluster's workload needs attention, and new procedures switch a PostgreSQL primary over to a standby, apply minor upgrades to MySQL, Galera and PostgreSQL clusters, and restore a cluster to a point in time. Every new procedure is checked by the server before anyone is asked to approve it. Point-in-time recovery always requires an approval, and can now require one from a second, independently authenticated person.
⚠ Read before upgrading
No tool, argument or setting was removed or renamed, but some calls now refuse what they used to accept, and one setting now refuses values it used to accept. Each change is described under Behaviour changes below. Match a refusal's code, not its sentence.
MCP_HUMAN_APPROVALnow accepts onlyoff,elicitation(and its earlier spellingson,enforced,1andtrue) orout_of_band. Any other value stops the server at startup, where it used to switch approval on. Check the value in/etc/default/cmon-mcpbefore upgrading.create_jobnow refuses anupgrade_clusterwhosejob_datacarries anything butclusterid(and, on PostgreSQL,upgrade_to_version), a PostgreSQL promotion of anything but a caught-up standby, a PostgreSQL rebuild that does not name a registered standby, and point-in-time recovery outside the admitted route.- With
MCP_TOOL_ALLOWset, the two new tools are out of scope until you add them. A profile copied into/etc/default/cmon-mcpkeeps refusing them, andagentic-operatecopies keep refusingrestore_backup, until you copy the new assignments. get_clusterhost lines end with a newversion=field, and the finding catalog moves from version 19 to 24.
advise_workload— what in a cluster's workload needs attention. On MySQL-family clusters it reads the controller's top query digests, its process list and its recorded long-running transactions; on PostgreSQL, the process list. Codes:QUERY_HOTSPOT(one digest holds at least 25% of the summed wait, once that sum reaches 10 seconds),QUERY_FULL_SCAN_SUSPECTED(1,000 rows examined per row sent over at least 100 executions, a heuristic),LONG_RUNNING_QUERY(30 seconds),IDLE_IN_TRANSACTION(PostgreSQL, at least 20 seconds),LOCK_WAITS_RECENT(transactions the controller recorded in the last hour),QUERY_MONITOR_DISABLEDandWORKLOAD_DATA_UNAVAILABLE. Missing, stale or partial data is never reported as clean, and only the cluster's own database nodes are judged, not its load balancers. It reports no latency percentiles or query plans, and no statement text beyond a digest's normalised pattern. (CLUS-8999)list_available_upgrades— the package upgrades the controller last found for each host of a cluster, with the age of that package check and the hosts it did not cover. These are the controller's recorded candidates; the package repositories can change before an upgrade installs them. (CLUS-9022)sop_switchover_postgresql— switches a running PostgreSQL 14 to 18 primary over to a chosen standby. It reads the standby twice, at least two minutes apart, and stops unless every standby is streaming and the chosen one is caught up, with replay not paused and a lag of at most 5 seconds. It also stops on an active maintenance window. The approval asks whether an external failover manager such as Patroni manages the hosts, which ClusterControl does not detect, and names the primary that will be stopped and the standby that will be promoted. Afterwards it checks that the old primary rejoined as a standby.sop_failover_drillnow routes PostgreSQL clusters to it. (CLUS-9000, CLUS-9021)sop_minor_upgradeandsop_minor_upgrade_postgresql— upgrade a MySQL replication or Galera cluster, or a PostgreSQL 14 to 18 cluster, to the newest minor release its package repository offers. Each stops on a topology the controller cannot upgrade this way (MYSQL_SINGLE,GROUP_REPL,POSTGRESQL_LOGICAL) and, before approval, requires a finished package check under 24 hours old. The approval says what restarts: the replication primary in place with writes refused and no switchover, and every Galera and PostgreSQL node, even with nothing to upgrade. (CLUS-9001)sop_pitr_restore— restores a cluster to a point in time from one of its own completed backups, throughrestore_backup. MySQL and Galera: Oracle MySQLMYSQL_SINGLEandREPLICATION, and healthy Percona, Codership or MariaDB Galera clusters, from physical full backups, physical incremental chains (the whole chain is checked) and complete gzip logical dumps. PostgreSQLPOSTGRESQL_SINGLE:pg_basebackup,pg_basebackupincr(PostgreSQL 17 or later),pgbackrestfull,pgbackrestincr,pgbackrestdiff,walgfullandwalgincr. The preview states the target and what the restore replaces. After approval the server checks permissions, the backup and the topology again and submits the restore once; neither a confirmation nor an approval can override a failed final check. (CLUS-9002, CLUS-9033, CLUS-9040)- Independent approval (
MCP_HUMAN_APPROVAL=out_of_band) — a destructive call waits for a decision from a separately authenticated approver whose controller user is not the requester's. Approvers answer on a separate loopback listener (MCP_APPROVAL_BIND_ADDRESS), are listed in an operator-owned file (MCP_APPROVER_MAP_FILE) by controller user and token hash, and their tokens must differ from every caller's. A request expires after two minutes. The mode requires the identity map, the digest key and the audit log, and the server does not start without them.elicitationremains available, and the packagedagentic-operateprofile keeps it. (CLUS-8997, CLUS-9002) - The tool registry grows from 84 to 86 tools (57 pure-read, 26 CMON-mutating, 3 local-filesystem-writing; 22 flagged destructive), adding the two read-only tools above, and the procedure prompts grow from six to ten. The 21 resource surfaces are unchanged. The finding catalog moves from version 19 to 24.
MCP_HUMAN_APPROVALtakes named values.offor empty turns approval off,elicitation(oron,enforced,1,true) asks the calling session as before, andout_of_bandselects independent approval. Any other value stops the server at startup withMCP_HUMAN_APPROVAL must be off, elicitation or out_of_band. (CLUS-8997)- Point-in-time recovery runs only through an admitted
restore_backup. Arestore_backupcall, the dedicated tool orcreate_job, that carriespitr,pitr_stop_time,pitr_stop_logorpitr_stop_posis checked before the preview and again before submission, and needs an approval model switched on (PITR_APPROVAL_MODEL_REQUIRED). Refused withPITR_NOT_ADMITTED: the standalonepitrcommand, other recovery options on any command, unknown keys, and a backup, method or topology outside the admitted set. Arestore_backupwith none of these keys is an ordinary restore, as before. (CLUS-9002, CLUS-9033, CLUS-9040) create_jobholdsupgrade_clusterto two shapes.job_datamay carry onlyclusteridand, onPOSTGRESQL_SINGLE,upgrade_to_versionas a bare major version. Every other key is refused, among themversion,mysql_version,mongodb_versionandserver_version, which could turn a minor upgrade into a major one. So isupgrade_clusteronMYSQL_SINGLE,GROUP_REPL, the SQL Server types,ELASTIC,CLICKHOUSEandPOSTGRESQL_LOGICAL. The check runs before the preview and again before submission. (CLUS-9001)- A PostgreSQL promotion must name a caught-up standby of the one primary.
promote_replication_slaveonPOSTGRESQL_SINGLEis refused unless it names, with an explicit port, an online standby that is streaming from the cluster's online primary with replay not paused and a lag of at most 5 seconds;forceis refused. UnderMCP_EXECUTION_GUARDthe confirmation binds both the standby and the primary the preview named. A MySQL promotion is unchanged. (CLUS-9000, CLUS-9021) - A PostgreSQL rebuild must name a registered standby and a different primary.
stage_replication_slaveonPOSTGRESQL_SINGLEchecks both roles before the preview and again before submission; a down or failed standby can still be rebuilt. Registrations of other services on different ports no longer block promotion or rebuild admission. (CLUS-9019, CLUS-9020) - The query, process and transaction tools check cluster access first.
get_top_queries,get_sql_processes,get_tx_deadlocksand the query and process resources ask for the cluster before reading, which adds one request, and refuse a cluster the identity cannot read exactly as one that does not exist. A cluster the controller holds but is not running now reads "Cluster was not found." too. (CLUS-8998) - Answers change shape.
get_clusterhost lines end withversion=<v>, orversion=unknown.FAILOVER_READY's PostgreSQL recommendation namessop_switchover_postgresql.sop_major_upgradesays this server checksupgrade_cluster's keys. (CLUS-9000, CLUS-9001) - The deployment profiles allow the new tools. Both add
advise_workloadandlist_available_upgrades.agentic-operatealso allows the dedicatedrestore_backuptool, and its job command policy addsrestore_backuptopromote_replication_slave,stage_replication_slave,upgrade_clusterandverify_backup. Copy the new assignments into/etc/default/cmon-mcpand restart. (CLUS-8999, CLUS-9002, CLUS-9022)
- A registered name can no longer add lines to tool output. Cluster names, hostnames, roles, statuses and types that hold control characters or Unicode line separators are now quoted in
get_clusterand related listings, so a crafted name cannot forge an extra line an agent would read as the server's. Ordinary text and structured JSON are unchanged. (CLUS-9023)
get_tx_deadlocksworks against ClusterControl 2.5.0. The controller refused its request, which carried no offset; the request now always carriesoffset: 0. (CLUS-9004)- PostgreSQL sessions show their real process id, user, database, node and time.
get_sql_processesreturned a process id of 0 and empty fields for every PostgreSQL session, so a session could not be identified or ended. (CLUS-9005) - One unrelated host entry no longer blocks a promotion or rebuild. A registration with a port above 65535, or of another service on a different port, made the whole cluster refuse. (CLUS-9019)
- Point-in-time recovery is admitted more widely than it was run live. Live runs on ClusterControl 2.5.0 covered PostgreSQL 18 native full backups with local WAL, and physical full, physical incremental and logical restores on Oracle MySQL 8.4 replication and MariaDB 10.11 Galera. pgBackRest, WAL-G, native PostgreSQL incrementals, other timezones and timelines, and MySQL positional, encrypted, cloud and streaming cases are admitted without a live run.
- On MySQL and Galera, check the restored data, not only the job's state. A finished restore job does not by itself show that the data reached the target time. Before resuming writes, check on every member that rows written before the target are present and rows written after it are absent; the procedure's verify step does this, and it stops before the preview when it cannot confirm the backup and binary logs it will replay.
- A PostgreSQL point-in-time recovery can finish after falling back to ordinary recovery. Native recovery, a local pgBackRest repository and WAL-G can replay all available WAL when the target cannot be reached, so a finished job does not show the requested point was reached; the procedure reports the job, any fallback and the data separately.
- Checks and approvals apply to jobs the MCP Server submits. The ClusterControl GUI, the s9s CLI and other clients do not pass through them, and a preview binds the backup's catalog record and the topology, not the backup's bytes.
- An approval proves who answered, not that a person read the request.
elicitationshows that the requesting session answered;out_of_bandthat a different authenticated user decided. Neither stops an operator from giving one agent both credentials. - A switchover judges the controller's last sample. The server checks the standby's last reading before the preview and again just before submission, but the standby can fall behind after that, and the controller itself does not check it. (CLUS-9025)
- On Debian and Ubuntu, a MySQL replication minor upgrade can restart a server once more while the packages install, before ClusterControl restarts it. The approval says so. (CLUS-9024)
advise_workloadhas no PostgreSQL query digests or lock waits, which it reports asWORKLOAD_DATA_UNAVAILABLE, andget_fleet_posturedoes not run it.- Packages are
x86_64only in this release.
Feature Release: Guided remediation — a fleet view, recovery procedures and PostgreSQL coverage
- Build:
- clustercontrol-mcp-1.0.0-194
Where the previous feature release let the server advise, this one helps act on the advice. Findings now
name their cluster and what to run next, a fleet view ranks what needs attention across every cluster you
can read, and four new procedures rebuild a broken MySQL replica or PostgreSQL standby and prove that a
backup restores. Every new tool is read-only: a procedure changes a cluster only through create_job,
which now checks a job before anyone is asked to approve it and can be limited to the job commands you
allow.
⚠ Read before upgrading
No tool, argument or setting was removed or renamed, but some calls now refuse what they used to accept and some answers change shape. Each change is described under Behaviour changes below. Match a refusal's code, not its sentence.
- With
MCP_TOOL_ALLOWset, the four new tools are out of scope until you add them. WithMCP_TOOL_DENYkeeping backup data or controller settings from an agent, also denyadvise_backup_posture,advise_failover_readinessandget_fleet_posture, which read them. create_jobnow refuses a job on a cluster where the identity lacks read and execute access, ajob_datathat is not one JSON object with unique keys, thecreate_maintenancecommand, a replica rebuild aimed at a primary, and a verification of a backup the cluster does not own.- The maintenance tools require write access to the cluster, in the
dry_run=truepreview too. - Every finding gains
cluster_idand may carrynext_action, andcatalog_versionmoves from 7 to 19. list_backupsrows end with averified:field, and IPv6 endpoints are written[address]:port.
- Findings name their cluster and what to run next — every advisor finding carries
cluster_id, and a finding code can name anext_action: a read-only tool or a procedure prompt, with its arguments filled in from the finding.REPL_LINK_DOWNnames the rebuild procedure for its engine,BACKUP_NOT_VERIFIEDnamessop_backup_verify, andBACKUP_LAST_FAILEDnamesget_job_logfor the job that ran the failed backup. (CLUS-8816, CLUS-8817, CLUS-8818, CLUS-8819, CLUS-8894) get_fleet_posture— which clusters need attention first, and why. It runs six advisors (replication, failover readiness, backups, SSL, release end of life and disk capacity) over every cluster this identity can read, and returns theirwarnandcriticalfindings ranked, the worst cluster first, with per-clustercritical,warnandunknowncounts. A cluster whose data could not be read or is stale counts as unknown, never as clean. A call has a 45-second budget and returns at most 50 findings, and its text is held within 64 KiB by cutting whole clusters from the bottom;completeandtruncationsay what was cut. A cluster this identity cannot read is not listed. (CLUS-8821, CLUS-8962)advise_backup_posture— will the backup restore, and is the recovery point met? For any engine:BACKUP_NONE,BACKUP_LAST_FAILED,BACKUP_VERIFICATION_FAILED,BACKUP_NOT_VERIFIED,BACKUP_STALE(no restorable backup in 26 hours),BACKUP_ON_DB_HOST,BACKUP_NO_SCHEDULE,BACKUP_SCHEDULE_PAUSEDandBACKUP_OK. A backup counts as restorable only when it completed and has a storage location, and a location the controller did not report is treated as unknown, never as empty. (CLUS-8817)advise_failover_readiness— if the primary died now, could ClusterControl fail over, and to which replica or standby? It judges Oracle MySQL and Percona replication clusters, and PostgreSQL 14 to 18POSTGRESQL_SINGLEclusters of the community vendor, against the controller's own election rules for each engine:FAILOVER_READY,FAILOVER_CANDIDATE_BLOCKEDwith the first failing rule,FAILOVER_READINESS_UNKNOWN,NO_FAILOVER_CANDIDATE(critical) andFAILOVER_AUTORECOVERY_OFF. On PostgreSQL the summary names the projected winner, the ready standby furthest ahead in replay. MariaDB is refused withUNSUPPORTED_ENGINE. (CLUS-8820, CLUS-8892)check_capacity— which database host fills up first. It judges each database host on its fullest mount's newest disk sample against the controller'sdiskspace_warninganddiskspace_criticalsettings, or the defaults of 80% and 90% when those cannot be read, and says which it used:DISK_USAGE_CRITICAL,DISK_USAGE_WARNING,DISK_USAGE_OK,CAPACITY_DATA_STALE(a sample older than three collection intervals) andCAPACITY_DATA_UNAVAILABLE. Stale, missing or malformed data is never reported as clean. (CLUS-8823, CLUS-8962)check_version_eolassesses community PostgreSQL — by major version, against the single community end-of-support date of each major from 9.6 to 18. PostgreSQL 14 readsMAINTENANCE_ENDING_SOONthrough November 12th, 2026, andVERSION_EOLafter it. PostgreSQL takes no support entitlement, and EnterpriseDB and distribution-packaged builds are still not assessed. The bundled lifecycle table grows from 30 to 40 releases. (CLUS-8957)sop_rebuild_replica— rebuilds a MySQL-family replica whose replication link is down with SQL error 1062 or 1032, or IO error 1236. Each procedure in this release previews before it acts, asks for approval, and carries one branch for an operation nobody approved and another for a failure part-way through. This one stops on the primary, an intermediate primary, an IPv6 host or an active maintenance window. (CLUS-8818, CLUS-8816)sop_rebuild_standby— rebuilds a PostgreSQL 14 to 18 standby that cannot follow its primary. Before advising that a down standby be started, it reads that standby's own rebuild history. The controller keeps a standby's last replication positions even after a failed rebuild has erased its data directory, so the procedure hands the standby to a person when that history shows an erase, shows a rebuild still running, or cannot be read in full. (CLUS-8894, CLUS-8900, CLUS-8961)sop_backup_verify— proves a MySQL-family backup restores, onto a spare host that a person chooses. It admits only the backupadvise_backup_posturenames, stops on a spare that belongs to a visible cluster or is the controller, and reads the outcome from the job's final state. (CLUS-8819, CLUS-8902, CLUS-8906)sop_backup_verify_postgresql— the same for PostgreSQL 14 to 18pg_basebackupandpgdumpallbackups. Its approval step states that ClusterControl turns the cluster's automatic failover and node recovery off while it restores the backup, and what the spare host is left with. (CLUS-8893)- A job command policy (
MCP_JOB_COMMAND_ALLOW,MCP_JOB_COMMAND_DENY, or the-job-command-allowand-job-command-denyflags) — names the job commands thatcreate_joband the dedicated job tools may submit; deny wins, and unset changes nothing. A refused command answersJOB_COMMAND_NOT_PERMITTEDbefore any preview or approval request. It is checked again before submission, and a tool that submits one fixed command is hidden when that command is not permitted.get_session_inforeports the effective policy asjob_command_policy. (CLUS-8956) - Two deployment profiles for agents —
agentic-observe(read-only, audit on, an allow list) andagentic-operate(audit on, the execution guard enforced, approval over elicitation, no export directory, the same allow list pluscreate_job, and a job command policy of the four commands its procedures submit). They are installed as/usr/share/cmon-mcp/profiles/agentic-observe.envandagentic-operate.env, and nothing reads them in place: copy the assignments into/etc/default/cmon-mcp, and copy them again after an upgrade that changes them.agentic-operateneeds the HTTP transport and an identity map. (CLUS-8822, CLUS-8829, CLUS-8956) - The tool registry grows from 80 to 84 tools (55 pure-read, 26 CMON-mutating, 3 local-filesystem-writing; 22 flagged destructive), adding the four read-only tools above, and the procedure prompts grow from two to six. The 21 resource surfaces are unchanged. The finding catalog moves from version 7 to 19.
create_jobchecks a job before anyone is asked to approve it. Admission freezes the call's arguments and requires read and execute access (randx) on the cluster before any preview, confirmation or approval request. It runs again on the frozen arguments just before the job is submitted, so a privilege removed while a person was deciding still stops the job. (CLUS-8883)create_jobacceptsjob_dataonly as a string holding one JSON object with unique, printable keys; an empty string still omits it. Ajob_datasent as an object, array, number,nullor bool used to be dropped, so the job ran without it, and a repeated key was sent with its last value. The refusal names the key at fault, in thedry_run=truepreview too. (CLUS-8819)- Replica rebuilds and backup verifications are checked against the cluster. A
stage_replication_slavejob must name a replica as its target and a source in the same cluster, with explicit ports and the right roles. A primary, writable or read-only, or an intermediate primary as the target is refused before the preview. A backup verification requires a backup the named cluster owns, and refuses an ambiguous selector or a file path with no backup record. (CLUS-8884, CLUS-8926) - The maintenance tools require write access, and
create_jobrefusescreate_maintenance.add_maintenance_window,remove_maintenance_windowandremove_maintenance_windows_by_filterrefuse, in the preview as on execution, unless the identity holdswon the cluster and on every readable cluster that lists the host as its own. They also refuse the controller's host and Prometheus hosts.create_jobrefuses thecreate_maintenancecommand and points toadd_maintenance_window.list_all_maintenanceshows only the windows of clusters this identity can read, by cluster id or by a host's hostname or IP, andlist_maintenanceheads a cluster-wide windowcluster #<id>. (CLUS-8827) - More tools confirm the identity can read the cluster before answering. These are
list_maintenance,get_db_growth, the cluster maintenance resource,get_job_log,get_job_checkpoint, and thecheck_no_primary_keys,check_redundant_indexesandcheck_myisam_tablesadvisors. A cluster the identity cannot read gets the controller's own refusal, and a job of such a cluster is answered as not found. (CLUS-8816, CLUS-8827, CLUS-8832) - The MySQL procedures cover the MySQL family.
sop_rebuild_replica,sop_backup_verifyandsop_failover_drillcontinue on aMYSQL_SINGLEorREPLICATIONcluster of vendororacle,perconaormariadb, with no version gate, and stop on anything else; Galera is not covered.sop_failover_drillnow opens with an eligibility step and stops aMYSQL_SINGLEcluster before approval. (CLUS-8907, CLUS-8911) - The approval tier says what it checks. It accepts an answer from the calling session that carries the approval code it sent. The startup lines, the
HUMAN_APPROVAL_REQUIREDandHUMAN_APPROVAL_UNAVAILABLErefusals and the procedures no longer say the call is put to a person. Every refusal still begins with its code; the text after the code has changed. (CLUS-8887) - Answers change shape.
REPL_LINK_DOWNevidence carries the host'shostname,portandengine, and a PostgreSQL standby's finding namessop_rebuild_standbyinstead of the MySQL procedure.list_backupsrows end withverified: <status> <time>, orverified: unknown.get_session_infogainsidentity_noteandjob_command_policy. Every findings tool's description now opens with the question it answers. (CLUS-8818, CLUS-8819, CLUS-8821, CLUS-8882, CLUS-8894, CLUS-8956) NO_FAILOVER_CANDIDATEis now emitted, byadvise_failover_readinessatcritical. Previously it was catalogued underadvise_replication_topologyand never emitted, so a client filtering on a finding's tool or severity sees it move. (CLUS-8820)- A down PostgreSQL standby with no upstream is now named in
advise_replication_topology's summary, whose replica count now reads "with a reported upstream". (CLUS-8901)
- The approval prompt shows a job's
job_datakey by key. It used to be one string cut at 96 bytes, so the end of a longjob_datacould be submitted without being shown to the approver. Each value is now cut on its own, and credential-named keys holding a string or a composite value are redacted. Numbers are shown and sent exactly as written:9007199254740993used to be sent as9007199254740992. (CLUS-8819) - A major-upgrade preview carries the high-risk warning.
upgrade_clusterwas missing from the commands whose preview warns, although a major upgrade stops and unregisters the primary and cannot be rolled back once started.verify_backupnow previews with the warning too, because a MySQL verification replaces the MySQL software on the host it names. (CLUS-8746, CLUS-8819) - A procedure's
hostnamemust name its host literally. IPv4 in any but canonical form (192.168.139.010,3232271112,0xc0.0xa8.0x8b.0x4f) is refused, because a resolver reads those as a different host than the text says. Loopback addresses and names are refused too. (CLUS-8819)
create_backup_scheduleaccepts a plain cron line. The recurrence was sent with a prefix the controller read as part of the minute field, so0 2 * * *was refused with "Failed to parse recurrence." It is now sent as written, and a line with noTZ=token runs in UTC. Both schedule tools now check the line before the preview, and refuse a line the controller would run at other times than written, naming the field at fault. (CLUS-8882)update_backup_scheduleno longer loses the schedule it replaces. It deleted the old schedule before creating the new one, so a replacement the controller refused left no schedule at all. It now creates the replacement first, and refuses ajob_idthat is not one of the named cluster's schedules. (CLUS-8882)get_session_infowithout an identity map no longer reads as "not connected". The newidentity_notesays that every call runs as the server's configured user. (CLUS-8882)audit_db_privilegesno longer audits MariaDB's built-inmariadb.sys@localhostaccount. (CLUS-8882)- A reply the controller sends while it is stopping is an error, not an empty success. Every tool read it as a successful reply with no data — no windows, no rows, a "report" holding the reply. It now reports
cmon: cmon is stopping. (requestStatus ObjectNotFound). (CLUS-8858) check_ssl_postureno longer fails on a host listed twice, which dropped the request over HTTP and ended the server process over stdio. A cluster listing the controller does not answerOkis now an error, rather than an empty or partial list. (CLUS-8821)- IPv6 endpoints are written
[2001:db8::5]:3306. They were written2001:db8::5:3306, which is itself a valid, different address, inget_cluster,list_nodes,get_cluster_topology, the replication and SSL advisors and the incident bundle. (CLUS-8818) advise_replication_topologyno longer fails on a node with no hostname. It names the node by role and port, and still counts it, so it raises no falseSINGLE_NODE_PRIMARY. (CLUS-8818)- Backup-verification spares and upgrade candidates are no longer judged as database nodes.
check_ssl_posture,advise_replication_topologyandcheck_version_eolraised SSL findings for them, counted them as a second node, and listed them among the hosts. (CLUS-8828) sop_failover_drillcan no longer promote twice after a timed-out submit. It looked for the job in one default page oflist_jobsand, finding none, submitted again. It now asks for at least 200 jobs, goes on only with exactly one match, and stops for a person otherwise. (CLUS-8816)
- The approval tier cannot see a person. It checks an answer from the calling session carrying the approval code, which is a person's decision only if the client shows the request to a person the agent cannot answer for. So far only the Python SDK with an
elicitation_callbackhas been shown approving. - Admitted is wider than qualified. The MySQL procedures were run end to end against a live controller on Oracle MySQL 8.0 and 8.4
REPLICATIONclusters only (CLUS-8958). Percona Server, MariaDB,MYSQL_SINGLE, the failover drill and the major upgrade are admitted without that run. The PostgreSQL procedures and the PostgreSQL failover judgement were run on PostgreSQL 18 only, and thepgdumpallverification loop has not been run through the server. - Admission, ownership and command-policy checks apply to jobs the MCP Server submits.
- A command policy governs job submission, not effects.
set_controller_config,set_node_config,unset_node_configandadd_maintenance_windowreach the same effects as some job commands through other requests. Scope those tools too, or prefer the allow list; the server names each such case at startup. advise_failover_readinessdescribes ClusterControl-managed failover only. It does not consider Patroni. It judges no MariaDB,MYSQL_SINGLEorPOSTGRESQL_LOGICALcluster, and refuses IPv6 entries in a failover list. It says so, rather than reading a maintenance window as protection, because ClusterControl 2.5.0 fails a PostgreSQL primary over during maintenance.get_fleet_posturehas no cursor. Past 64 KiB of text the least pressing clusters are counted but not listed; call an advisor on one of them for its findings.check_capacityjudges every mount, whether or not it holds the data directory. It measures sample age on the MCP server's clock, and predicts no time until full.advise_backup_posturejudges one page of schedules, at most 100 scheduled jobs of every command, and the controller can answer a failed backup read as an empty list. (CLUS-8830)- A verification leaves files on the spare host. A PostgreSQL spare keeps a
wal_archivedirectory, which a person removes, and a backup kept only in cloud storage is downloaded to the spare. - A failed standby rebuild does not always drop the standby's upstream. On ClusterControl 2.5.0 it has been seen both ways, and the advisor and
sop_rebuild_standbyhandle both. - The scope-overlap warning over-names. Denying one of the newly access-checked tools warns that some twenty cluster tools reach the same data, which they do not. The warning errs towards naming too much, never too little.
- Packages are
x86_64only in this release.
Maintenance Release: September 30th, 2026
- Build:
- clustercontrol-mcp-1.0.0-124
This release fixes how the server reads backup records, so the backup tools list real backups again. The tools, their arguments and the server's settings are unchanged from 1.0.0-122.
- Backups are listed with their real id, method, status, timestamps and size again.
list_backups,get_latest_backupand theclustercontrol://clusters/{cluster_id}/backupsresource showed a backup that exists as#0with a size of0 Band no method, status or timestamps, so a restore or a delete could not be pointed at a real backup id. The server asks the controller for version-2 backup records, which the controller returns nested undermetadata, but it read them in the older flat shape. It now reads both shapes, and the output format is unchanged. Every earlier build was affected, against ClusterControl 2.4.0 and 2.5.0 controllers alike. (CLUS-8812)
Feature Release: Advisors that report findings, and Terraform export
- Build:
- clustercontrol-mcp-1.0.0-122
Where the previous release made the server safe to operate, this one lets it advise. Six new tools inspect a cluster and report what is wrong or risky — as machine-readable findings a client can act on, not prose — and an existing cluster can now be exported as Terraform. Every new tool is read-only, so read-only mode, tool scoping and the audit log apply to them exactly as to any other read tool.
⚠ Read before upgrading
No tool, argument or setting was removed or renamed. Three changes can still affect a client that parses output strictly; all three are described under Behaviour changes below.
lag=0sbecomeslag=unknownin topology and incident-bundle text wherever the controller reported no lag.- Cluster host JSON gains keys.
- With
MCP_TOOL_ALLOWset, the six new tools are out of scope until you add them.
- One findings contract for every advisor — each advisor returns
{findings, summary, catalog_version}, both asstructuredContentwith a publishedoutputSchemaand as the same JSON in the text content, so a client can key on a finding'scodeinstead of parsing prose. Codes, severities (info,warn,critical), recommendations and thresholds come from a versioned catalog that ships inside the binary (version 7), so changing a threshold is a catalog version bump rather than a silent change in behaviour. A healthy cluster produces nowarnorcriticalfindings. (CLUS-8116) advise_replication_topology— broken replication links (REPL_LINK_DOWN), replicas more than 60 seconds behind (REPL_LAG_HIGH), and a cluster with a single database node (SINGLE_NODE_PRIMARY). MySQL replication and PostgreSQL streaming replication are each judged by their own model, and an unknown lag is reported as unknown, never as zero. (CLUS-8113)audit_db_privileges— accounts holding every global privilege (PRIV_GLOBAL_ALL), accounts that accept connections from any host (PRIV_WILDCARD_HOST), and more than three superuser accounts (PRIV_SUPERUSER_COUNT_HIGH), on MySQL-family and PostgreSQL clusters. System accounts are excluded. (CLUS-8116)check_config_drift— a configuration parameter whose value differs between nodes of the same role (CONFIG_DRIFT), with each node's value and the node that is off the majority. Parameters that differ per node by design —server_id, addresses, paths — are never compared. (CLUS-8117)check_ssl_posture— SSL turned off on a database host (SSL_DISABLED), and the state of each of the cluster's certificates from ClusterControl's own CA: revoked, expired, expiring within 30 days, valid, or unknown. On MySQL-family hosts it asks the database server itself whether TLS is available rather than trusting the controller's flag alone — see Bug fixes. (CLUS-8115, CLUS-8762)check_version_eol— whether each database release is supported, ending within 90 days, past community maintenance, or end of life, resolved per engine against your support entitlement. The lifecycle table covers 30 releases of MySQL, MariaDB and MongoDB, ships inside the package and is never fetched, so the check works in an air-gapped installation; every result carries the table's date so its age is visible. (CLUS-8118, CLUS-8767)- Support entitlement settings (
MCP_SUPPORT_ENTITLEMENT,MCP_EOL_TABLE_FILE) — read only bycheck_version_eol, and both unset by default. The entitlement is given per engine and optionally per cluster, for examplemysql=premier,mariadb=community,cluster:7=extended; unset means each engine's free community stream. The table file replaces the bundled lifecycle table, for testing or to carry newer dates before the next release. Both fail fast: a value the engine does not accept, or a table file that cannot be read, stops the server at startup with an error naming the entry. (CLUS-8118) export_terraform— an existing cluster as Terraform HCL for theseveralnines/clustercontrolprovider v0.2.25, returned in the tool result; the server writes no file. Credentials appear only asvar.*variables. MySQL replication, Galera and PostgreSQL replication clusters are exported; an engine or layout the provider cannot express is refused withEXPORT_UNSUPPORTED_ENGINEorEXPORT_UNSUPPORTED_TOPOLOGYrather than exported as a different cluster. (CLUS-8119)- The documentation bundle that
search_docsserves offline is refreshed from the current ClusterControl documentation. (CLUS-8769) - The tool registry grows from 74 to 80 tools (51 pure-read, 26 CMON-mutating, 3 local-filesystem-writing; 22 flagged destructive), adding the six read-only tools above. The 21 resource surfaces are unchanged.
lag=0sbecomeslag=unknowninget_cluster_topologyandget_incident_bundletext wherever the controller reported no lag, and the topology view gains alag_unknownfield. Anything that readlag=0sas "caught up" was being told something the controller never said. (CLUS-8113)- Cluster host JSON gains keys where the controller reports them:
version,hostname_data,hostname_internal,ip,synchronous,sync_state, and the replication link status with its IO/SQL error numbers and states. A client that rejects unknown keys needs to accept them. (CLUS-8113, CLUS-8119) - With
MCP_TOOL_ALLOWset, the new tools are out of scope until they are added to the list. That is the scope working as designed. - The configuration readers hide more parameters — every parameter whose name contains
conninfois now hidden. See Security fixes. (CLUS-8766)
- The configuration readers no longer return replication credentials in clear text.
get_node_config,get_cluster_configand the configuration resource returned thewsrep-provider-optionsandloose-wsrep-provider-optionsspellings, and PostgreSQLprimary_conninfo, unmasked — values that can carry a replication password. Parameter names are now normalised before the masking decision, and every name containingconninfois hidden, which deliberately also hides some non-secret parameters. (CLUS-8766)
set_node_configworks on MySQL-family clusters. It sent no configuration group, so outside CCX mode the controller rejected the change with "Group is missing.", andunset_node_confignamed no section ofmy.cnf. Both tools now take an optionalgroup; when it is omitted, a MySQL, Galera or Group Replication node getsmysqldand any other node gets none. (CLUS-8760)check_ssl_postureno longer reports SSL enabled on a MySQL-family server that refuses TLS. The controller derives its SSL flag fromtls_version, which lists protocols even when the server cannot negotiate TLS; this was reproduced on MySQL 8.0, MySQL 8.4 and MariaDB 11.4. Where the controller reports a MySQL-family host enabled, the tool now reads the server's ownhave_ssl, or on MySQL 8.4 whether a certificate is loaded, and reportsSSL_DISABLEDwhen the server says TLS is off. The check only ever turns enabled into disabled; a host that does not answer keeps the controller's flag and is named in the summary. (CLUS-8762)- Reading a PostgreSQL cluster no longer fails on an unusual lag value. A replication lag reported as
"--"or as a fraction broke the whole cluster read for every tool, and an empty lag no longer reads as0. (CLUS-8113)
- The advisors read the controller's sampled state. The replication advisor sees the controller's last sample, taken about every 10 seconds by default, and
REPL_LAG_HIGHuses its own 60-second threshold, separate from the controller'smax_replication_lagalarm. Galera is judged for redundancy only:REPL_LINK_DOWNandREPL_LAG_HIGHare never raised on a Galera cluster, and the summary says so. - Two replication codes are reserved but never emitted.
NO_FAILOVER_CANDIDATEandREPL_MONITOR_GRANT_MISSINGare in the catalog, but the controller exposes no clean source for either, so promotability and the monitoring account's grants are not assessed. check_config_driftcompares configuration files, not running servers. A parameter changed withSET GLOBAL, or a file edited but not reloaded, is not seen as the server has it, and memory-sized settings legitimately differ between nodes on different hardware. Hidden parameters are never compared.check_version_eolassesses database nodes, never the controller, and covers 30 releases. PostgreSQL, Percona, Redis/Valkey, SQL Server, and releases the table does not list returnEOL_DATA_UNAVAILABLE. The table's dates change only with a new package. Oracle Sustaining Support does not count as supported, so MySQL 8.0 readsVERSION_EOLeven undermysql=extended.audit_db_privilegesis literal. A stock MySQL cluster always reportsPRIV_GLOBAL_ALL, and because accounts are counted peruser@hostit can exceed the superuser limit. A single-node MySQL cluster is refused, because the controller does not list its accounts; PostgreSQL host rules are not assessed forPRIV_WILDCARD_HOST; and privileges held only through a granted role, and dynamic privileges, are not seen.check_ssl_posturereads certificate expiry from ClusterControl's CA, so a certificate it did not issue or import is reportedSSL_CERT_EXPIRY_UNKNOWN.export_terraformdescribes how to recreate a cluster, not how to manage it. The provider cannot import an existing cluster, soterraform planagainst an export is never a no-op; applying it against a different controller deploys onto the same hosts, even while they run this cluster; and the Terraform state holds the passwords you supply in plaintext. ClickHouse clusters and load balancers are not exported. No export from this release has been applied against a controller.- ClickHouse is not covered by the advisors in this release.
- Packages are
x86_64only in this release.
Feature Release: Per-session identity, a confirmation step, and job forensics
- Build:
- clustercontrol-mcp-1.0.0-108
Where the previous release let the server refuse actions, this one lets it tell two callers apart. Each assistant can now hold its own CMON identity, a destructive call can be made to require a confirmation — or a person — before it runs, and a failed job can be asked what it was doing when it stopped.
⚠ Breaking changes
Three changes alter behaviour a working deployment may depend on. All three are described under Behaviour changes below.
- On the HTTP transport, session IDs the server did not issue are now refused, and outstanding IDs do not survive a restart. Two instances behind a load balancer need sticky routing.
create_jobnow refuses a command that is not in this build's catalogue.get_node_configandget_controller_confighide more parameters than before.
- Per-session identity (
MCP_IDENTITY_MAP_FILE) — an operator-owned map binds each bearer token to its own CMON username and credential, so the controller's audit log attributes each assistant's actions to a different user. A token that is not in the map resolves to nothing: there is no default entry and no fall back to the shared credentials, so an unmapped token is refused rather than arriving as somebody else. A map that does not parse, or that is ambiguous, is a startup error rather than a server that silently dropped an entry. The map requires the HTTP transport — identity rides on theAuthorizationheader, and selecting a map on stdio is a startup refusal. (CLUS-8102, CLUS-8646) get_session_infonow reports whether that identity actually works. It returns one ofno_identity_bound,not_attempted,verifiedorfailed, plusidentity_last_errorcarrying the controller's own sentence when it refused. Previously the tool reported the configured name and nothing else, so a map naming a CMON user that does not exist looked healthy until the first call failed. Credentials are still not probed at startup — the verdict is what CMON answered on a call the server has already made. (CLUS-8738)- Two-step execution guard (
MCP_EXECUTION_GUARD=enforced) — a destructive call is admitted only against aconfirmation_tokenthe server minted on a preview of the same operation. The confirmation covers one identity, one session, one tool and one set of arguments; it is single-use, it expires, and a restart revokes every outstanding one. A preview is never refused, and is where the confirmation comes from. (CLUS-8108) - Human-approval tier (
MCP_HUMAN_APPROVAL=elicitation) — above the guard, and usable on its own. A destructive execution is put to a person over the calling session's elicitation channel, carrying the operation's digest and a single-use code the answer must return. Where an approval cannot be sought at all — no bound identity, or a session that cannot be elicited — the call is refused withHUMAN_APPROVAL_UNAVAILABLErather than proceeding or hanging. (CLUS-8108) - Standard operating procedure prompts —
sop_failover_drillandsop_major_upgrade, served as MCP prompts. Each previews before it acts and carries an explicit branch for a failure part-way through.sop_major_upgradeopens with an engine guard (PostgreSQL only) and a backup check;sop_failover_drillopens with a preflight. Both name a human-approval step, which this server enforces only whenMCP_HUMAN_APPROVALis on — it says so at startup when it is not. (CLUS-8109, CLUS-8110) get_job_checkpoint— where one job actually got to: its command, status, whether this build recognises that status at all, and the tail of its log. Fetched by job ID alone, so a job older than one page oflist_jobsis still answered for. It never suggests re-submitting a job: CMON jobs are not idempotent, so every hint it gives is a query or a wait. (CLUS-8111)get_incident_bundlecan be anchored on a job. Passingjob_idadds afailed_jobsection and widens the jobs window to reach that job — never narrowing it below what you asked for. Only the jobs section is job-scoped, and the other sections say why they cannot be. (CLUS-8112)- Client capability probe — the server records what each client declared at connection time and consults it when a control needs to reach a person, so an approval-required call is refused on a session that cannot be elicited rather than waiting for an answer that cannot arrive. (CLUS-8107)
- The tool registry grows from 72 to 74 tools (45 pure-read, 26 CMON-mutating, 3 local-filesystem-writing; 22 flagged destructive), adding
get_session_infoandget_job_checkpoint. The 21 resource surfaces are unchanged.
- Session IDs are validated for issuance. On the HTTP transport the server now admits only the
Mcp-Session-Idvalues it issued, where previously any correctly shaped value was served. Two consequences: outstanding IDs do not survive a restart, so clients get404and must re-initialize; and two server instances require sticky routing for a session's full lifetime, because a session established against one is not known to the other. (CLUS-8646) - With an identity map configured,
/sseand/messageare not served. SSE's separate session mechanism sits outside the identity binding, so it is refused rather than left as a way around it. Deployments using SSE should stay on the shared-token configuration until their clients speak the streamable HTTP transport. (CLUS-8102) create_jobrefuses a command outside this build's catalogue. Previously such a call was accepted and reported a job ID — CMON creates a job titledUnknown Command, runs nothing and fails it — so a caller was told work had started that never would. The catalogue is a snapshot taken from the controller source at build time, so a command added by a newer controller is also refused; the refusal says the command is not in this build's catalogue, and never that it is not a real CMON command. (CLUS-8736)get_node_configandget_controller_confighide more parameters. The rule that decides what counts as a credential is now shared with the approval prompt and matcheskeyandauthas substrings, so operational parameters whose names contain them —key_buffer_size,foreign_key_checks,authentication_policyand similar — are now returned as<hidden>. This over-matching is deliberate: the alternative is a hand-maintained exemption list whose failure mode is disclosure. (CLUS-8740)
- Task status notifications no longer reach every connected client. A background job's progress was broadcast to all sessions, so one assistant could observe another's activity. Notifications are now scoped per session when an identity map is configured; without a map every caller is the same CMON principal, which is the pre-existing behaviour. (CLUS-8737)
get_node_configno longer returns credentials verbatim.wsrep_sst_authcarriessstuser:<password>and matched none of the previous rules, so Galera SST credentials were returned in clear text. The read path is now no wider than the approval prompt, from one shared list. (CLUS-8740)- The destructive-operation warning now fires for the commands it names. Four of the nine job commands it escalated on were names CMON does not accept —
shutdown,remove_node,drop_clusterandrebuild_replication_slave— so the extra warning could never appear for stopping or removing a cluster. The same fabricated names appeared in the operator-facing scope warning. Both are corrected against the controller's own command list. (CLUS-8736, CLUS-8741) - A tool declaring that it writes to the filesystem can no longer bypass the export directory. The build-time check enforced only that a tool declaring no local writes made none; a tool declaring the opposite could call the filesystem directly. Both directions are now enforced. (CLUS-8707)
- A non-credential refusal is recorded as a credential failure.
identity_verificationreadsfailedwhenever the controller answersAccessDenied, and CMON answersAccessDeniedboth for a wrong password and for a licensing refusal or a controller whose database is unavailable. An identity whose credentials are correct can therefore readfailedwhile the controller is starting up. (CLUS-8752) - Scoping removes a tool, not a data class. Several tools read the same data, so denying one can leave a sibling serving the same rows. The server names each case at startup as
tool scope: WARNING: …. create_jobstill reaches job commands no tool exposes. It is now bounded — the command must be in the committed catalogue — but that catalogue is wider than the tool surface and includes destructive commands such asremove_cluster,removenodeandfailover. The startup warning about this is narrower than the exposure: it appears only when a tool scope is configured, read-only mode is off,create_jobis in scope, and that scope denies a job-backed tool. A deployment with no scope configured has the exposure in full and gets no warning.- Symlink protection covers the final path component only. For the digest key and the audit log, a hard link at the path itself, or a symlink at any parent directory, is followed normally. Whoever can write a directory on those paths controls what is at the end of them.
- Packages are
x86_64only in this release.
Feature Release: Access controls, audit logging and offline docs
- Build:
- clustercontrol-mcp-1.0.0-90
This release adds the controls needed to connect an AI assistant to a production controller: the server can now refuse actions itself, rather than relying on the client to respect an advisory hint.
- Global read-only mode (
MCP_READ_ONLY) — refuses all 29 state-changing tools for the lifetime of the process. Enforced on two independent layers: the write tools are hidden from the client's tool list, and a direct call on one is refused, so a client that calls a tool it was never shown is still refused. (CLUS-8099) - Per-tool and per-resource scoping (
MCP_TOOL_ALLOW,MCP_TOOL_DENY) — expose only the tools you name. Deny wins over allow, the two compose with read-only mode, and resource surfaces follow their tools automatically. An entry matching no tool is a startup error rather than a silent no-op. (CLUS-8100) - Audit log (
MCP_AUDIT_LOG) — every tool call and resource read recorded twice as JSONL, anintentrecord before the action and acompletionafter, with a thirdacceptancerecord on the background-task path. Raw arguments are never written; what is recorded is a keyed digest, so a reader of the log cannot work backwards to a password. Auditing is fail-closed: if theintentrecord cannot be written, the action does not run. (CLUS-8103) - Export directory containment (
MCP_EXPORT_DIR) — the three tools that write to the MCP Server's own filesystem are confined to one directory, whatever path the client asks for. (CLUS-8581) search_docs— ranked excerpts from a ClusterControl documentation bundle shipped inside the package. No network calls, so it works in an air-gapped installation. (CLUS-8104, CLUS-8105)get_incident_bundle— one read-only call returning alarms, recent jobs, collected log tails, a metric summary with outlier flags, and topology. Every section is always present and explicitly marked[error],[empty]or[truncated], so a section missing because a source failed cannot be mistaken for one that was empty. (CLUS-8106)- The tool registry grows from 70 to 72 tools (43 pure-read, 26 CMON-mutating, 3 local-filesystem-writing; 22 flagged destructive), with 21 resource surfaces unchanged.
- Local file writes are confined by default. A server whose configuration is untouched will begin refusing destination paths outside
/var/lib/cmon-mcp/exports— including paths such as/tmpthat previously worked. SetMCP_EXPORT_DIRto the directory your callers already use to keep their existing paths valid. (CLUS-8581) - A fresh install is audited by default. First installs provision a digest key and switch auditing on. Upgrades enable nothing, because a host that has never been audited has no key and a server told to audit without one refuses to start. Set
MCP_AUDIT_LOG=offin/etc/default/cmon-mcpto opt out. (CLUS-8583) - The configuration file is
/etc/default/cmon-mcp. It follows the service and binary names; the package is stillclustercontrol-mcp. On RPM hosts an earlier build could leave settings behind in a.rpmsavefile during this rename — the installer now reports exactly what it found and where. (CLUS-8601, CLUS-8648)
- A flag-parse error no longer reprints the CMON password and MCP bearer token to the journal. (CLUS-8587)
/etc/default/cmon-mcp, which holdsCMON_PASSWORDandMCP_AUTH_TOKEN, now ships mode0600rather than world-readable, and the installer tightens every copy of it the package manager leaves behind. (CLUS-8594)export_cluster_logis no longer an arbitrary-file write as root; every client-supplied path is confined to the export directory and lands through a staged rename, so a symlink at the destination is never written through. (CLUS-8581)get_controller_configno longer returns live Vault and OpenBao tokens in clear text. (CLUS-8650)- Credentials and key material are held where Go's formatting verbs cannot reach them, so no log line or error message can print them by accident. (CLUS-8595)
- The digest key file is no longer symlink-swappable, and governed mode refuses to write its marker through a dangling symlink. (CLUS-8576, CLUS-8647)
- Every session runs as one CMON identity. The server authenticates as the single configured
CMON_USERNAME, and the audit log attributes every action to it, so two assistants cannot be told apart from the record. Per-session identity is planned for a later release. - Scoping removes a tool, not a data class. Several tools read the same data, so denying one can leave a sibling serving the same rows. The server names each case at startup as
tool scope: WARNING: …. create_jobreaches the whole job surface. Its free-formcommandargument reaches CMON job commands that have no tool of their own and that no deny list can name.- Packages are
x86_64only in this release.
Maintenance Release: September 1st, 2026
- Build:
- clustercontrol-mcp-1.0.0-60
⚠ Breaking change
get_cluster_log no longer accepts output_path and no longer writes files — it is now a pure read that returns log content (the tail of the last 200 lines by default). Callers that used output_path to save a log file locally must switch to the new export_cluster_log tool, which requires output_path and writes the file with mode 0600. (CLUS-8098)
export_cluster_log— exports a collected cluster log file in full to a localoutput_pathon the MCP Server host. The file is written with mode0600, including when overwriting an existing file that had looser permissions. (CLUS-8098)- Tool annotations — all 70 tools now serve the standard MCP
readOnlyHintanddestructiveHintannotations. The annotations are generated at tool registration from a committed, human-reviewed manifest, so the served hints cannot drift from the manifest. Note that annotations are advisory metadata for MCP clients — clients can use them to auto-approve reads and require confirmation before destructive calls — they are not server-side enforcement, anddry_runpreviews remain a client-side safeguard. (CLUS-8098) - The tool registry grows from 69 to 70 tools (41 pure-read, 26 CMON-mutating, 3 local-filesystem-writing; 22 flagged destructive), with 21 resource surfaces (3 static + 18 templates). (CLUS-8098)