Concepts
ClawQL connects agents to REST-shaped APIs through a thin MCP surface, without asking models to ingest full OpenAPI documents up front.
Architecture
Agent
└─▶ MCP Server (stdio, Streamable HTTP, or optional gRPC)
├─▶ search tool ──▶ In-memory spec index
└─▶ execute tool ──▶ GraphQL client (single-spec)
└─▶ GraphQL (in-process, single-spec)
└─▶ Your REST API
Transports: stdio and Streamable HTTP are the usual paths; gRPC (protobuf model_context_protocol.Mcp) is optional and uses the same tool registration via mcp-grpc-transport—see Deployment.
In multi-spec mode, search uses one merged index while execute routes each operation to the correct spec (REST).
Design principles
searchfirst,executesecond — discoveroperationIdand parameters without loading the entire spec into context.- GraphQL is internal — agents never write GraphQL; the server builds precise selections to keep tool outputs small.
- Single source of truth — the index and execution map derive from the same loaded OpenAPI/Discovery documents.
How the two phases save tokens
| Phase 1 — planning | Phase 2 — execution | |
|---|---|---|
| Mechanism | search + in-memory index instead of pasting full specs | Internal GraphQL projection (when available) vs fat REST JSON |
| Typical win | Input: huge spec text → short ranked hits | Output: smaller structured payloads returned to the model |
| Tradeoff | — | Small extra input for the internal query + variables |
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 optional cache tool (CLAWQL_ENABLE_CACHE) holds short-lived key/value state in the MCP process (LRU, no disk). The optional audit tool (CLAWQL_ENABLE_AUDIT) holds short-lived structured events in-process (ring buffer, no disk) — not compliance-grade alone; see enterprise-mcp-tools.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.