AI Assistant (MCP)

3.8 AI assistant access with MCP

Since 3.1.43 replication-manager can expose its clusters to an AI assistant through the Model Context Protocol (MCP): Claude Code, Claude Desktop or any MCP client can list the clusters, read topology, alerts, logs, server status, backups, and, when allowed, run actions such as a switchover or a rolling restart.

Every MCP tool mirrors a REST endpoint and runs under the caller's own permissions: the assistant can do exactly what the account or token it uses can do through the API, nothing more. There is no separate MCP permission model.

3.8.1 Enabling the server

All are server-wide settings, applied live, in the dashboard under Settings (global) → AI Assistant (MCP), or through the global settings API.

With the default api transport nothing else is exposed: the assistant connects to the same HTTPS URL as the dashboard and the API. The standalone sse transport is plain HTTP: keep it on localhost or behind a TLS proxy. The stdio transport carries no credential and only starts with mcp-auth-enabled = false, which runs every tool unrestricted.

3.8.2 Authenticating the assistant

Use an API token: it survives restarts, can be narrowed to the grants and clusters the assistant needs, and is revocable. Create it from your User Profile in the dashboard or from the CLI:

replication-manager-cli token create --label claude --grants "db-show cluster-show" --clusters belair --expire-days 90

Then point the client at the server with the token as bearer, for example in .mcp.json for Claude Code:

{
  "mcpServers": {
    "replication-manager": {
      "type": "sse",
      "url": "https://repman.example.com:10005/api/mcp/sse",
      "headers": { "Authorization": "Bearer ${REPLICATION_MANAGER_API_TOKEN}" }
    }
  }
}

An interactive login JWT from POST /api/login also works, but it expires after api-token-timeout hours and at every restart.

3.8.3 Demo

Claude Code driving replication-manager from the terminal with a token limited to db-show cluster-show on one cluster: the reads are answered, the switchover is refused by the cluster ACL, and the refusal lands in the security log.

The recording is also available as an asciinema cast.

3.8.4 What the assistant may do

• Only the clusters the account has access to are listed; a cluster-scoped token sees only its clusters.
• Each tool is checked against the ACL of the REST endpoint it mirrors: reading server variables needs db-show-variables, a switchover needs cluster-switchover, changing a setting needs cluster-settings, and so on. A token narrowed to db-show can read but never act. There is no global read-only switch: read-only or read-write is decided per account or token.
• Refusals are returned to the assistant as tool errors and written to the security log as mcp_denied; rejected connections as mcp_auth_failure.

3.8.5 Cloud18 from the assistant

The assistant can also connect the instance to Cloud18 and browse the marketplace. These tools are instance-wide, not per cluster: reads are open to any authenticated caller, actions need the global-admin-show grant, and a token must carry the "every cluster" scope.

• get-cloud18-status: registered or not, URI, GitLab user, plan, state of a registration in progress.
• cloud18-register (email, uri): starts the registration. The GitLab password is generated by replication-manager and never shown to the assistant; the person clicks the confirmation email, then get-cloud18-register-status reports complete. cloud18-register-confirm is the manual second step after a timeout. cloud18-unregister disconnects the instance.
• list-cloud18-subscription-plans, get-cloud18-subscription, cloud18-change-subscription (plan).
• list-cloud18-clusters-for-sale: the marketplace catalogue, and list-cloud18-infrastructures: the distinct provider infrastructures (one per api-public-url) with the clusters each offers.
• Prompt cloud18-onboarding walks the assistant through the whole flow.

Creating a cluster on an infrastructure. When the provider has enabled self-service (see Registration, self-service clusters), the assistant can create a cluster there directly, with no subscription or email chain:

• cloud18-create-cluster (infrastructure, cluster_name, db_image, db_count, proxy, apps, confirm). Without confirm it only returns the plan: the services it would create and the infrastructure's self-service status for your identity (enabled or the reason, per-user limit, remaining slots). With confirm=true it creates the cluster on the infrastructure's default unit plan (DBU / APU / BKU, no service plan to choose), sets the database image (default mariadb:lts, the latest MariaDB long-term-support release), adds the database nodes (default 2), the proxy (default haproxy), the apps from their templates (for example phpmyadmin), and provisions. Your instance's Cloud18 identity becomes the sponsor of that cluster; the provider is informed. This is billable consumption on the infrastructure. You are the identity. Your Cloud18 account is valid on every public instance, so a creation is yours wherever it happens, and the instance you talk to spends nothing of its own. Three steps:

• get-cloud18-infrastructures: for each marketplace infrastructure, your self-service status there (may you create a cluster and why not, free DBU and APU of its plan pot, the default plan a cluster takes, the clusters you may still sponsor) and a ready-to-paste MCP server entry carrying your session on that infrastructure, the same login the dashboard's Enter opens, as you. No account and no token are written on the infrastructure, only that session. It expires with the login (api-token-timeout) and is a secret like a token. A local admin without a Cloud18 account acts as this instance's registered identity; a local user or an API token is refused with the way in.

• Connect the assistant to the infrastructure's entry and run cloud18-create-cluster there, with no infrastructure argument: the infrastructure creates the cluster and makes you its sponsor, with the grants to populate, provision and manage it. Your account appears there, and only there.

• cloud18-create-cluster-token, same place: your durable token for that cluster (120 days by default) and the final MCP entry. Only where you created something.

The infrastructure answers the status from a snapshot refreshed every cloud18-self-service-cache-seconds (10 by default): a burst of calls, or a brute force on GET /api/cloud18/self-service, costs it one computation per interval.

• get-cloud18-cluster (infrastructure, cluster_name): state, servers, proxies and apps, to follow the provisioning.
• cloud18-create-cluster-token (infrastructure, cluster_name, grants, expire_days): once the cluster exists, this is how the assistant gets to operate it. A token is valid on one replication-manager only, so the sponsor mints one on the infrastructure hosting the cluster, scoped to that cluster, and the tool returns it once together with the infrastructure's MCP endpoint configuration. Add it to the assistant as a second MCP server (one server per infrastructure) and the cluster's tools appear there, under the partner's ACL for your identity.

For example: "use infrastructure https://repman.example.io to create a cluster named blab, latest MariaDB LTS, HAProxy, with the latest phpMyAdmin app on it".

3.8.6 Tools

Tool names follow six rules, so that a new tool is named by rule and not by taste:

1. A read is <verb>-<domain>-<object>: list- when the result has several entries, get- when it is one object (a status map, a settings object, statistics), check- when it answers yes or no with a reason.
2. An action is <domain>-<verb>[-<object>], imperative: cluster-switchover, database-start, proxy-stop, cluster-archive-purge.
3. The domains are the API's: cluster, database (one database server, as opposed to a proxy), proxy, cloud18. A cluster-scoped object carries cluster (list-cluster-local-backups), a server-scoped one carries database (database-backup-physical).
4. Objects use the product's words, local backups and archive backups, never the name of the implementation behind them.
5. Parameters are cluster_name, server_name (host:port), proxy_name, task_id.
6. One tool is one REST route and needs that route's grant: reads the matching *-show grant, actions the grant named next to them (for example cluster-switchover).

Cluster

Database servers

Proxies

Cloud18

* required parameter. Reads need the matching *-show grant, actions the grant of their REST route (for example cluster-switchover, db-restore, cluster-bench); every tool is one route, see the ACL table in the server.

3.8.7 Application templates

app-add deploys an application next to the database from a template; list-app-templates returns the names the running replication-manager knows (they come from the public cloud18-templates repository). The template name is <directory>/<file>, for example postgres/postgres-standby. Every app gets its plan (cores, memory, disk) from its units, its database access from the cluster ({{app.db.*}}: a schema and a user created for it), a generated password when the template asks for one ({{app.randompassword}}) and an https route on the gateway.

Each code runtime template clones a git repository in an init container at start: the public cloud18-template-code repository holds a "hello world, I'm connected to database server id N" sample for every language, and cloud18-template-config the matching server configuration. An assistant deploying your own code gives app-add the template and, through the app's settings, your repository instead.