Cb Analytics Capella

Capella Management via cb-analytics-mcp

The 9 capella_* tools wrap Couchbase Capella's v4 Management API. They are only available when CB_CAPELLA_API_KEY_SECRET is set; otherwise the tools raise a clear RuntimeError: Capella client is not configured.

The hierarchy

Organization (you may belong to several)
└── Project        (group of clusters; usually one per environment)
    └── Cluster    (the actual Capella deployment)
        └── Backup

Every cluster-scoped tool takes (org_id, project_id, cluster_id) in that order. Use capella_list_organizations() and your own org's project IDs to discover them — the tools don't accept names.

Read-only first

• capella_list_organizations() — first call to discover IDs.
• capella_list_clusters(org_id, project_id) — see what exists.
• capella_get_cluster(org_id, project_id, cluster_id) — full details for one.
• capella_list_backups(org_id, project_id, cluster_id) — list available

backups.

• capella_list_api_keys(org_id) — audit API key usage.

Write operations (require confirmation)

• capella_create_cluster(org_id, project_id, cluster_spec) — cluster_spec

is a free-form dict matching the v4 API schema; don't guess it, ask the user to paste the exact body, or refer them to Capella's UI's "View as JSON" feature.

• capella_delete_cluster(org_id, project_id, cluster_id) — destructive.

Always restate the cluster name and project before calling.

• capella_create_backup(org_id, project_id, cluster_id) — triggers an

immediate backup. Cheap; safe to retry on failure.

• capella_restore_backup(org_id, project_id, cluster_id, backup_id, target_cluster_id=None) —

restore in place (omit target_cluster_id) or into a different cluster (set target_cluster_id). Always confirm the source backup id and destination cluster.

What the tools won't do

• They don't create projects or organizations (rarely needed; do that in

the Capella UI).

• They don't manage cluster networking, allowed CIDRs, or VPC peering — use

the Capella UI or the broader v4 API directly.

• They don't subscribe / unsubscribe billing.

Common failure modes

• AnalyticsAuthError: the API key is missing the required role for the

org. The fix is in the Capella UI, not here.

• AnalyticsNotFoundError: a stale org/project/cluster id. Re-list

parents to refresh.

• AnalyticsRequestError with status 400: the cluster_spec doesn't

match what Capella expects. Surface the message body to the user verbatim; it usually names the offending field.

What to avoid

• Don't capella_delete_cluster without an explicit, named confirmation in

the conversation.

• Don't poll cluster status faster than every 30 seconds for long-running

provisions; Capella throttles.

• Don't store the Capella API key in plain config files. Use the env var.

Rate limits & safety

Capella tools split across rate-limit categories:

• read (60/sec): capella_list_organizations, capella_list_clusters,

capella_get_cluster, capella_list_backups, capella_list_api_keys.

• write (1/sec): capella_create_cluster, capella_delete_cluster,

capella_create_backup, capella_restore_backup.

Capella's own API throttles separately and more aggressively than our local rate limit — long-running provisions reject status polling faster than every ~30 seconds. So both buckets exist: ours (per-API-key, in-process) plus Capella's (their service).

If a RateLimitExceeded comes back from our server, honour retry_after_sec. If a 429/throttle comes from Capella itself, surface the message verbatim — it usually names the offending limit.

Don't try to work around the write-rate limit on capella_delete_cluster or capella_restore_backup by raising RATE_LIMIT_WRITE_PER_SEC. The limit is there precisely because these operations are destructive at cloud scale.

Related skills

• cb-analytics-cluster — once connected to a Capella cluster, cluster-level ops use these tools
• couchbase-mcp — the MCP-Couchbase server has 16 read-only capella_* tools for org/project/cluster inspection (separate server, separate credentials)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: celticht32
• Source: celticht32/Couchbase-Skills-for-Claude.ai
• License: MIT

Install and usage instructions live in the source repository linked above.