Concepts

ClawQL connects agents to HTTP and gRPC APIs (OpenAPI/Discovery by default, optional native GraphQL and gRPC) through a thin MCP surface, without asking models to ingest full OpenAPI documents up front.

Architecture

Agent
  └─▶ MCP Server  (stdio, Streamable HTTP, or optional MCP gRPC)
        ├─▶ search tool  ──▶ In-memory operation index
        └─▶ execute tool  ──▶ OpenAPI→GraphQL (single-spec) / REST (multi) / native HTTP GraphQL / gRPC

Transports: stdio and Streamable HTTP are the usual paths; MCP over gRPC (protobuf model_context_protocol.Mcp) is optional and uses the same tool registration via mcp-grpc-transport—see Deployment. (This is the MCP wire protocol, distinct from native gRPC API sources in CLAWQL_GRPC_SOURCES.)

In multi-spec mode, search uses one merged index while execute routes OpenAPI/Discovery operations to the correct spec (REST). Native GraphQL/gRPC operations use their own clients when configured.

Feature tiers (what is on by default)

Aligned with the layer diagram and configuration § Feature tiers:

1. ClawQL Core (always on — no opt-out) — search, execute, audit, cache (same band as in the diagram; no env gate).
2. Default on — opt out — memory_ingest / memory_recall, Documents (ingest_external_knowledge, knowledge_search_onyx when CLAWQL_ENABLE_ONYX is set). Use CLAWQL_ENABLE_MEMORY or CLAWQL_ENABLE_DOCUMENTS set to 0 to hide.
3. Default off — opt in — sandbox_exec (CLAWQL_ENABLE_SANDBOX=1), schedule, notify, hitl_enqueue_label_studio (CLAWQL_ENABLE_HITL_LABEL_STUDIO=1 — HITL — Label Studio), ouroboros_*, and the knowledge_search_onyx wrapper (CLAWQL_ENABLE_ONYX, with Documents still enabled). sandbox_exec needs backend env (sandbox bridge, Seatbelt, or Docker) once registered.

Core is search, execute, audit, cache — no opt-out.

Design principles

1. search first, execute second — discover operationId and parameters without loading the entire spec into context.
2. OpenAPI→GraphQL is internal — for REST-backed operations, agents do not hand-author GraphQL; the server builds precise selections. Native GraphQL endpoints still use GraphQL over HTTP, but execute builds the document from introspection-shaped metadata.
3. Single index — OpenAPI/Discovery plus optional native sources contribute to one search result set (spec configuration).

Ouroboros (library + optional MCP tools)

For multi-step workflows that iterate on a structured spec (acceptance criteria, ontology fields) until convergence, ClawQL’s repo includes the TypeScript clawql-ouroboros package — see Ouroboros library and clawql-ouroboros.md. It complements the search → execute pattern: executors inside the loop can still call the same APIs through your integration layer. With CLAWQL_ENABLE_OUROBOROS=1, clawql-mcp registers three ouroboros_* MCP tools; without the flag, use the library from your own process.

How the two phases save tokens

Benchmarks in the repo compare planning-context size (merged specs on disk vs workflow/search artifacts) to illustrate scale—not a literal per-call “API bill” from a model provider. See Benchmarks.

Ephemeral cache vs vault memory

The cache tool (ClawQL Core, always registered) holds short-lived key/value state in the MCP process (LRU, no disk). The audit tool (always registered) holds short-lived structured events in-process (ring buffer, no disk) — not compliance-grade alone; see enterprise-mcp-tools.md. The optional notify tool (CLAWQL_ENABLE_NOTIFY) sends Slack messages via chat.postMessage (outbound HTTP to Slack, not vault storage) — Slack notify, notify-tool.md. The optional hitl_enqueue_label_studio tool (CLAWQL_ENABLE_HITL_LABEL_STUDIO) enqueues tasks in Label Studio and accepts POST /hitl/label-studio/webhook callbacks — HITL — Label Studio, hitl-label-studio.md (#228). The optional knowledge_search_onyx tool (CLAWQL_ENABLE_ONYX) calls your Onyx HTTP API for semantic document search (enterprise index, not the vault) — Onyx knowledge search, onyx-knowledge-tool.md. memory_ingest / memory_recall use your Obsidian vault (and optional memory.db) for durable notes and graph recall. Do not confuse them: use Session cache for scratch data; use the vault tools when the user expects persisted knowledge. See cache-tool.md.