Skip to main content
ClawQL

Onyx knowledge_search_onyx

The optional knowledge_search_onyx MCP tool queries your Onyx index via POST /search/send-search-message. It is a thin wrapper over the same execute path as operation onyx::onyx_send_search_message when the onyx bundled spec is in the merge — so you get typed parameters (query, num_hits, …) without hand-building the Onyx JSON each time.

  • Enable: CLAWQL_ENABLE_ONYX=1 (or true / yes).
  • Spec: The loaded merge must include onyx (default all-providers, or add onyx to CLAWQL_BUNDLED_PROVIDERS, or CLAWQL_PROVIDER=onyx for Onyx-only).
  • Connectivity: ONYX_BASE_URL = HTTP API root (often ends with /api). Auth: ONYX_API_TOKEN or CLAWQL_ONYX_API_TOKEN as Bearer, or CLAWQL_PROVIDER_AUTH_JSON with an onyx key.
  • Provider matrix: default bundle positioning and auth fields live in one place: Bundled specs.

Learn walkthrough (what Onyx is, connector breadth, ACLs, vault pairing): Onyx enterprise search (knowledge_search_onyx).

Canonical guide (setup, wrapper vs execute, examples, errors, memory_ingest / notify): onyx-knowledge-tool.md · mcp-tools.md § knowledge_search_onyx · issue #118.

Topology and deployment pointers

  • Flink connector sync into Onyx index: tracked in #119. For full architecture, security boundaries, Helm values, and operations runbook, see Flink Onyx sync.
  • Full-stack deployment pointers: the Helm chart can now co-deploy document pipeline + stores topology; see Helm and issue #113.
  • Optional case study context: docs-site operational workflows and postmortems are under Case studies.

Quick examples

Minimal retrieval:

{
  "query": "What is our data retention policy for EU customers?"
}

Limit hits and trim top-level JSON keys (adjust fields to match your Onyx response):

{
  "query": "runbook kubernetes cluster upgrade",
  "num_hits": 8,
  "include_content": true,
  "fields": ["query", "documents"]
}

Equivalent execute (merged onyx label):

{
  "operationId": "onyx::onyx_send_search_message",
  "args": {
    "search_query": "deployment runbook kubernetes",
    "num_hits": 10,
    "include_content": true,
    "stream": false
  }
}

Vault and Slack

  • After retrieval, use memory_ingest to persist a short summary and redacted hit list so memory_recall can surface it in later sessions — see vault memory.
  • Use optional notify to post completion signals with links — Slack notify.

Tests

Repo tests: src/knowledge-search-onyx.test.ts, src/server.test.ts (tool registered when CLAWQL_ENABLE_ONYX=1).

See Tools for how knowledge_search_onyx fits alongside search, execute, vault tools, cache, audit, and notify.