CLI parity map

The MCP server’s contract with the CLI is 1:1: every remote-capable moda command is exposed as exactly one MCP tool with the same name (kebab-case becomes snake_case, subcommand spaces become underscores) and the same wire behavior — same endpoints, same query parameters, same encodings, same warnings. The trace tools keep their original names (conversations, cluster_conversations) while the CLI’s primary commands are now moda traces and moda cluster-traces — the legacy moda conversations / moda cluster-conversations aliases still match 1:1; the mapping below covers the documented tools. Each tool’s registration carries the command it mirrors in _meta["dev.moda/cli_command"], and the manifest tool returns this entire map machine-readably at runtime.

Tool-to-command map

The documented tools, grouped by toolset. Writes? reflects each tool’s readOnlyHint annotation — what approval-gating clients see.

MCP tool	CLI command	Toolset	Writes?
`overview`	`moda overview`	data	No
`investigate`	`moda investigate`	data	No
`failures`	`moda failures`	data	No
`ask`	`moda ask`	data	No
`clusters`	`moda clusters`	data	No
`cluster_conversations`	`moda cluster-traces` (legacy alias `moda cluster-conversations`)	data	No
`conversations`	`moda traces` (legacy alias `moda conversations`)	data	No
`search`	`moda search`	data	No
`world_state`	`moda world-state`	data	No
`context`	`moda context`	data	No
`audit`	`moda audit`	data	No
`step_scores`	`moda step-scores`	data	No
`frustrations`	`moda frustrations`	data	No
`tool_failures`	`moda tool-failures`	data	No
`tool_failure_detail`	`moda tool-failure-detail`	data	No
`emotions`	`moda emotions`	data	No
`hallucinations`	`moda hallucinations`	data	No
`problems`	`moda problems`	data	No
`problem`	`moda problem`	data	No
`problem_feedback`	`moda problem-feedback`	data	Yes
`feedback`	`moda feedback`	data	Yes
`tail`	`moda tail --once`	data	No
`whoami`	`moda auth whoami`	meta	No
`doctor`	`moda doctor`	meta	No
`status`	`moda status`	meta	No
`manifest`	`moda manifest`	meta	No

Wire parity contract

The server ports the CLI’s request-building rules exactly; anything the backend sees is byte-for-byte what the CLI would have sent. The rules:

Rule	Behavior
Parameters travel only when provided	Absent parameters are omitted from the query string so backend defaults apply — the backend rejects unknown parameters, and the CLI never materializes defaults client-side. The handful of client-materialized defaults the CLI does send are copied exactly: `days_back` on `overview`/`investigate`/`failures` (default 7, floored and clamped to 90), `msg_index=0` on `world_state` snapshots, `format` on the `world_state` replay route, `category`/`severity` in the `feedback` body, `signal`/`limit` in `tail`.
Numeric parameters are integers	Input schemas enforce integers, serialized as integer strings on the query string — never floats, never quoted numbers in JSON bodies.
Boolean encodings copied per endpoint	Boolean wire encodings vary per endpoint by backend contract and are copied from the CLI verbatim: `include_tool_io=true` on `/search`, but `summary_only=1` on world-state and `include_raw=1` on audit. Booleans in JSON `POST` bodies are real JSON booleans.
Empty-200 not-found convention	The Data API answers unknown ids with HTTP 200 and an empty payload, never a 404. Tools convert that to a warning — `No <entity> found for id "..." — it may not exist in this tenant` — using the CLI’s template verbatim, never an error.
UUID pre-validation on problem sub-resources	`problem` with a `view` and `problem_feedback` require a canonical problem UUID and fail fast client-side before any network call, because the backend returns 400 for non-UUID ids on those routes. The `problem` dossier (no `view`) accepts any id and answers `found: false`.
Zero transport retries on writes	Every non-idempotent `POST` passes `retries: 0` — a transport retry after a lost response could double-run a pipeline step or insert a duplicate row. Reads retry up to 3 times on 429/5xx with exponential backoff (500 ms initial). `ask` additionally retries exactly once on a network-level failure (the CLI’s poisoned-connection guard); HTTP errors never consume that retry.

Timeout budgets

Per-call timeouts mirror the CLI’s budgets. Calls not listed use the 30-second default.

Call family	Budget
`ask` (`POST /cli/ask`)	250 s
Everything else	30 s

Deliberate deviations

The following behaviors intentionally differ from the CLI. Each is also called out in the affected tool’s description.

Area	MCP server	CLI
Path-segment ids	Every path-segment id is URL-encoded before interpolation, so ids containing `/`, `?`, or `#` cannot break out of their path segment (hardening). Query-string behavior is untouched.	Encodes some path ids (`/audit/:id`, `/conversations/:id/step-scores`) but not others (`/clusters/:node_id/conversations`, world-state, context) by design-accident.
`tail`	The `--once` form only: one poll returning ordered events plus a coverage record stating how much of the score-ranked emotions window was scanned. Call repeatedly and dedupe by `conversation_id`/`detection_id` to follow along.	Continuous interval polling with cross-poll dedupe and NDJSON streaming.

CLI-only commands

Commands that open a browser, manage local credentials, or read and write your repo have no MCP tool. The manifest tool returns this list with the same reasons.

Command	Why it stays CLI-only	MCP alternative
`moda init`	Browser sign-in, local file writes, coding-agent subprocesses.	None — run it once in a terminal; it produces the API key this server authenticates with.
`moda provision`	Requires a browser-minted CLI session token; it mints the API key this server uses.	None — provision the key headlessly, then configure it on the connection.
`moda auth login/token/logout`	Manages local credentials; MCP auth is per-request headers.	`whoami` validates the connection’s key and reports its tenant.
`moda profiles` / `moda config` / `moda keys`	Local credential/profile files; an MCP connection is one credential.	Add a separate MCP server entry per environment or tenant.
`moda agent context/investigate/next-action/evidence`	Built from local doctor state plus `.moda` artifacts.	`overview`, `investigate`, and `doctor` cover the cloud halves.
`moda workspace` / `moda hooks install`	Local git shadow repo and coding-agent hook configuration.	None.
`moda tail` (continuous)	Long-running poller.	`tail` is the `--once` form; call it repeatedly and dedupe client-side.

Next steps

MCP server — endpoint, authentication, toolsets, and client setup.
MCP tool reference — every tool with its parameters and example output.
CLI reference — the moda commands these tools mirror, with flags and trimmed outputs.

​Tool-to-command map

​Wire parity contract

​Timeout budgets

​Deliberate deviations

​CLI-only commands

​Next steps