EKOSdocs
Docs / Reference Operate

MCP Tools

Every tool the ekos MCP server exposes, with purpose and access level.

A server with the default configuration lists 22 tools. Listed says when a tool is offered; Scoped says whether a reader with a restricting read scope may call it (the others are refused for such a reader, each for a stated reason).

Tool Purpose Access Listed Scoped
ekos_search Full-text search over objects (names, kinds, excerpts). query, limit (default 20, max 100), mode lexical/vector/hybrid. Trailing * = prefix. Use 2–3 keywords read always yes
ekos_query Structured answer — fact lookup and named graph traversal; typed atomic claims with location and analyzer; a claim about a disputed attribute carries disputed: true; no LLM read always yes
ekos_retrieve Inspect the compiled Query Plan, the EvidenceSet and query understanding; no LLM read always yes
ekos_ekl Run an Enterprise Knowledge Language query read always yes
ekos_state Full state of one object: relationships and evidence, and its open_conflicts; at (RFC 3339) for historical state read always yes
ekos_neighborhood BFS from an object: depth 0–3 (default 1), max_objects 1–5000 (default 500); sets truncated: true when it stops early read always yes
ekos_dependents Incoming edges — what depends on this read always yes
ekos_impact Transitive impact, directional, optional relationship-kind filter; max_hops default 5, at most 20 read always yes
ekos_diff Objects and relationships written in a time window read always yes
ekos_graph_export Whole graph in one call; filters and aggregate super-nodes read always yes
ekos_status Entries, objects, relationships, ledger path, and a freshness block saying whether the ledger still matches the source. While it does not, read tools add a one-line note to their result read always no
ekos_audit Write history of one object/relationship with run, stage and source artifact read always no
ekos_transformation_explain Walk a Pentaho/SQL transformation pipeline with evidence per step; max_hops default 50, at most 200 read always no
ekos_transformation_diff Compare two pipelines; added/removed sources, filters, joins, aggregations; max_hops default 50, at most 200 read always no
ekos_architecture_evaluate Deterministic completeness / evidence-coverage score read always no
ekos_architecture_drift Crate roles whose classification changed over time read always no
ekos_architecture_diff Semantic architecture diff between two points in time read always no
ekos_identity_review Confirm or reject a candidate identity match (SameAs); optional reviewer, note. A payment approval (AuthorizedBy) is refused: a person uses ekos treasury confirm|reject write (appends an event) always no
ekos_architecture_review Confirm or reject an LLM-classified crate role; optional reviewer, note write (appends an event) always no
ekos_ossie_export The compiled schema as an Apache Ossie semantic model: datasets with typed fields and keys, relationships, business meanings with their review status, metrics from Ossie files in the sources. status (confirmed default, hypothesis, all), database, match, format (json/yaml), max_datasets (default 50, max 500) — on main (RFC 0245) read always yes
ekos_signoff_status Where the project stands in the seven-step operator workflow, and whether a person has signed off each review subject (scope, pii, conflicts, identity, write-behaviour, glossary): valid, stale, revoked or none, with item and blocking counts. No arguments (RFC 0213) read always no
ekos_conflicts Where sources disagree about one fact: every claim with file and line, what EKOS kept, the decision if any (RFC 0172). subject, status (open default, resolved, dismissed, all), limit (default 20, max 100) read [conflicts] (on by default) no
ekos_xref_check Cross-reference integrity (RFC 0233): references that resolve to nothing or to several objects, dependency cycles, unused tables, SQL routine reachability, from the index the last commit wrote. name resolves one table, view or routine name now — use it before writing SQL or code against a name. subject, scope (cross-system/all), min_confidence, limit (default 20, max 200) read [xref] (on by default) no
ekos_clickhouse_query Live NL-to-SQL over a compiled ClickHouse schema; a single validated SELECT only; each call recorded as an evidence/event pair gated, writes its audit event [clickhouse] enable-mcp-query = true no
ekos_session_note Record an agent note in the session inbox file (RFC 0151); opens no ledger handle inbox only [session-memory] no
ekos_session_recall Notes from earlier sessions, each with its tier and staleness verdict read [session-memory] no
ekos_session_brief Token-budgeted brief of relevant notes in an untrusted envelope read [session-memory] no
ekos_semantics_lookup What a term, table, column or code value means (RFC 0170): definition, evidence, review status in words; rejected items left out unless include_rejected; no_semantics_found when nothing matches read [semantics] no
ekos_semantics_gaps What is not known: unexplained codes, undocumented concepts, conflicts read [semantics] no

Extension builds add tools (for example the binary-recovery tools ekos_binary_explain and ekos_binary_migration_check). An extension tool is refused under a restricting scope unless the extension declares it scoped.

Through the console's MCP gateway (POST /mcp/<tenant>/<project>) a call needs the caller's role: the two review tools need the review right, which an API token never has; ekos_session_note needs operator; every other tool needs read.

Argument rules

  • Unknown argument names are refused with a JSON-RPC error that names the tool's declared parameters. A misspelled parameter (for example max_depth sent to ekos_impact, whose parameter is max_hops) used to be silently ignored, which ran the tool at its default depth.
  • Numeric bounds are enforced. A value that is out of range or of the wrong type is an error, never silently clamped.
  • A traversal that stops at its object cap says so with truncated: true. A truncated graph is partial.
  • A disputed fact is never handed over as settled: ekos_query / ekos_retrieve claims carry disputed: true and point to ekos_conflicts.
  • Review decisions and sign-offs (ekos review …, ekos signoff approve|revoke), EKOS Migrate's approve/reject, session memory's review, ekos semantics confirm|reject|edit, ekos import linkml, ekos import ossie, ekos conflicts resolve and ekos treasury confirm|reject have no MCP equivalent, by design.

The server's own tools/list output, with each tool's input schema, is authoritative.