Skip to content
ClawQL

Optional MCP tools

ClawQL Core always registers search, execute, audit, and cache. Everything in this guide is optional — enable per tool with CLAWQL_ENABLE_* env vars. Use this page to pick the right tool, compose workflows, and jump to deep-dive Learn modules.

Hub index: Optional tools reference · Full API: MCP tools · Feature tiers: Configuration

Core vs optional (quick map)

Always on (Core) Optional (this guide)
search, execute schedule, notify, sandbox_exec, knowledge_search_onyx, …
audit, cache memory_ingest / memory_recall (default on — see Memory)
hitl_enqueue_label_studio (planned full plugin)

audit and cache are Core but often taught here because operators enable Loki, schedule, and vault workflows around them.

Enablement cheat sheet

Tool / area Enable Prerequisites
Schedule CLAWQL_ENABLE_SCHEDULE=1 SQLite job store; URL allowlist for synthetics
Notify CLAWQL_ENABLE_NOTIFY=1 Slack in merged spec / CLAWQL_SLACK_*
Schedule → Slack CLAWQL_SCHEDULE_NOTIFY_CHANNEL + CLAWQL_SCHEDULE_NOTIFY_ON_FAILURE=1 Notify enabled
Onyx search CLAWQL_ENABLE_ONYX=1 Enterprise Onyx index + ACL
Sandbox CLAWQL_ENABLE_SANDBOX=1 Kata / Docker / Seatbelt harness
Memory default on; disable with plugin config Obsidian vault path
Audit → Loki CLAWQL_LOKI_PUSH_URL Loki push endpoint (no extra tool flag)

Restart the MCP server after changing flags. Confirm with Tools or search for the tool name in your client’s tool list.

Pick the right tool

Your goal Start here Deep dive
Scratch state between chats cache Cache handoff
Durable notes + graph recall memory_* clawql-memory
Live session breadcrumbs audit Audit & observability
Cron / HTTP synthetics schedule Schedule & notify
Slack milestones / paging notify Schedule & notify
Enterprise semantic search knowledge_search_onyx Onyx search
Run untrusted code safely sandbox_exec Sandbox exec
Human review queues HITL / Label Studio HITL — Label Studio
Import URLs/Markdown to vault ingest_external_knowledge External ingest

Composed workflows (recipes)

1. Probe → page humans

schedule (synthetic) ──fail──► built-in Slack notify OR agent notify
  1. CLAWQL_ENABLE_SCHEDULE=1 + CLAWQL_ENABLE_NOTIFY=1
  2. Create job with schedule create; validate with trigger + dry_run: true
  3. Set CLAWQL_SCHEDULE_NOTIFY_ON_FAILURE=1 for automatic posts, or call notify yourself for richer Block Kit messages

Details: Schedule & notify workflows.

2. Execute → audit → vault

execute ──► audit.append ──► memory_ingest (summary)

Use correlationId in audit to thread a multi-step run. For compliance-grade trails, add Audit Trail WORM — the in-process audit ring is not legal hold by itself.

3. Search → execute → cache handoff

search ──► execute ──► cache.set ──► (new chat) cache.get

Keeps planning context small; see Cache handoff.

4. Onyx evidence → execute

knowledge_search_onyx ──► execute (with citations in summary)

Ground regulated workflows before mutating upstream systems: Onyx enterprise search.

5. Sandbox → notify on failure

sandbox_exec ──► notify (thread_ts for incident channel)

Pair with Panguard enforcement so only approved tools run in production.

Observability stack (optional tools + platform)

Layer Tool / path
Metrics GET /metrics — clawql_audit_* counters
Logs CLAWQL_LOKI_PUSH_URL on audit.append
Traces OTel → Tempo (Docker Desktop lab)
Immutable Audit Trail WORM (separate from audit ring)

Walkthrough: Audit tool & observability.

Safety habits

  • Redact secrets in audit.summary and notify.text — exports are production data.
  • Allowlist synthetic probe URLs (CLAWQL_SCHEDULE_URL_ALLOWLIST_PREFIXES).
  • Fail closed on sandbox and Panguard paths — do not disable enforcement to “unblock” agents.
  • Prefer dry_run: true on schedule and external ingest before live jobs.

Troubleshooting

Symptom Fix
Tool missing in client Env flag off or wrong MCP process — check Configuration
notify auth error Slack token / merged spec provider
Schedule never fires Worker poll CLAWQL_SCHEDULE_POLL_MS; job enabled
Onyx empty results ACL + index connector; CLAWQL_ENABLE_ONYX=1
Audit buffer empty after restart Expected — enable Loki or memory_ingest for durability

Module index (deep dives)