cube-mcp

MCP server for EdgescaleAI Cube management and Apollo deployments.

New owner / inheriting this repo? Jump to Operations & Ownership. The two runbooks you need are docs/admin.md (full RBAC + infra reference) and docs/adding-new-user.md (onboard a teammate end-to-end). Both are written so you can point Claude Code at them and have it execute the steps for you.

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

Kubernetes

Apps

Build & Registry

Apollo Environments

Apollo Modules

Apollo Secrets

Apollo Products & Release Channels

Apollo Change Requests

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

Operations & Ownership

This section exists so anyone inheriting cube-mcp can run it end-to-end without tribal knowledge. If something here is wrong or missing, fix it in this README — don't keep the truth in your head.

Runbooks (point Claude Code at these)

These docs are written in runbook style — open Claude Code in this repo and ask it to "follow docs/adding-new-user.md to add alice@example.com to the lear-dev group" and it will execute the AWS CLI calls itself.

Where AWS resources live

Everything is in AWS account 992382448282, region us-west-2. All resources are managed by Terraform in infra/terraform/ — change them there, not in the console.

Outside AWS:

• Teleport: edgescaleai.teleport.sh — bot is cube-mcp-bot, joins via IAM. See docs/admin.md §4.
• Apollo: edgescaleai.palantirapollo.com — OAuth2 credentials per profile, stored in Secrets Manager.
• PyPI / npm: auto-published from main via CI (scripts/ + GitHub Actions). The npm shim under npm/ is a thin wrapper that shells to uvx cube-mcp.

CI/CD pipelines

All deploys go through GitHub Actions in .github/workflows/. AWS auth uses OIDC — no long-lived AWS keys are stored in GitHub.

OIDC role for all AWS-touching jobs: arn:aws:iam::992382448282:role/github-actions.

Required CI secrets

Stored as GitHub repo secrets. To rotate any of these, generate a new value at the source and update via gh secret set <NAME> (or the repo Settings → Secrets UI).

AWS credentials are not stored as secrets — deploy.yml/deploy-dev.yml assume arn:aws:iam::992382448282:role/github-actions via OIDC. To grant a new repo or change permissions, update that role's trust policy and inline policies in AWS IAM.

Terraform state

Stored in S3, no DynamoDB lock table currently configured (single-writer assumption — CI is the only applier).

Local apply (only if you really need to bypass CI):

cd infra/terraform
terraform init                                                    # prod
terraform init -backend-config="key=cube-cloud-dev/terraform.tfstate"  # dev
terraform plan

The S3 bucket has versioning enabled, so a corrupt state file can be rolled back to a previous version via the AWS console.

Dev environment

A parallel stack exists in the same AWS account for testing infra changes before merging to main.

Push to dev-main to validate, then PR dev-main → main (or cherry-pick) for prod.

Versioning & releases

• Scheme: patch-bump only, automated. publish.yml reads pyproject.toml, increments the patch, writes it back to both pyproject.toml and npm/package.json, commits as github-actions[bot], and tags vX.Y.Z.
• Major/minor bumps: edit pyproject.toml manually in a PR. The next merge to main that touches src/ / npm/ / pyproject.toml will publish from there.
• PyPI ↔ npm sync: the same version number is used for both packages. The npm/ shim is a thin wrapper that shells to uvx cube-mcp@<version> (see scripts/sync_version.py).
• What "main" means for users: every merge that touches the publish paths ships to PyPI + npm within minutes. There is no staging release.

Rollback playbook

Monitoring & alerting

Status: not yet configured. No CloudWatch alarms, SNS topics, Sentry, or paging are set up at the time of this handoff. The only observability is CloudWatch Logs (/ecs/cube-mcp-prod) and the ECS service's own task health.

Day-to-day debugging:

# Live tail prod logs (cube-cloud + tbot)
aws logs tail /ecs/cube-mcp-prod --follow --region us-west-2

# Filter to just tbot
aws logs tail /ecs/cube-mcp-prod --filter-pattern "tbot" --follow

# Service health
aws ecs describe-services \
  --cluster cube-mcp-prod-cluster \
  --services cube-mcp-prod-service \
  --query 'services[0].{running:runningCount,desired:desiredCount,events:events[0:5]}'

Recommended additions for the next owner (none of these exist yet):

• CloudWatch alarm on ECS service RunningTaskCount < 1 → SNS → email/PagerDuty.
• ALB 5xx alarm on the listener.
• DynamoDB throttling alarm on cube-mcp-prod-api-keys.
• Synthetic check that runs agent_login_browser end-to-end weekly.

Stakeholders & contacts

TODO(owner): Vinayak (departing) is the only person with full context on these. Fill these in before he leaves so the next owner has someone to call.

Cost & billing

TODO(owner): Add rough monthly run-rate and the account that gets billed.

• AWS (account 992382448282): TODO — typical monthly spend, biggest line items, who pays the invoice.
• Teleport (edgescaleai.teleport.sh): TODO — plan tier, seat count, billing contact.
• Apollo (edgescaleai.palantirapollo.com): TODO — Palantir contract reference, who renews.
• Domain (edgescaleai-cube.com): TODO — registrar, expiry date, who has the login.
• PyPI / npm: free tiers, no recurring cost.

If costs need to be cut quickly: the dev ECS service (cube-mcp-dev-service) can be scaled to zero with no user impact.

Access & disaster recovery

Known tech debt / planned work

Update this list as you ship or de-scope items so the next owner sees current state, not folklore.

• Phase 2 RBAC: per-role tbot identity outputs are wired up but only admin profile actually has scoped Apollo creds. Lear/Conagra/Palantir profiles still resolve to admin Apollo credentials at runtime — see the note in docs/admin.md §3 ("Currently defined groups"). Scoping these is the biggest open item.
• ECR :latest-only tagging makes ECS rollback awkward (see Rollback playbook). Tag images with the git SHA in deploy.yml.
• No alerting. See Monitoring section.
• Teleport role management is manual tctl. The future plan is the Teleport Terraform provider — see docs/admin.md → Future.
• No DynamoDB lock on Terraform state. Acceptable while CI is the only applier; add a lock table if local applies become routine.
• Cognito drift: esaiadmin group. Surfaced in #93. The prod Cognito pool has an esaiadmin group that isn't defined in infra/terraform/cognito.tf — it was created in the console. Either terraform import it or delete it; don't leave it as drift.
• Stale claim in docs/rbac-architecture.md line ~134 that "Cognito user → profile assignment is not yet implemented." This contradicts docs/admin.md and login_flow.py (the groups[0] resolution has shipped). Fix in a docs-only PR — also flagged in #93.
• TODO(owner): anything else in flight at handoff time.

First-day checklist for a new owner

1. Read docs/admin.md end-to-end. Then run agent_login_browser yourself so you've experienced the user flow.
2. Get console access to AWS account 992382448282 (us-west-2) with permissions for Cognito, DynamoDB, Secrets Manager, ECS, IAM, and CloudWatch Logs.
3. Get Teleport admin (tctl) on edgescaleai.teleport.sh — needed to manage the cube-mcp-bot and add roles. Ask the person listed in Stakeholders & contacts.
4. Get Apollo admin on edgescaleai.palantirapollo.com — needed to issue per-profile OAuth2 credentials when adding new tenants.
5. Install cube-admin locally for API key management: uv pip install -e packages/cube-admin. This package is internal-only and must never be published.
6. Verify CI is healthy and you can rotate every secret in Required CI secrets. Push a no-op commit to dev-main to confirm deploy-dev.yml succeeds end-to-end against the dev stack.
7. Replace every TODO(owner) in this README — Stakeholders, Cost, Access & DR, Tech debt. If you can't fill one in, write down who you asked and what they said. Don't leave them blank.

Common ops tasks

• Add a user: docs/adding-new-user.md.
• Add a new tenant / role: docs/admin.md → Creating a new role / profile. Six steps — Cognito group, SM secret, Teleport role, bot role grant, tbot output, merge.
• Revoke access: docs/admin.md → Revoking access.
• Manage API keys: cube-admin keys {create,list,revoke} — see docs/admin.md → Managing API keys with cube-admin.
• Debug a failing tool call: check aws logs tail /ecs/cube-mcp-prod --follow for the cube-cloud and tbot containers.

Repo layout cheatsheet

packages/
  cube-agent/    # Local MCP server (npx cube-mcp entrypoint)
  cube-cloud/    # FastAPI service on ECS — auth, RBAC, Apollo, Teleport relay
  cube-common/   # Shared types and helpers
  cube-admin/    # Internal-only API key CLI — DO NOT PUBLISH
infra/
  terraform/     # All AWS resources
  tbot/          # tbot Dockerfile, entrypoint, prod config
docs/            # Runbooks (start here)
resources/       # User-facing reference docs
npm/             # npm shim that calls uvx cube-mcp
scripts/         # Release / publish helpers