EKOSdocs
Docs / Usage Build

MCP

Expose the ledger read-only to agents over stdio, TCP or Streamable HTTP.

ekos mcp serve --workspace /path/to/workspace              # stdio
ekos mcp serve --workspace DIR --tcp 127.0.0.1:7331         # NDJSON JSON-RPC 2.0
ekos mcp serve --workspace DIR --http 127.0.0.1:8080        # POST /mcp
ekos --project shop mcp serve                               # a project in the EKOS home
ekos mcp serve --workspace DIR --read-scope scope.json      # only what the scope allows

Almost every tool goes through the read-only Runtime. The exceptions:

  • ekos_identity_review and ekos_architecture_review append a review event citing evidence;
  • the gated ekos_clickhouse_query (off by default) records each live query it runs;
  • the opt-in ekos_session_note writes only its inbox file, never the ledger.

Read-only tools that report review and integrity state — ekos_conflicts, ekos_signoff_status and ekos_xref_check (the last two since v1.2.0) — can show a decision but never make one: sign-offs, conflict resolutions and semantics confirmations are human-only. The opt-in [semantics] tools ekos_semantics_lookup and ekos_semantics_gaps are read-only too. Unknown argument names are refused. Tool list and arguments: MCP Tools. Setup: Connect Your AI Agent.

Under a restricting read scope, only the tools that read through the store are served; the rest are refused with a reason.

--workspace resolves that directory's ekos.toml when --config is not given. Precedence: --config, then EKOS_CONFIG, then the workspace's ekos.toml, then EKOS_WORKSPACE.

The web console also serves every project over MCP, at /mcp/<tenant>/<project> with an API token, starting a project's server on first use; see Connect Your AI Agent.