MCP Configuration
Transports, tokens, origins and the gated write and live-query tools.
MCP is configured on the command line of ekos mcp serve:
| Flag | Purpose |
|---|---|
--workspace DIR |
workspace containing .ekos/ |
--tcp ADDR |
raw NDJSON over TCP |
--http ADDR |
Streamable HTTP at POST /mcp |
--http-allow-origin ORIGIN |
extra allowed Origin (repeatable) beyond loopback |
--token-file FILE |
require a bearer token on every --tcp / --http connection |
--tcp and --http are mutually exclusive. The older name --tcp-token-file remains as an alias.
Token
Read from --token-file (whitespace trimmed), or EKOS_MCP_TOKEN. HTTP: Authorization: Bearer <token>. TCP: params._meta.token in the first initialize. Stdio ignores it.
Gated tools
ekos_clickhouse_query (live NL-to-SQL) is off unless [clickhouse] enable-mcp-query = true; it accepts a single validated SELECT only. ekos_identity_review and ekos_architecture_review write review events (citing evidence that names the optional reviewer and note) and are the only write-capable review tools; ekos_clickhouse_query records each live query it runs as an evidence + event pair. Everything else a person decides — sign-offs, the review subjects, conflict resolutions, semantics confirmations, treasury authorizations — has no MCP tool at all; agents can only read the state (ekos_signoff_status, ekos_conflicts).
Read scope
--read-scope <file> (or EKOS_READ_SCOPE) limits the whole server to what a JSON file of allow /
deny rules by source, path pattern or object id allows; deny wins, and an unknown source or path
counts as denied. A client may also send a per-call scope in params._meta["ekos/readScope"].
Under a restricting scope only the tools that read through the store are served; the rest — for
example ekos_xref_check — are refused with a reason.
Limits
| Limit | Value |
|---|---|
| Request line (stdio, TCP) | 4 MB |
| Concurrent TCP connections | 64 |
| HTTP request queue | 64; beyond that 503 + Retry-After |
ekos_neighborhood |
depth ≤ 3, max_objects ≤ 5000 (default 500), truncated flag |
ekos_impact |
max_hops ≤ 20 |
| Transformation tools | max_hops ≤ 200 |
Unknown argument names are refused, and a tool call that panics returns an error without stopping the server.
Session memory tools
ekos_session_note, ekos_session_recall and ekos_session_brief appear only when [session-memory] enabled = true. The note tool writes only the inbox file. See Agent Session Memory.