Severalnines CCX Server

MCP (Model Context Protocol) server for managing CCX database clusters through AI assistants like Claude Code, Claude Desktop, Cursor, and Windsurf.

Quick Start

Claude Code

Register the server in one command — no manual config file editing required:

claude mcp add ccx -- npx -y @severalnines/ccx-mcp@latest \
  --endpoint https://app.myccx.io \
  --client-id <your-client-id> \
  --client-secret <your-client-secret>

Create OAuth2 credentials in the CCX UI under Account > Security.

Then restart Claude Code (or run /mcp and reconnect) and you're ready to go.

Password auth instead of OAuth2

Use --username and --password in place of --client-id / --client-secret:

claude mcp add ccx -- npx -y @severalnines/ccx-mcp@latest \
  --endpoint https://app.myccx.io \
  --username [email protected] \
  --password your-password

Allow destructive operations

Destructive tools (delete cluster, delete user, restore backup, etc.) are blocked by default. To allow them, add --protect false:

claude mcp add ccx -- npx -y @severalnines/ccx-mcp@latest \
  --endpoint https://app.myccx.io \
  --client-id <id> --client-secret <secret> \
  --protect false

Managing the server

claude mcp list           # show registered servers
claude mcp remove ccx     # remove the server

All available flags

Flag	Maps to env var
--endpoint <url>	CCX_BASE_URL
--client-id <id>	CCX_CLIENT_ID
--client-secret <secret>	CCX_CLIENT_SECRET
--username <email>	CCX_USERNAME
--password <password>	CCX_PASSWORD
--protect <true|false>	CCX_PROTECT
-h, --help	Show usage

CLI flags override environment variables when both are set.

Tips

• Pin @latest in the npx invocation (as shown above). Without a version pin, npx may serve a stale cached build instead of fetching the newest from npm.
• If you have an old node_modules/@severalnines/ccx-mcp from a previous install in your project, delete it — npx will resolve to it before checking the registry and run the wrong version.

Install from npm

Add this to your MCP client configuration:

{
  "mcpServers": {
    "ccx": {
      "command": "npx",
      "args": ["-y", "@severalnines/ccx-mcp"],
      "env": {
        "CCX_BASE_URL": "https://app.myccx.io",
        "CCX_USERNAME": "[email protected]",
        "CCX_PASSWORD": "your-password"
      }
    }
  }
}

Alternative: install as a project dependency

If npx causes issues (e.g. spawning errors or version caching problems), you can install the package as a dependency and reference it directly:

npm install @severalnines/ccx-mcp

Then use this configuration:

{
  "mcpServers": {
    "ccx": {
      "command": "node",
      "args": ["node_modules/@severalnines/ccx-mcp/build/index.js"],
      "env": {
        "CCX_BASE_URL": "https://app.myccx.io",
        "CCX_USERNAME": "[email protected]",
        "CCX_PASSWORD": "your-password"
      }
    }
  }
}

Install from source

git clone https://github.com/severalnines/ccx-mcp.git
cd ccx-mcp
npm install
npm run build

Then point your MCP client to the built server (replace the path with where you cloned the repo):

{
  "mcpServers": {
    "ccx": {
      "command": "node",
      "args": ["/home/user/ccx-mcp/build/index.js"],
      "env": {
        "CCX_BASE_URL": "https://app.myccx.io",
        "CCX_USERNAME": "[email protected]",
        "CCX_PASSWORD": "your-password"
      }
    }
  }
}

Or use OAUTH2 credentials (create them under Accounts -> Security in the CCX UI):

    "CCX_CLIENT_ID": "your-client-id",
    "CCX_CLIENT_SECRET": "your-client-secret"

Where to put the configuration

MCP Client	Config file
Claude Code	.mcp.json in your project root, or ~/.claude/.mcp.json for global
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Cursor	.cursor/mcp.json in your project root
Windsurf	~/.codeium/windsurf/mcp_config.json

CCX_BASE_URL

This is the URL of your CCX deployment. If you're using the hosted CCX service, it's typically https://app.myccx.io. If you're running a self-hosted CCX instance, use its URL instead.

Using OAuth2 instead of password

Replace CCX_USERNAME and CCX_PASSWORD with CCX_CLIENT_ID and CCX_CLIENT_SECRET:

{
  "mcpServers": {
    "ccx": {
      "command": "npx",
      "args": ["-y", "@severalnines/ccx-mcp"],
      "env": {
        "CCX_BASE_URL": "https://app.myccx.io",
        "CCX_CLIENT_ID": "your-client-id",
        "CCX_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

You can create OAuth2 credentials in the CCX UI under Account > Security.

Then ask your AI assistant things like:

• "List my datastores"
• "Create a PostgreSQL cluster on AWS in eu-west-1"
• "Get the connection string for my production database"
• "Add 10.0.0.0/24 as a trusted source on my cluster"
• "Create a new database user called appuser"
• "Scale my cluster to a medium instance"
• "Show me the slowest queries on my database"
• "List backups for my production cluster"
• "What's the CPU usage on my database?"
• "List the default parameters for PostgreSQL 16"
• "Create a parameter group for MySQL 8.4 with max_connections set to 500"

Authentication

Password Auth

Set CCX_USERNAME and CCX_PASSWORD:

{
  "env": {
    "CCX_BASE_URL": "https://app.myccx.io",
    "CCX_USERNAME": "[email protected]",
    "CCX_PASSWORD": "your-password"
  }
}

OAuth2 (Client Credentials)

For programmatic or CI/CD use, set CCX_CLIENT_ID and CCX_CLIENT_SECRET instead:

{
  "env": {
    "CCX_BASE_URL": "https://app.myccx.io",
    "CCX_CLIENT_ID": "your-client-id",
    "CCX_CLIENT_SECRET": "your-client-secret"
  }
}

Available Tools

Datastore Management

Tool	Description
ccx_list_datastores	List all database clusters with status, vendor, and cloud provider
ccx_get_datastore	Get detailed cluster info including credentials and job progress
ccx_create_datastore	Create a new cluster (only vendor, cloud provider, and region required)
ccx_delete_datastore	Delete a cluster (requires explicit confirmation)
ccx_get_nodes	Get cluster nodes with roles, status, and IP addresses
ccx_get_connection_string	Connection strings in URI, CLI, JDBC, and env formats
ccx_scale_datastore	Scale instance size (CPU/RAM) or expand storage volume
ccx_add_node	Add a new replica node to a cluster

Cloud & Plans

Tool	Description
ccx_list_clouds	List available cloud providers and regions
ccx_list_plans	List instance sizes, volume types, and sizes per cloud

Database Management

Tool	Description
ccx_list_databases	List databases on a datastore
ccx_create_database	Create a new database
ccx_delete_database	Delete a database

Database Users

Tool	Description
ccx_list_db_users	List database users with grants and auth plugins
ccx_create_db_user	Create a user with configurable privileges, host, and admin flag
ccx_delete_db_user	Delete a database user

Firewall / Trusted Sources

Tool	Description
ccx_list_firewall_rules	List trusted source CIDRs and allowed ports
ccx_create_firewall_rule	Allow a CIDR to connect to the database
ccx_delete_firewall_rule	Remove a trusted source CIDR

Backups & Recovery

Tool	Description
ccx_list_backups	List available backups with status, type, and timestamps
ccx_restore_backup	Restore from a backup with optional point-in-time recovery

Parameter Groups

Tool	Description
ccx_list_parameter_groups	List parameter groups with optional filtering by vendor, version, or name
ccx_get_parameter_group	Get a parameter group with its full list of parameters
ccx_create_parameter_group	Create a new parameter group with custom database configuration
ccx_update_parameter_group	Update parameters, optionally syncing changes to all associated datastores
ccx_delete_parameter_group	Delete a parameter group (requires explicit confirmation)
ccx_apply_parameter_group	Apply a parameter group to a datastore
ccx_list_default_parameters	Get default parameters for a vendor and version to see available options

Monitoring & Performance

Tool	Description
ccx_get_top_queries	Get slowest queries ranked by execution time
ccx_get_stats	Get performance metrics (CPU, memory, disk, network, SQL, DB stats)

Protection Mode

Destructive operations are blocked by default to prevent accidental data loss. The following tools are affected:

• ccx_delete_datastore — deletes an entire database cluster
• ccx_delete_db_user — deletes a database user account
• ccx_delete_database — deletes a database
• ccx_delete_firewall_rule — removes a firewall access rule
• ccx_restore_backup — overwrites current data with a backup
• ccx_delete_parameter_group — deletes a parameter group
• ccx_apply_parameter_group — applies configuration changes to a datastore

To allow destructive operations, set CCX_PROTECT=false in your MCP configuration and restart the server:

{
  "env": {
    "CCX_PROTECT": "false"
  }
}

Supported Databases

• PostgreSQL
• MySQL / Percona
• MariaDB
• Redis
• Valkey
• Microsoft SQL Server

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run test:watch

Requirements

• Node.js 18+
• A CCX account at ccx.severalnines.com

License

Apache-2.0