Cursor iOS + Cloud Agent

Use ClawQL from the Cursor iOS app by running Cloud Agents with stdio MCP on the agent VM and a team vault bucket (R2, S3, or GCS) for memory that survives across sessions.

Desktop contrast: Cursor on macOS/Windows can run npx clawql-mcp locally over stdio with ~/.ClawQL on disk. The iOS app has no local shell, no stdio MCP subprocess, and no persistent ~/.ClawQL on the phone — Cloud Agents provide the runtime.

Related: Agent setup prompt · Team vault sync · MCP clients

Architecture

  Cursor iOS app
        │
        ▼
  Cloud Agent VM (Cursor-managed)
  ├── stdio MCP: npx -p clawql-mcp clawql-mcp
  ├── CLAWQL_HOME=/home/ubuntu/.ClawQL  (ephemeral VM disk)
  └── memory_sync ◄──► object storage (R2 / S3 / GCS)
        │
        ▼
  Next Cloud Agent session (new VM) — pull same bucket prefix

• MCP runs inside the Cloud Agent VM, not on the phone.
• Memory/ Markdown is the durable source of truth; memory.db is rebuilt per VM.
• vault/providers.json (API tokens) stays on the VM or in Cursor Secrets — never in the sync bucket.

Prerequisites

1. Object-storage bucket with a team prefix (R2 quick start: team-vault-sync.md).
2. Cursor Cloud Agents enabled for your account (repo connected in the Cursor dashboard).
3. clawql-mcp on the agent VM — npx -p clawql-mcp resolves it at MCP startup (Node.js is preinstalled on Cloud Agent VMs).

One-time bucket setup can be done from a desktop machine with the ClawQL CLI:

clawql sync init --interactive
clawql sync push   # seed Memory/ from an existing ~/.ClawQL

1. Cursor dashboard secrets

Add these under Cursor → Settings → Cloud → Secrets (or your team's secret store). They are injected into every Cloud Agent run for the repo.

For S3 or GCS, use the credential variables from team-vault-sync.md instead of R2 keys.

Provider API tokens (GitHub, Slack, Cloudflare, etc.) also belong in Secrets — same keys as local clawql secrets set, loaded via CLAWQL_HOME / clawql.env. Do not put tokens in mcp.json or git.

2. Connect ClawQL MCP (stdio)

Cloud Agents use the repo's MCP configuration. Add .cursor/mcp.json (or enable the clawql server in the agent run UI):

{
  "mcpServers": {
    "clawql": {
      "command": "npx",
      "args": ["-p", "clawql-mcp", "clawql-mcp"],
      "env": {
        "CLAWQL_HOME": "/home/ubuntu/.ClawQL"
      }
    }
  }
}

CLAWQL_HOME in env can match the dashboard secret; dashboard secrets are also visible to the MCP child process.

On a desktop machine you can generate the same JSON:

npx -p clawql-mcp clawql mcp-config --write cursor

Enable the clawql MCP server when starting a Cloud Agent from iOS (same as desktop — the server must be toggled on per run if your client requires it).

3. Bootstrap the vault on the VM

The first Cloud Agent run creates an empty CLAWQL_HOME on VM disk. Choose one bootstrap path:

A. Pull existing team memory (recommended)

With sync secrets set, MCP auto-pull on start fetches Memory/ from the bucket. Or ask the agent to call:

{ "direction": "pull" }

via the memory_sync tool (see below).

B. Agent-guided init

Paste the agent setup prompt into a Cloud Agent run. The agent can run:

npx -p clawql-mcp clawql init --interactive

Provider secrets should come from Cursor Secrets, not interactive prompts, when possible.

C. Optional repo install hook

Teams can add .cursor/environment.json with an install script that runs clawql init, writes sync.json, or pre-installs clawql-mcp before the agent starts. Keep secrets out of the script — use dashboard Secrets only.

4. Session workflow (memory)

memory_sync replaces shell clawql sync push / pull on Cloud Agents (no reliance on clawql CLI in the agent shell). See team-vault-sync.md — memory_sync.

Auto sync (CLAWQL_SYNC_AUTO=1) debounces push after each memory_ingest; still call memory_sync at the end of important runs to flush immediately and reconcile conflicts.

5. Copy-paste prompt (iOS / Cloud Agent)

You are helping me use ClawQL from Cursor on iOS via a Cloud Agent.

Facts:
- MCP is stdio: npx -p clawql-mcp clawql-mcp with CLAWQL_HOME on the agent VM.
- There is no local ~/.ClawQL on my phone; durable memory lives in object storage (R2/S3/GCS).
- Sync credentials are in Cursor Cloud Secrets (CLAWQL_SYNC_* + CLAWQL_R2_ACCOUNT_ID).
- Provider API tokens are in Secrets or CLAWQL_HOME/vault/providers.json — never in mcp.json or git.

Workflow:
1. memory_recall with a concrete query at the start of non-trivial work.
2. search → execute for API operations; memory_ingest for durable outcomes.
3. Before ending the run: memory_sync { "direction": "auto" } to pull then push the team bucket.

If sync is not configured, say so and list which CLAWQL_SYNC_* secrets are missing.
Do not invent API responses. On auth failure, point to vault/providers.json or docs/providers/*-onboarding.md.

Docs: team vault sync and cursor-ios-cloud-agent getting-started guides in this repo.

Troubleshooting

Related

• Team vault sync — bucket providers, Helm teamSync, CLI reference
• Agent setup prompt — vault-first desktop onboarding
• Local provider vault — vault/providers.json shape
• Memory / Obsidian — vault layout and wikilinks