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_depthsent toekos_impact, whose parameter ismax_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_retrieveclaims carrydisputed: trueand point toekos_conflicts. - Review decisions and sign-offs (
ekos review …,ekos signoff approve|revoke), EKOS Migrate'sapprove/reject, session memory'sreview,ekos semantics confirm|reject|edit,ekos import linkml,ekos import ossie,ekos conflicts resolveandekos treasury confirm|rejecthave no MCP equivalent, by design.
The server's own tools/list output, with each tool's input schema, is authoritative.