Skip to content

ClusterControl MCP

The ClusterControl MCP Server is a bridge between your AI assistant and your databases. You type what you need in plain English or other languages, and it figures out the rest. No dashboards to click through, no commands to memorize. It works with AI tools like Claude Desktop, Claude Code, and OpenAI Codex, and offers 86 tools, 21 resources and 10 guided procedures, covering backups, cluster management, user accounts, performance monitoring, advisors that report findings, and guided recovery. It works with MySQL, MariaDB, PostgreSQL, MongoDB, SQL Server, and TimescaleDB.

How It Works

The diagram below shows how everything connects. Your AI tool sits at the top. When you type a request, it goes through the MCP Server, which translates it into the right action and passes it to the CMON Controller. The controller then talks to whichever database cluster you are working with.

Before you get started, make sure you have the following in place:

  • A running ClusterControl installation with CMON Controller accessible over the network (CMON controller reachable on port 9501)
  • A CMON user account with access to the clusters you want to query
  • An MCP-compatible AI client such as Claude Desktop, Claude Code, or OpenAI Codex

Once you have confirmed all the requirements above are in place, you are ready to install and configure the ClusterControl MCP Server. Packages are published to the Severalnines repository alongside other ClusterControl components.

sudo yum install clustercontrol-mcp

sudo apt-get install clustercontrol-mcp

The binary installs to /usr/bin/cmon-mcp. A systemd service unit and default configuration file are also installed:

  • /etc/systemd/system/cmon-mcp.service : service unit
  • /etc/default/cmon-mcp : environment file for credentials and transport options
  • /etc/cmon-mcp/governed.env : written by a fresh install; turns the audit log on and names the digest key
  • /etc/cmon-mcp/digest.key : the digest key a fresh install generates (mode 0600)
  • /usr/share/cmon-mcp/profiles/ : the two deployment profiles
  • /usr/share/cmon-mcp/docs : the documentation bundle search_docs reads
  • /etc/logrotate.d/cmon-mcp : rotation for the audit log

Packages are built for x86_64 only.

Tool Annotations

Every tool the MCP Server exposes advertises the standard MCP annotations readOnlyHint and destructiveHint alongside its name and description. Of the 86 tools, 57 are pure reads, 26 change state on the CMON Controller, and 3 write files on the local filesystem of the MCP Server host; 22 tools carry destructiveHint: true. The annotations are generated at tool registration from a committed, human-reviewed manifest, so the hints a client sees cannot drift from what was reviewed.

MCP clients can use these annotations to auto-approve read-only tools and to require explicit confirmation before state-changing or destructive ones. Keep in mind that annotations are advisory metadata for the client: the server does not enforce them. On its own, the dry-run preview for write operations is a client-side safeguard too, but the server can enforce it: with the execution guard on, a destructive call runs only against a confirmation minted on a preview of the same call, and the approval tier can require an approval as well. See Confirmation and Approval.

If you need the server itself to refuse an action rather than rely on the client, see Access Control below.

Configuration

The ClusterControl MCP Server is configured through the /etc/default/cmon-mcp file on your CMON host. Open the file and edit the values to match your environment:

sudo vi /etc/default/cmon-mcp

Where Settings Come From

Every setting can be given as a command-line flag or as an environment variable. On a server host, the environment comes from two files that systemd loads in order.

Source Used when Notes
Command-line flags, for example -endpoint or -read-only An AI client starts the server itself (stdio), for example claude mcp add clustercontrol -- cmon-mcp … A flag wins over the same setting in the environment. A password passed as a flag is briefly visible in the process list, so prefer CMON_PASSWORD or, better, CMON_KEY_FILE.
Environment variables in the client's configuration An AI client starts the server itself, for example the env block in claude_desktop_config.json The same names as on a server host.
/etc/default/cmon-mcp The cmon-mcp systemd service Your file. systemd loads it second, so a setting here wins over the same setting in governed.env. An upgrade does not overwrite it.
/etc/cmon-mcp/governed.env The cmon-mcp systemd service Written by a fresh install: it turns the audit log on and names the generated digest key. Loaded first, so /etc/default/cmon-mcp can override it, for example with MCP_AUDIT_LOG=off.
Files a setting points to When you name them The identity map, the approver map, the digest key, an operator lifecycle table and the documentation bundle. The deployment profiles in /usr/share/cmon-mcp/profiles/ are never read in place; see Deployment Profiles.

The audit log, the execution guard, the approval mode and the independent-approval settings have no flag: set them in the environment.

Two Ways to Run It

On the client (stdio) As a service (HTTP)
Who starts the server Each AI client starts its own process systemd, once, on a host that can reach the CMON Controller
Where settings live Flags or the client's env block /etc/default/cmon-mcp
Turned on by MCP_BIND_ADDRESS unset MCP_BIND_ADDRESS set, for example 127.0.0.1:3000
ClusterControl identity The one user in its settings One user, or one per caller with an identity map
Needed for A single user on their own machine Team access, per-agent identities, approvals attributed to a user, the agentic-operate profile, independent approval

Configuration Parameters

CMON Controller Connection

Parameter Description Example
CMON_ENDPOINT The URL of your CMON Controller API https://127.0.0.1:9501
CMON_USERNAME The ClusterControl username admin
CMON_PASSWORD Password for the user (leave empty if using key auth) severalNINES999
CMON_KEY_FILE Path to RSA private key (alternative to password) /etc/clustercontrol/id_rsa

You can authenticate using either a password or an RSA key file, not both at the same time. If CMON_PASSWORD is set, leave CMON_KEY_FILE empty, and vice versa.

The CMON user you specify here is the identity the MCP Server uses for every action it performs. We recommend creating a dedicated CMON user with only the privileges your team actually needs and please avoid reusing your main admin account.

MCP Server

Parameter Description Example
MCP_BIND_ADDRESS Address and port the MCP Server listens on 0.0.0.0:3000
MCP_BASE_URL Public URL that AI clients use to connect http://your-cc-host:3000
MCP_AUTH_TOKEN Bearer token to secure all incoming connections your-strong-random-token

For MCP_BIND_ADDRESS, use 127.0.0.1:3000 if you only need local access, or 0.0.0.0:3000 to allow remote AI clients to connect.

MCP Transport Endpoints

The MCP Server exposes two transports on the same port: /sse and /message is SSE transport, used by Claude Desktop and Claude Code. /mcp is Streamable HTTP transport, used by OpenAI Codex

Per-Caller Identity

Parameter Description Example
MCP_IDENTITY_MAP_FILE Maps each caller's bearer token to its own ClusterControl user (also -identity-map-file); HTTP only /etc/cmon-mcp/identity-map.yaml

By default every session acts as the one CMON user configured above, so the audit log cannot tell two callers apart. An identity map binds each token to its own ClusterControl user. The file must be mode 0600, and an unmapped token is refused before anything runs; it never falls back to the configured user.

identities:
  - token_label: agent-a            # names this entry in errors and logs
    token_hash: sha256:<64 hex>     # or token: <a strong random token>
    cmon_username: agent-a          # what every audit record names
    cmon_password: <password>       # or cmon_key_file: /path/to/key

An identity map changes the HTTP endpoints

With a map active, MCP_AUTH_TOKEN is ignored (each token authenticates on its own) and /sse and /message are not served. Clients that can only use SSE cannot be used with an identity map; connect them to /mcp instead.

Access Control

These settings are enforced by the server, not by the AI client. Unlike tool annotations and dry_run previews, a refusal here cannot be overridden by the client.

Parameter Description Example
MCP_READ_ONLY Refuses all 29 state-changing tools for the lifetime of the process 1
MCP_TOOL_ALLOW Comma-separated list of the only tools to expose list_clusters,list_alarms
MCP_TOOL_DENY Comma-separated list of tools to refuse; wins over MCP_TOOL_ALLOW create_job,restore_backup

Read-only mode both hides the write tools from the client's tool list and refuses a direct call on one, so a client that calls a tool it was never shown is still refused. Scoping works the same way, and the resource surfaces follow their tools automatically — a surface is served only when every tool it maps to is in scope.

A name that matches no tool stops the server

An unknown entry in either list is a startup error naming every offender, and the service exits non-zero. This is deliberate: a silently ignored deny entry would leave a tool you meant to remove fully exposed.

Prefer MCP_TOOL_ALLOW when the requirement is only these

A deny list names what to remove, so a tool added in a later release is exposed by default. An allow list names what to keep, so a new tool is out of scope until you add it.

Read the startup warnings. Scoping is by tool name, and a tool name is not a data class. Several tools read the same data from the CMON Controller, so denying one can leave a sibling serving the same rows. The server names every such case at startup as tool scope: WARNING: …. If you denied a tool for a security reason, that line tells you whether you actually removed the data.

One case deserves singling out: create_job takes a free-form command, which reaches CMON job commands that have no tool of their own and that no tool deny list can name — including drop_cluster, remove_node and failover. Limit them with the job command policy below. Without one, if create_job is in scope, treat the assistant as able to run any CMON job.

Job Command Policy

Parameter Description Example
MCP_JOB_COMMAND_ALLOW Comma-separated CMON job commands that create_job and the dedicated job tools may submit; unset permits every one verify_backup,stage_replication_slave
MCP_JOB_COMMAND_DENY Comma-separated job commands to refuse; wins over the allow list remove_cluster

A command the policy does not permit is refused with JOB_COMMAND_NOT_PERMITTED before any preview, confirmation, approval request or controller request, and is checked again just before submission. A tool that submits one fixed command (delete_backup, restore_backup, generate_error_report, create_backup_schedule, update_backup_schedule) is hidden when its command is not permitted. A name that is not a known job command stops the server at startup. The policy is logged at every start as job command policy: …, and get_session_info reports it.

The policy governs job submission, not effects

set_controller_config, set_node_config, unset_node_config and add_maintenance_window reach some of the same effects as job commands through other requests. Scope those tools with MCP_TOOL_ALLOW or MCP_TOOL_DENY as well; the server names each such case at startup.

Independently of the policy, create_job checks a job before anyone is asked to approve it: the identity needs read and execute access on the cluster, job_data must be one JSON object with unique keys, and replica rebuilds, upgrades, PostgreSQL promotions and point-in-time recovery are held to the shapes the release notes describe.

Confirmation and Approval

Parameter Description Example
MCP_EXECUTION_GUARD enforced: a destructive call runs only against a single-use confirmation minted on a preview of the same call. Unset or off: off enforced
MCP_HUMAN_APPROVAL elicitation: every destructive execution is put to the calling session for approval. out_of_band: a separately authenticated approver decides. Unset or off: off elicitation
MCP_APPROVAL_BIND_ADDRESS For out_of_band: the separate loopback address approvers answer on 127.0.0.1:8089
MCP_APPROVER_MAP_FILE For out_of_band: the operator-owned approver list, with cmon_username and token_sha256 entries /etc/cmon-mcp/approvers.yaml

With the guard on, a refused call gets CONFIRMATION_REQUIRED; preview it first and present the confirmation it returns. Confirmations are single-use and held in memory, so a restart revokes every outstanding one.

MCP_HUMAN_APPROVAL accepts on, enforced, 1 and true as older spellings of elicitation. Any other value stops the server at startup.

  • elicitation sends the approval request to the calling session. That is a person's decision only if the client shows the request to a person the agent cannot answer for; so far the official MCP Python SDK with an elicitation_callback is the only client shown approving. It needs an identity map: without per-session identity a destructive call is refused with HUMAN_APPROVAL_UNAVAILABLE.
  • out_of_band waits for an approver whose ClusterControl user is not the requester's. Approver tokens must differ from every caller's, and a request expires after two minutes. It requires the identity map, the digest key and the audit log, and the server does not start without them.

Point-in-time recovery always needs an approval model: with MCP_HUMAN_APPROVAL off it is refused with PITR_APPROVAL_MODEL_REQUIRED. Either mode proves who answered, not that a person read the request.

Governed mode needs a digest key

Turning on the audit log, the execution guard or the approval tier puts the server in a governed mode, and a governed server needs the digest key. A fresh install creates /etc/cmon-mcp/digest.key; on a host that was upgraded rather than installed, write a key and set MCP_DIGEST_HMAC_KEY_FILE before you restart.

Auditing

Parameter Description Example
MCP_AUDIT_LOG Path to the JSONL audit log; off disables auditing /var/log/cmon-mcp/audit.jsonl
MCP_DIGEST_HMAC_KEY_FILE Key file the argument digests are computed under /etc/cmon-mcp/digest.key

Every tool call and resource read is recorded twice — an intent record before the action runs and a completion record after, correlated by call_id. Background tasks add a third, acceptance, correlated by task_id. Two records rather than one, because a single record written at the end cannot be told apart from an action that never happened, and the actions that matter most are the ones that did not return.

Raw arguments are never written. What is recorded is a keyed digest of them, so that someone who can read the log cannot work backwards to a low-entropy argument such as a password.

A fresh install is audited by default; an upgrade changes nothing

A first install provisions /etc/cmon-mcp/digest.key and /etc/cmon-mcp/governed.env, and that second file switches auditing on — so a newly installed host records from its first call. An upgrade enables nothing, because a host that has never been audited has no key, and a server that is told to audit without one refuses to start. To turn auditing off on a fresh install, set MCP_AUDIT_LOG=off in /etc/default/cmon-mcp, which is read after the package's file and wins.

Auditing is fail-closed

If the intent record cannot be written, the call is refused with AUDIT_UNAVAILABLE and the action never runs. This is the intended behaviour: an unauditable server does not act.

It also means the log's permissions matter. The server refuses any log file whose mode is wider than 0600, on every record, so a rotation policy that recreated it world-readable would refuse every later call. The shipped /etc/logrotate.d/cmon-mcp already handles this correctly — do not loosen its create 0600 root root line.

To find failed actions you need both fields, because they mean different things:

jq 'select(.outcome=="error" or .tool_is_error==true)' /var/log/cmon-mcp/audit.jsonl

outcome covers transport and task-level failure; tool_is_error covers a tool that ran and returned an error. The absence of tool_is_error is not evidence that the tool succeeded.

File Exports

Parameter Description Example
MCP_EXPORT_DIR The one directory local file writes are confined to; off refuses them all /srv/cc-exports

Three tools write to the MCP Server host's own filesystem: download_error_report, export_cluster_log and unpack_error_report. Each takes a destination path from the client, and the service runs as root, so without a boundary, granting an assistant export_cluster_log alone is not meaningfully different from granting it root write access to the host. Every path the client supplies is resolved inside this directory and may not leave it.

The default is /var/lib/cmon-mcp/exports, created at mode 0700 on start.

This can change behaviour on an existing host

The boundary is on by default, so a server whose configuration you never touched will begin refusing paths such as output_path=/tmp/report.tar.gz that previously worked. Point MCP_EXPORT_DIR at the directory those callers already use to keep their existing paths valid.

The boundary is only as strong as the directory's own permissions. If it is a symlink, group- or world-writable, or owned by another user, the server says so at startup as export dir: WARNING: … rather than refusing — a link onto a larger volume is a legitimate thing to want.

Parameter Description Example
MCP_DOCS_DIR Installed ClusterControl documentation bundle used by search_docs /usr/share/cmon-mcp/docs

The package ships a documentation bundle and the search_docs tool answers from it locally, with no network calls, so it works in an air-gapped installation. The bundle is read once at startup; if it cannot be loaded, only search_docs is disabled and the reason is written to the journal, leaving every other tool working. Restart the service after repairing or upgrading it.

Advisors

Parameter Description Example
MCP_SUPPORT_ENTITLEMENT Your support entitlement, which check_version_eol judges end of life against: mysql= premier, extended or sustaining; mariadb= community, enterprise or extended; and cluster:<id>= overrides. Unset: each engine's free community stream mysql=extended
MCP_EOL_TABLE_FILE Your own release lifecycle table instead of the bundled one, in the same format, for example to get newer end-of-life dates on an air-gapped host between packages /etc/cmon-mcp/eol.yaml

The bundled lifecycle table is never fetched from the network. A table you name that cannot be read or parsed stops the server at startup, and the refusal never quotes a value from the file.

Complete Configuration Example

The following shows the ClusterControl MCP Server example configuration after it has been set up through the /etc/default/cmon-mcp file on your CMON host.

# CMON Controller connection
CMON_ENDPOINT=https://127.0.0.1:9501
CMON_USERNAME=admin
CMON_PASSWORD='severalNINES999'
# RSA key auth alternative (leave CMON_PASSWORD empty if using this):
# CMON_KEY_FILE=/etc/clustercontrol/id_rsa

# MCP Server
MCP_BIND_ADDRESS=0.0.0.0:3000
MCP_BASE_URL=http://your-cc-host:3000
MCP_AUTH_TOKEN=

# Access control — enforced by the server, not the AI client.
# Start here if you are connecting an assistant to a production controller.
MCP_READ_ONLY=1
# MCP_TOOL_ALLOW=list_clusters,get_cluster,list_alarms,search_docs
# MCP_TOOL_DENY=create_job

# Auditing — set automatically on a fresh install; shown here for reference.
# MCP_AUDIT_LOG=/var/log/cmon-mcp/audit.jsonl
# MCP_DIGEST_HMAC_KEY_FILE=/etc/cmon-mcp/digest.key

# File exports — defaults to /var/lib/cmon-mcp/exports. Set this if callers
# already rely on a different directory.
# MCP_EXPORT_DIR=/srv/cc-exports

# Per-caller identity (HTTP only) — one ClusterControl user per token.
# MCP_IDENTITY_MAP_FILE=/etc/cmon-mcp/identity-map.yaml

# Job command policy — the job commands create_job may submit.
# MCP_JOB_COMMAND_ALLOW=verify_backup,stage_replication_slave

# Confirmation and approval for destructive calls.
# MCP_EXECUTION_GUARD=enforced
# MCP_HUMAN_APPROVAL=elicitation
# Or independent approval:
# MCP_HUMAN_APPROVAL=out_of_band
# MCP_APPROVAL_BIND_ADDRESS=127.0.0.1:8089
# MCP_APPROVER_MAP_FILE=/etc/cmon-mcp/approvers.yaml

Start read-only

MCP_READ_ONLY=1 is the setting to reach for first when pointing an assistant at a production controller. All 57 read tools keep working, so the assistant can still investigate, explain and report — it simply cannot change anything. Turn it off deliberately, once you know which write actions you actually want to allow.

Generating a Secure Token

It is strongly recommended to protect your MCP Server with a bearer token, especially when MCP_BIND_ADDRESS is set to 0.0.0.0. Generate one with:

openssl rand -hex 32

Copy the output and set it as the value of MCP_AUTH_TOKEN.

Starting the Service

Save the configuration file, then restart the service:

systemctl restart cmon-mcp

Confirm it started successfully:

journalctl -u cmon-mcp -n 20

You should see output confirming the MCP Server is running and listening on the address defined in MCP_BIND_ADDRESS.

A malformed value in any setting stops the server at startup with exit code 78 and names the setting, and systemd does not keep restarting it, so nothing runs half-configured. Each setting logs its effective value at startup, so the journal shows what took effect. From a client, get_session_info shows the session's transport, its ClusterControl identity, the job command policy, and whether an approval request can reach the client.

Common Setups

You want Configure
One person on their own machine stdio: the connection settings in the client's configuration. Add MCP_READ_ONLY=1 if it should only read.
A team sharing one server The service with MCP_BIND_ADDRESS and an identity map, so each person acts as their own ClusterControl user.
An agent that only diagnoses and advises The agentic-observe deployment profile.
An agent that fixes what a finding names, under approval The agentic-operate deployment profile, and MCP_HUMAN_APPROVAL=out_of_band if a second person must approve.
A host without internet access Nothing extra: the lifecycle table and documentation bundle ship in the package. Use MCP_EOL_TABLE_FILE for newer end-of-life dates.

Deployment Profiles

The package ships two ready-made configurations for running the server under an AI agent. Each is a short list of settings that switches on the controls an agent should run with and limits it to the tools its job needs. Start from one rather than writing the configuration yourself.

What a Profile Is

  • Two files in /usr/share/cmon-mcp/profiles/: agentic-observe.env and agentic-operate.env. The package owns them: they are readable by everyone (0644), hold no credentials, and are replaced on every upgrade.
  • Nothing reads them in place. Copy the assignments from one into /etc/default/cmon-mcp and restart with systemctl restart cmon-mcp. Your connection settings stay where they are.
  • Copy the lines rather than including the file: a systemd drop-in naming it with EnvironmentFile= would be read after /etc/default/cmon-mcp and would silently override anything you later change there.

Which One to Use

Profile The agent can The agent cannot
agentic-observe Run every advisor and the fleet view, follow a finding's next action to the read it names, and make every read a guided procedure needs Change anything: every write tool is hidden and refused with READ_ONLY_MODE, so a procedure stops at its submit step
agentic-operate Everything agentic-observe can, plus run a guided procedure to its submit step and submit the job through create_job or restore_backup, after a confirmation and an approval Submit a job command its procedures do not use, such as remove_cluster, or use any other write tool

Use agentic-observe for an assistant that diagnoses and advises, with nothing to approve. Use agentic-operate for one that can fix what a finding names, under approval.

What Each Profile Sets

Setting agentic-observe agentic-operate
MCP_READ_ONLY 1 unset
MCP_AUDIT_LOG /var/log/cmon-mcp/audit.jsonl /var/log/cmon-mcp/audit.jsonl
MCP_EXECUTION_GUARD unset (nothing to confirm) enforced
MCP_HUMAN_APPROVAL unset (nothing to approve) elicitation
MCP_EXPORT_DIR unset off
MCP_BIND_ADDRESS, MCP_IDENTITY_MAP_FILE not needed required; the file carries them as commented placeholders
MCP_TOOL_ALLOW 25 tools: every advisor, get_fleet_posture, get_session_info, and the read tools that findings and procedures name the same 25 plus create_job and restore_backup
MCP_JOB_COMMAND_ALLOW unset (create_job is refused anyway) promote_replication_slave, restore_backup, stage_replication_slave, upgrade_cluster, verify_backup

Before You Start

  • Both profiles turn the audit log on, which requires the digest key. A fresh install provisions one; on an upgraded host, write a key and set MCP_DIGEST_HMAC_KEY_FILE before you restart.
  • agentic-operate needs the HTTP transport and an identity map. Without them the server starts but refuses every create_job and restore_backup execution with HUMAN_APPROVAL_UNAVAILABLE (a dry_run preview still works), and says so at startup.
  • Bring an approver client: under elicitation the approval request goes to the agent's own session. For an approval from a separate person, use out_of_band (see Confirmation and Approval).
  • Moving an agent from agentic-observe to agentic-operate: remove the MCP_READ_ONLY line, or every create_job and restore_backup is refused with READ_ONLY_MODE.

Setting It Up

  1. Copy the assignments from the profile into /etc/default/cmon-mcp. For agentic-operate, keep the MCP_BIND_ADDRESS line already in that file and set MCP_IDENTITY_MAP_FILE to your identity map.
  2. Restart: systemctl restart cmon-mcp.
  3. Read the startup lines: journalctl -u cmon-mcp. The job command policy: line lists the job commands allowed, and each session's get_session_info reports the same list.

Each profile prints some WARNING: lines at every start, and they are expected. The tool scope: lines name data that an allowed tool still reads for a tool the profile leaves out. Under agentic-observe, the sop prompts: line says no approval is enforced, which is true and harmless: nothing can be submitted there. A warning of any other kind is the one to read.

What You Can Change

Change your copy in /etc/default/cmon-mcp, never the profile file.

Change Effect
Add a tool to MCP_TOOL_ALLOW The agent can call it. A non-destructive write tool you add is gated by neither the execution guard nor the approval tier, so prefer read tools.
Remove a tool The agent can no longer call it. Other allowed tools may still read the same data; the tool scope: warnings at startup name them.
Add a job command to MCP_JOB_COMMAND_ALLOW The agent can submit it through create_job, after its own preview and an approval.
Have a separate person approve Set MCP_HUMAN_APPROVAL=out_of_band with MCP_APPROVAL_BIND_ADDRESS and MCP_APPROVER_MAP_FILE.
Switch the guard or the approval off under agentic-operate Not recommended: destructive calls then run without a confirmation or an approval, and point-in-time recovery is refused until an approval model is set.

After an Upgrade

Your copy in /etc/default/cmon-mcp is never overwritten. Compare it with the new profile files after each upgrade: a tool or job command that a release adds stays refused under your copy until you add it. In 1.0.0-213 both profiles add advise_workload and list_available_upgrades, and agentic-operate adds the restore_backup tool and job command.

diff <(grep -E '^MCP_' /usr/share/cmon-mcp/profiles/agentic-operate.env | sort) \
     <(grep -E '^MCP_' /etc/default/cmon-mcp | sort)

Limits

  • A profile limits tools, not data. Under agentic-observe, advise_workload reads the database user and database names of long-running and idle-in-transaction sessions, and the database names and normalised statement patterns of busy or full-scanning queries. Leave advise_workload out of your copy if an observing agent should not see them.
  • A profile governs calls made through the MCP Server only; the ClusterControl GUI, the s9s CLI and other clients are not affected.

Connecting to AI Clients

Once the MCP Server is running, you need to register it with your AI client. The steps differ slightly depending on which client you use.

Claude Desktop

Open your Claude Desktop configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following entry under mcpServers so that it looks like this :

{
  "mcpServers": {
    "clustercontrol": {
      "type": "sse",
      "url": "http://your-cc-host:3000/sse",
      "headers": {
        "Authorization": "Bearer your-auth-token"
      }
    }
  }
}

Alternatively, you can use mcp-remote with Node.js installed on your environment with the following JSON configuration:

{
  "mcpServers": {
    "clustercontrol": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://your-cc-host:3000/sse",
        "--allow-http",
        "--header",
        "Authorization: Bearer your-auth-token"
      ]
    }
  }
}

With an identity map

When an identity map is active, /sse and /message are not served. Point the mcp-remote form at http://your-cc-host:3000/mcp with the agent's own token instead.

Save the file and restart Claude Desktop. You should see clustercontrol appear in the File → Settings → developer → Local MCP servers panel like this after restart Claude Desktop.

Claude Code

To connect to the MCP Server running as a service, use its SSE endpoint:

claude mcp add --transport sse \
  --header "Authorization: Bearer your-auth-token" \
  clustercontrol http://your-cc-host:3000/sse

With an identity map active, /sse is not served; connect to the streamable HTTP endpoint instead, with the agent's own token:

claude mcp add --transport http \
  --header "Authorization: Bearer your-agent-token" \
  clustercontrol http://your-cc-host:3000/mcp

To run the MCP Server on your own machine instead (stdio, with cmon-mcp installed there), let Claude Code start it. Pass the credentials in the environment rather than as flags, which are briefly visible in the process list:

claude mcp add \
  --env CMON_ENDPOINT=https://your-cc-host:9501 \
  --env CMON_USERNAME=admin \
  --env CMON_KEY_FILE=/path/to/id_rsa \
  clustercontrol -- cmon-mcp

To verify it was added:

claude mcp list

OpenAI Codex

Add the MCP Server to your Codex tool configuration using the /mcp endpoint:

{
  "tools": [
    {
      "type": "mcp",
      "server_label": "clustercontrol",
      "server_url": "http://your-cc-host:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-auth-token"
      },
      "require_approval": "never"
    }
  ]
}

require_approval: \"never\" approves every tool call

With this setting Codex calls every tool without asking you, write tools included. Use it with MCP_READ_ONLY=1 or the agentic-observe profile, or switch on the server's execution guard and approval tier so that destructive calls cannot run unconfirmed.

Verifying the Connection

Once connected, ask your AI assistant the following to confirm everything is working:

List all my database clusters

If the setup is correct, it will return the list of clusters managed by your ClusterControl instance.

Copyright © 2014-2026 Severalnines AB. All rights reserved.

Severalnines and ClusterControl are registered trademarks in the US, UK, and EU. The 3rd-party trademarks on this site are property of their respective owners and are used for referential purposes only.

Made with Material for MkDocs