Getting started for teams

Run ClawQL as a shared MCP backend for your team: centralize Obsidian memory notes in object storage and wire observability so operators can see health, audit volume, and agent work traces.

Prerequisites: Helm Kubernetes (or Tier 1 Compose for a lab slice), Vault provider secrets synced via External Secrets Operator, and at least one shared bucket (R2, S3, or GCS).

What teams need

Architecture

  Teammates / agents                Shared backend
  ─────────────────                 ──────────────
  Cursor / Claude Desktop    ──►    clawql-mcp-http (Helm)
  clawql sync pull/push      ◄──►   Object storage bucket
                                    Memory/ + sources/ (synced)
                                    Vault KV → ESO → pod env
                                    Prometheus / Loki / Tempo / Langfuse

• Secrets (vault/providers.json, API tokens) stay local or in Vault — never in the sync bucket.
• memory.db is rebuilt per pod after pull; the Markdown in Memory/ is the shared source of truth.

1. Deploy the shared MCP backend

Helm (recommended for teams)

helm upgrade --install clawql ./charts/clawql-mcp \
  --namespace clawql \
  --create-namespace \
  --set envFromSecret=clawql-provider-env \
  --wait

Wire provider keys through HashiCorp Vault → External Secrets → envFromSecret. See Vault provider secrets and the Operations guide.

Local lab: make local-k8s-up on Docker Desktop — MCP at http://clawql-mcp.localhost/mcp, bundled Vault, Kyverno, ingress.

Solo dev with team bucket

Engineers can run npx clawql-mcp locally and use clawql sync pull before memory_recall and clawql sync push after memory_ingest — same bucket as the cluster. See Team vault sync.

2. Shared object storage for team memory

ClawQL syncs selected paths under ~/.ClawQL to a team prefix in object storage. Cloudflare R2 is the default provider (bundled stack); S3 and GCS (HMAC interop) are first-class peers.

What syncs

Kubernetes: teamSync Helm values

teamSync:
  enabled: true
  provider: r2 # r2 | s3 | gcs
  bucket: acme-clawql-team
  prefix: teams/engineering/
  autoPush: true # debounced push after memory_ingest
  autoPushDebounceMs: 30000
  autoPull: true # throttled pull before memory_recall
  autoPullMinMs: 60000
  autoPullOnStart: true
  r2:
    accountId: '<cloudflare-account-id>' # or cloudflareAccountId in provider secret

Credentials in Vault / envFromSecret (never in values.yaml):

helm upgrade --install clawql ./charts/clawql-mcp \
  --set envFromSecret=clawql-provider-env \
  --set teamSync.enabled=true \
  --set teamSync.bucket=acme-clawql-team \
  --set teamSync.prefix=teams/engineering/ \
  --set teamSync.autoPush=true \
  --set teamSync.autoPull=true

CLI (local machines)

clawql sync init --interactive
# provider: r2 (default), bucket, prefix

export CLAWQL_R2_ACCOUNT_ID="..."
export CLAWQL_SYNC_ACCESS_KEY_ID="..."
export CLAWQL_SYNC_SECRET_ACCESS_KEY="..."

clawql sync push    # upload Memory/ to team bucket
clawql sync pull    # download teammate changes
clawql sync status  # compare local vs remote

Auto sync env (MCP runtime): CLAWQL_SYNC_AUTO=1, CLAWQL_SYNC_AUTO_PULL=1 — see Team vault sync.

Full provider quick starts (R2, S3, GCS), conflict handling, and manifest details: Team vault sync.

3. Observability for team MCP

Operators need three signal types plus optional LLM work traces.

Metrics (Prometheus)

ClawQL exposes OpenMetrics at GET /metrics when CLAWQL_ENABLE_HTTP_METRICS=1 (default on HTTP transport).

Helm — scrape annotations (default, works with Istio sample Prometheus):

metrics:
  prometheusScrapeAnnotations:
    enabled: true
    path: /metrics

Helm — ServiceMonitor (kube-prometheus-stack):

metrics:
  serviceMonitor:
    enabled: true
    labels:
      release: kube-prometheus-stack

Key series today: clawql_audit_*, clawql_native_protocol_*. Import dashboards from docs/grafana/.

Verify:

kubectl -n clawql port-forward svc/clawql-mcp-http 8080:8080
curl -s localhost:8080/metrics | head

Audit → Loki

The MCP audit tool appends structured events. Push to Loki for team grep and Grafana panels:

CLAWQL_LOKI_PUSH_URL=http://loki:3100/loki/api/v1/push

See Audit tool & observability and Bring your own observability.

Infra traces (OTLP → Tempo)

CLAWQL_ENABLE_OTEL_TRACING=1
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_SERVICE_NAME=clawql-mcp

Lab stack: Docker Desktop observability — Prometheus, Loki, Tempo, Grafana, OTEL collector in one profile.

Work traces (Langfuse)

Langfuse is the default work-trace ledger for token savings and eval — opt out with CLAWQL_ENABLE_LANGFUSE=0. See ADR 0005 and Bundled observability.

Set LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST via Vault / envFromSecret.

Observability profiles

Index: Observability bundle.

4. Verify end-to-end

Run this checklist after Helm install + team sync + observability wiring:

# Health
kubectl -n clawql get pods
curl -s http://clawql-mcp.localhost/healthz

# Metrics
curl -s http://clawql-mcp.localhost/metrics | grep clawql_audit

# Team memory (from a machine with sync configured)
clawql sync status
clawql doctor

# MCP memory round-trip
# memory_ingest a test note → auto-push (if CLAWQL_SYNC_AUTO=1)
# Teammate: clawql sync pull → memory_recall with the new note

Grafana: import clawql-core-observability.json and clawql-idp-observability.json.

After pull: run clawql doctor or set CLAWQL_MEMORY_DB_SYNC_ON_RECALL=1 so memory.db reflects new Markdown.

Related

• Team vault sync — R2 / S3 / GCS reference, CLI, auto sync, Helm
• Local provider vault — ~/.ClawQL layout and secrets
• Deployment & Operations guide — upgrades, secrets, day-2
• Helm chart — full values.yaml reference
• Memory / Obsidian — memory_ingest / memory_recall