cube-mcp 0.3.25

MCP server for EdgescaleAI Cube operations

cube-mcp

MCP server for EdgescaleAI Cube management and Apollo deployments.

Architecture

cube-agent runs locally as an MCP server (via npx cube-mcp). It handles authentication, Docker builds, Helm chart packaging, and app proxy tunnels. Server-side operations (Kubernetes, Teleport, Apollo) are proxied to cube-cloud, a FastAPI backend hosted on AWS ECS.

┌──────────────────────────────────────────────────────────────────────────────┐
│  LOCAL (developer machine)                                                   │
│                                                                              │
│  ┌─────────────┐    MCP JSON-RPC     ┌──────────────────────────────────┐   │
│  │ Claude Code  │◄──────────────────►│  cube-agent (MCP server)         │   │
│  └─────────────┘                     │                                  │   │
│                                      │  Local tools:                    │   │
│                                      │   • agent_login_browser          │   │
│                                      │   • agent_login / logout         │   │
│                                      │   • agent_status                 │   │
│                                      │   • cube_cluster_login           │   │
│                                      │   • build_and_publish_to_apollo  │   │
│                                      │   • app_proxy / stop / status    │   │
│                                      │                                  │   │
│                                      │  Remote tools:                   │   │
│                                      │   (proxied to cube-cloud ──────) │   │
│                                      └────────┬──────────┬──────────────┘   │
│                                               │          │                   │
│   ~/.kube/config ◄── kubeconfig merge         │          │ WebSocket         │
│   ~/.cube-agent/  ◄── API key storage         │          │ /tunnel           │
│   localhost:PORT  ◄── app proxy listener      │          │                   │
└───────────────────────────────────────────────┼──────────┼───────────────────┘
                                                │          │
                               HTTPS + Bearer   │          │  TCP-over-WS
                               POST /mcp/        │          │  relay
                                                │          │
┌───────────────────────────────────────────────┼──────────┼───────────────────┐
│  CLOUD (AWS ECS)                              │          │                   │
│                                               ▼          ▼                   │
│  ┌────────────────────────────────────────────────────────────────────────┐  │
│  │  cube-cloud (FastAPI)                                                  │  │
│  │                                                                        │  │
│  │  ┌─────────────────────┐     ┌──────────────────────────────────────┐ │  │
│  │  │  Auth Middleware     │     │  RBAC (Cognito + Profiles)          │ │  │
│  │  │  • Validate API key  │────►│  • Cognito group → profile          │ │  │
│  │  │    (DynamoDB lookup)│     │  • Profile → Apollo credentials     │ │  │
│  │  │  • Attach profile   │     │    (AWS Secrets Manager)            │ │  │
│  │  └─────────────────────┘     └──────────────────────────────────────┘ │  │
│  │                                                                        │  │
│  │  Cloud tools (RBAC-gated):                                            │  │
│  │   Kubernetes        Apollo Environments    Apollo Products            │  │
│  │   • cube_list       • list_environments    • list_products            │  │
│  │   • cube_status     • create_environment   • compare_product_versions │  │
│  │   • kubectl_exec    • replicate_environment• list_release_channels    │  │
│  │   • app_list        • delete_environment   • get_product_releases     │  │
│  │                     • install/uninstall_    • add/remove_product_     │  │
│  │   Modules             entity                 to_release_channel       │  │
│  │   • list_modules    • entity_health        • set/remove_label         │  │
│  │   • install_module  • plan_details                                    │  │
│  │   • uninstall_module• update/enforce_      Change Requests            │  │
│  │   • update_module_    entity_config        • list_change_requests     │  │
│  │     variables       • reset_env_agents     • review_change_request    │  │
│  │                                                                        │  │
│  │   Secrets           Registry                                          │  │
│  │   • create_secret   • acr_get_token                                   │  │
│  │   • update_secret   • apollo_publish_manifest                         │  │
│  └────────────────────────┬───────────────────────────┬──────────────────┘  │
│                           │                           │                      │
│  ┌────────────────────────┴────────────────┐          │                      │
│  │  tbot sidecar (Teleport credentials)    │          │                      │
│  │  • IAM join method (Fargate identity)   │          │                      │
│  │  • identity/  → tsh commands            │          │                      │
│  │  • kube/{cluster}/ → kubeconfigs        │          │                      │
│  │  • app-{name}/ → app TLS certs          │          │                      │
│  └──────────┬─────────────────────────────┘          │                      │
│             │                                         │                      │
└─────────────┼─────────────────────────────────────────┼──────────────────────┘
              │                                         │
              │ tsh/tctl (short-lived certs)            │ GraphQL (OAuth2)
              ▼                                         ▼
┌──────────────────────────┐            ┌──────────────────────────────────┐
│  Teleport                │            │  Apollo                          │
│  edgescaleai.teleport.sh │            │  edgescaleai.palantirapollo.com  │
│                          │            │                                  │
│  • Kube clusters         │            │  • Environments & Modules        │
│  • App proxies           │            │  • Entities (Helm charts)        │
│  • SSH access            │            │  • Products & Release Channels   │
│  • Identity & TLS certs  │            │  • Change Requests               │
└──────────────────────────┘            │  • ACR (Docker + Helm registry)  │
                                        └──────────────────────────────────┘

How it works

1. Local tools run directly on the developer's machine inside cube-agent. These handle authentication (Cognito browser login, API key storage), Docker builds, Helm chart packaging, kubeconfig merging, and app proxy tunnels.

2. Cloud tools are proxied from cube-agent to cube-cloud (FastAPI on AWS ECS) via MCP Streamable HTTP. Every request is authenticated with a Bearer API key validated against DynamoDB.

3. RBAC maps Cognito user groups to profiles. Each profile resolves to Apollo OAuth2 credentials stored in AWS Secrets Manager, scoping what the user can access.

4. Teleport access is provided by a tbot sidecar running alongside cube-cloud in the same ECS task. It uses IAM join to obtain short-lived certificates for Kubernetes clusters and app proxies — no tsh is needed on the developer's machine.

5. Apollo operations (environments, modules, entities, products, releases, change requests) go through a GraphQL API authenticated with per-profile OAuth2 client credentials.

Install

Requires uv (or pipx).

# Add to Claude Code
claude mcp add cube -- npx cube-mcp

Or run directly:

npx cube-mcp    # via Node (calls uvx under the hood)
uvx cube-mcp    # via uv directly

Getting Started

You: "Log me in"             → agent_login_browser (opens browser for Cognito login)
You: "Connect to staging"    → cube_cluster_login (merges kubeconfig)
You: "Show Cube status"      → cube_status

Tools

Auth

Tool	Description
agent_login_browser	Log in via browser (Cognito)
agent_login	Log in with an API key
agent_logout	Remove stored API key
agent_status	Check auth and connectivity

Kubernetes

Tool	Description
cube_list	List available Cube clusters
cube_status	Get node status for a cluster
cube_cluster_login	Get kubeconfig for a cluster (merges into ~/.kube/config)
kubectl_exec	Run kubectl commands (server-side)

Apps

Tool	Description
app_list	List Teleport apps
app_proxy	Start local proxy tunnel to an app
app_proxy_stop	Stop running proxies
app_proxy_status	Show proxy status

Build & Registry

Tool	Description
build_and_publish_to_apollo	Build Docker image, package chart, push to ACR, publish manifest
acr_get_token	Get Apollo Container Registry token
apollo_publish_manifest	Publish a manifest YAML

Apollo Environments

Tool	Description
list_environments	List/search Apollo environments
create_environment	Create a new environment with control plane
replicate_environment	Clone modules, entities, configs, and secrets
delete_environment	Delete an environment
install_entity	Install a Helm chart entity
uninstall_entity	Uninstall an entity
entity_health	Get entity health and activity status
plan_details	Get plan tasks, events, and error logs
update_entity_config	Update entity config overrides
enforce_entity_config	Force re-apply entity configuration
reset_environment_agents	Reset environment agents

Apollo Modules

Tool	Description
install_module	Install a module on an environment
uninstall_module	Uninstall a module
list_modules	List modules in an environment
update_module_variables	Update module variables

Apollo Secrets

Tool	Description
create_secret	Create a secret on an environment
update_secret	Update a secret value

Apollo Products & Release Channels

Tool	Description
list_products	List available products
compare_product_versions	Compare versions of a product
list_release_channels	List release channels
get_product_releases	Get releases for a product
add_product_to_release_channel	Add a product to a release channel
remove_product_from_release_channel	Remove a product from a release channel
set_label_on_product	Set a label on a product
remove_label_from_product	Remove a label from a product

Apollo Change Requests

Tool	Description
list_change_requests	List pending change requests
review_change_request	Approve or reject a change request

Local Development

# Install dependencies
uv sync --extra dev
uv pip install -e packages/cube-common -e packages/cube-cloud -e packages/cube-agent

# Run tests
uv run pytest packages/ -v

# Run cube-agent locally (for debugging)
uv run cube-agent

To test with Claude Code, point the MCP server at your local code:

claude mcp add cube-local -- uv run --directory /path/to/cube-mcp cube-agent

Reload after changes with /mcp in Claude Code.

Contributing

1. Create a branch
2. Make changes
3. Run uv run pytest packages/ -v
4. Push and open a PR — tests run automatically
5. Merge to main — auto-publishes to PyPI and npm, auto-deploys to ECS

Admin

See docs/admin.md for user management, RBAC, and profile configuration.