ClawQL

ClawQL is an MCP server for API discovery and execution with a token-efficient search -> execute workflow over OpenAPI, Google Discovery, and optional native GraphQL and gRPC sources (see CLAWQL_GRAPHQL_URL / CLAWQL_GRAPHQL_SOURCES / CLAWQL_GRPC_SOURCES in .env.example and ADR 0002). GraphQL-only vendors (e.g. Linear) need no OpenAPI spec: use CLAWQL_PROVIDER=linear (bundled SDL under providers/linear/ + LINEAR_API_KEY), or point CLAWQL_GRAPHQL_URL at their HTTP endpoint and auth headers, or load search from CLAWQL_GRAPHQL_SCHEMA_PATH / CLAWQL_GRAPHQL_INTROSPECTION_PATH (or per-source schemaPath / introspectionPath) when upstream introspection is disabled — without CLAWQL_SPEC_* / CLAWQL_PROVIDER, the default bundled REST specs are not loaded.

What You Get

Feature tiers (aligned with the architecture diagram — details in docs/readme/configuration.md):

• ClawQL Core (always on — no opt-out): search, execute, audit, cache — same band in the diagram; ring-buffer semantics for audit and LRU semantics for cache in docs/mcp/enterprise-mcp-tools.md and docs/mcp/cache-tool.md.
• Default on — opt out: memory_ingest / memory_recall, and the document stack (ingest_external_knowledge, plus knowledge_search_onyx when CLAWQL_ENABLE_ONYX=1). Use CLAWQL_ENABLE_MEMORY=0 or CLAWQL_ENABLE_DOCUMENTS=0 to hide; vault path still required for real disk I/O on memory / ingest.
• Default off — opt in: sandbox_exec (CLAWQL_ENABLE_SANDBOX=1), schedule, notify, knowledge_search_onyx (needs CLAWQL_ENABLE_ONYX=1 and documents on), ouroboros_* — see docs/mcp/mcp-tools.md. When enabled, CLAWQL_SANDBOX_BACKEND: omit = bridge; auto = Seatbelt → Docker → bridge.
• Stdio and HTTP MCP server modes
• Bundled provider specs for offline lookup and multi-provider workflows

Primary package: clawql-mcp
Repo: https://github.com/danielsmithdevelopment/ClawQL

Quick Start

Install:

npm install clawql-mcp

Run with bundled providers:

CLAWQL_PROVIDER=all-providers npx clawql-mcp

Then configure your MCP client (Cursor/Claude Desktop) to connect.

Documentation Map

Top-level docs index: docs/README.md

Start here

• Getting started: docs/readme/getting-started.md
• Configuration and env precedence: docs/readme/configuration.md
• Deployment and client config: docs/readme/deployment.md (Kubernetes list links docs/deployment/docker-desktop-istio-observability.md for Istio + Prometheus/Grafana/Tempo/Kiali/OTel on Docker Desktop)
• Benchmarks and case studies: docs/readme/benchmarks.md
• Development notes: docs/readme/development.md
• Tool workflow skills: docs/skills/README.md

Core references

• MCP tools and examples: docs/mcp/mcp-tools.md
• Workflow recipes: docs/recipes/README.md
• Memory and vault workflows: docs/memory/memory-obsidian.md
• Cache tool: docs/mcp/cache-tool.md
• Enterprise MCP notes (audit threat model, future metrics/governance): docs/mcp/enterprise-mcp-tools.md
• Slack notify tool: docs/mcp/notify-tool.md
• Onyx knowledge tool: docs/mcp/onyx-knowledge-tool.md
• Ouroboros package and integration: docs/ouroboros/clawql-ouroboros.md

Deployments

• Docker: docker/README.md
• Cloud Run: docs/deployment/deploy-cloud-run.md
• Kubernetes: docs/deployment/deploy-k8s.md
• Helm chart: docs/deployment/helm.md
• Tailscale / Headscale (beginner guide): docs/deployment/tailscale-and-headscale-for-clawql.md (website /tailscale)
• Headscale runbook + ACL starter: docs/deployment/headscale-tailnet.md, docs/deployment/headscale-acls-clawql.hujson

Security and supply chain

• Security overview and shipped controls: docs/security/README.md
• Golden image pipeline (CI → scan → push → sign → Kyverno enforcement): docs/security/golden-image-pipeline.md
• Defense in depth reference: docs/security/clawql-security-defense-in-depth.md
• Engineering deliverables matrix (shipped/partial/planned): docs/security/clawql-security-defense-deliverables.md
• Docker SBOM/sign/scan operator notes: docker/README.md
• npm publish hardening (pack → scan → publish, provenance): docs/security/npm-supply-chain.md
• Deploy-time image signature enforcement (admission / Kyverno): docs/security/image-signature-enforcement.md

Providers and specs

• Provider matrix and presets: providers/README.md
• Google Discovery helpers: docs/providers/google-apis-lookup.md

Architecture (Short Version)

1. Agent calls search to discover relevant operations without loading entire specs into prompt context.
2. Agent calls execute with operation details.
3. For OpenAPI/Discovery operations: in single-spec mode, ClawQL prefers an internal OpenAPI-to-GraphQL path (REST fallback on failure); in multi-spec mode, execute uses REST per owning spec.
4. For native operations (when configured): execute calls HTTP GraphQL or gRPC unary directly — same search index, routed by operation metadata — see ADR 0002.

Notes

• Core (search, execute, audit, cache) has no opt-out — no CLAWQL_ENABLE_* gate for those tools.
• A writable CLAWQL_OBSIDIAN_VAULT_PATH is required to read/write the vault for memory_* and bulk ingest_external_knowledge.
• For full environment variable details, see .env.example and docs/mcp/mcp-tools.md.