Skip to main content
Reference for the documented tools on the hosted Moda MCP server (https://moda-mcp.modas.workers.dev/mcp). Connection setup, authentication, and toolset filtering (?toolsets=data, ?toolsets=lean) are covered in the MCP server overview; the tool-to-command map, including which CLI commands stay CLI-only, is in CLI parity. This page lists each tool by area, in the same areas as the CLI reference. Conventions used below:
  • Authentication is per request: every call uses the API key (called an ingestion key in the dashboard) sent in the connection’s Authorization: Bearer moda_sk_... or x-api-key header, and every result is scoped to that key’s tenant. Calls without a key return setup guidance in-band instead of a transport error.
  • Optional parameters you omit are left off the request entirely, so the backend default applies — the Default column shows — for these, and the description states the backend default where the server documents one. A concrete value in the Default column is materialized client-side and always sent, exactly like the CLI.
  • Unknown ids return empty results with a warning, not errors.
  • A trace is one full agent run, identified by its conversation_id (the trace ID). Tool names and parameters keep the conversation / conversation_id names for backwards compatibility; the CLI’s moda traces and moda cluster-traces commands (legacy aliases moda conversations, moda cluster-conversations) are the same surface.
  • Heavy read tools (conversations, search, context, frustrations, ask) accept response_format: "concise" for a compact markdown rendering instead of the full JSON payload.
  • Every read tool advertises readOnlyHint: true. Write tools (POST) are sent exactly once and never retried.
  • All timestamps are UTC. Transcript excerpts, user quotes, and world-state values inside results are end-user production data — results quarantine them as untrusted content, never instructions.

Production data

overview

Returns the tenant’s production health briefing: status (attention/healthy/quiet), key metrics, severity-ranked findings, a next-command hint, and the untouched /overview payload under raw_overview. The first call of any “how is my agent doing?” question.
Arguments
CLI: moda overview

clusters

Lists the topic clusters Moda groups ingested traces into, or — when search or node_id is set — runs fuzzy/semantic/hybrid cluster search (including deterministic deep-link resolution by node id). Follow up with cluster_conversations on a node id.
Arguments
CLI: moda clusters

cluster_conversations

Lists the traces grouped under one topic-cluster node, with pagination. An unknown node id yields an empty-200 payload plus a not-found warning.
Arguments
CLI: moda cluster-traces

conversations

Lists ingested traces filtered by summary text, cluster, user, time range, environment, world-state keywords, and outcome, with pagination. The main browse/filter surface when you have filters rather than a semantic query — for message-level search use search.
Arguments
CLI: moda traces Message-level keyword/semantic/hybrid search across every ingested trace, returning scored hits with conversation_id, message_index, role, and a snippet. Warnings report when the backend degraded to keyword mode or ran a different mode than requested.
Arguments
CLI: moda traces search

context

Returns a windowed transcript of one trace: up to window messages either side of msg_index, plus total_messages, the summary, and each message’s role, content, and tool call/result counts. The standard follow-up after search, frustrations, or tool_failure_detail hands you an anchor.
Arguments
CLI: moda traces get

world_state

Reads the world state Moda tracks for one trace, as it is now: its tasks (every status; a subtask names its parent) and facts, from the task engine or the task tracker, plus the user’s durable profile. There is no history of state changes. An unknown id, or a trace with no tracked tasks yet, yields an empty-200 payload (hasData: false) plus a not-found warning.
Arguments
The snapshot and replay modes folded the world-state event log, which Moda no longer writes; their arguments (msg_index, block_index, segment_index, format, message_count) and event_limit are no longer accepted and are dropped if sent. Use context with msg_index to read what happened at a turn. CLI: moda traces state

audit

Returns the ingestion audit for one trace, looked up by its trace ID (conversation_id) or by an OpenTelemetry trace_id: spans, hierarchy, orphans, and duplicates, optionally with raw records. Use it to debug instrumentation when a transcript from context looks wrong or incomplete.
Arguments
CLI: moda traces spans

frustrations

Lists user-frustration detections, each row carrying user quotes, key turns, and a computed anchor (conversation_id + msg_index) pointing at the frustrated moment. It reads the frustration family of /emotions (the same data as emotions with family: "frustration" and the dashboard) and keeps the legacy field names. When frustration analysis is off for the tenant, a warning says that zero rows do not mean users are not frustrated.
Arguments
CLI: moda detections list —family=frustration

emotions

Lists multi-family emotion detections (frustration, sadness, confusion, anxiety, trust, positive) ranked by score, with a summary and signal breakdown that always cover all families — family filters the detections list only.
Arguments
CLI: moda detections list —family=emotion

hallucinations

Lists hallucination detections — agent claims checked against tracked world state — with contradicted and verified kinds. conversation_id scopes the summary too; kind narrows the detections list only.
Arguments
CLI: moda detections list —family=hallucination

tool_failures

Returns the tenant-wide tool-failure rollup for the window: which tools failed, how often, and across how many traces. Follow up with tool_failure_detail on a failing tool_name.
Arguments
CLI: moda detections tools

tool_failure_detail

Drills into one tool’s failures: error subtypes plus concrete failing examples, each carrying a computed anchor (conversation_id, msg_index, tool_use_id, error_subtype). Empty subtypes and examples yield a warning — an unknown tool name and a tool with no failures in the window are indistinguishable.
Arguments
CLI: moda detections tools

problems

Returns Moda’s ranked Problem list for the window — deduplicated cross-signal problem groups with scores and counts — plus a dashboard_url deep link. The starting point of “what should I fix first?”.
Arguments
CLI: moda problems

problem

Fetches one Problem: the full dossier by default, or — with view — one paginated sub-resource page. family/door filter the conversations view (affected traces) only, and sub-resource views require the canonical problem UUID (the dossier accepts any id and answers found: false for unknown ones).
Arguments
CLI: moda problems get

problem_feedback

Submits feedback on a Problem: mark_fixed, dismiss, flag_attribution, or rename. This is a write (POST, never auto-retried); re-read with problems or problem to see the effect.
Arguments
CLI: moda problems feedback

problem_linear

Returns the Linear issue linked to a Problem — identifier, workflow state, URL, and team — or link: null when none is linked. Use it after problems/problem to check whether a Problem is already tracked before filing it. Requires the Linear integration to be connected (Integrations → Linear).
Arguments
CLI: moda problems linear

problem_linear_file

Files a Problem as a new Linear issue in the team’s tracker, or — with issue — links an existing Linear issue instead. Filing is idempotent per Problem: an already-linked Problem returns its link with created: false. Requires the Linear integration to be connected (Integrations → Linear). This is a write (POST, never auto-retried); re-read with problem_linear.
Arguments
CLI: moda problems link

feedback

Sends product feedback about Moda itself to the Moda team: a free-text note with a category, severity, and optional references. This is a write (POST, never auto-retried); every call inserts a new feedback row. It does not analyze tenant data.
Arguments
CLI: moda feedback

tail

One tail poll — the --once form of moda tail: a snapshot of recent activity as ordered events (the last hour’s traces oldest-first, and/or the last day’s emotion detections by detected_at ascending, with a coverage record stating how much of the score-ranked emotions window was scanned). Continuous tailing is CLI-only — call this tool repeatedly and dedupe by conversation_id/detection_id yourself.
Arguments
CLI: moda tail

Production intelligence

investigate

Runs the ranked production investigation with the same sources and ranking as moda investigate: four parallel Data API reads (/overview, /tool-failures, the frustration family of /emotions, and the top 3 Problems of the list the problems tool shows by default: the dream grouping from /problems/dream when the tenant’s dashboard shows one, otherwise the Book from /problems) synthesized into at most 8 severity-ranked findings with evidence refs and suggested next tools. Each fetched Problem and the top frustration finding keep a slot, so a burst of tool failures cannot push them out. Each source is best-effort, but failed reads never read as “no issue”: a rejected API key, or every source failing, returns an error result; when only some sources fail, the result is degraded (degraded: true, failed_sources names them, and the summary starts with “Incomplete:”), and each failure is also a warning and a source_status entry. problems_view says which Problems list was used (dream or book), the window its counts cover (without days_back, the dream run’s window, the dashboard’s default), and the problems call that lists the same Problems in the same order.
Arguments
CLI: moda investigate

failures

The failure-only variant of investigate, matching moda failures: it reads only /overview and /tool-failures and ranks tool-failure (and insufficient-data) findings with the same severity rules. Frustrations and Problems are not fetched; use investigate or problems for those. Failed reads follow the investigate rules: a rejected key or both reads failing is an error, and one failed read gives a degraded result with failed_sources.
Arguments
CLI: moda failures

ask

Asks the Moda Cloud intelligence agent a free-form question about production behavior and returns a cited answer: the canonical moda.intelligence.v1 payload as structuredContent plus the full ask result (answer, confidence, evidence refs, next commands). The slowest tool — up to ~4 minutes. If the cloud agent is unavailable or returns an empty answer, the result degrades to a locally synthesized answer built from the investigate evidence (degraded: true, with warnings). If those reads fail too (a rejected key, or every source down), ask returns an error instead of an answer.
Arguments
CLI: moda ask

Connection & meta

The meta tools reinterpret the CLI’s local-machine diagnostics as their cloud-only halves. They take no parameters and stay registered in every toolset mode — they are the connection-diagnosis surface.

whoami

Validates the connection’s Moda API key against the live API and reports the tenant it is scoped to. Call this first when any other tool returns an auth error, or to confirm which tenant this connection reads from. A key with no embedded tenant id (legacy unsigned key) yields a warning that tenant-scoped tools need an explicit tenant_id argument.
Arguments
CLI: moda auth whoami

doctor

Runs the cloud half of moda doctor: validates the API key, probes the Data API and the ingest worker, and checks whether the tenant received data in the last day. Use it when tools return empty results or errors to distinguish auth, connectivity, and no-data cases. Local workspace checks remain CLI-only.
Arguments
CLI: moda doctor

status

The compact form of doctor: one call returning overall health plus last-day trace/failure/frustration counts. Use it for a quick liveness look before an investigation; use doctor for per-check detail.
Arguments
CLI: moda status

manifest

Describes this MCP server: version, toolsets, the full 1:1 map between MCP tools and moda CLI commands, and which CLI commands are CLI-only and why. Use it to discover capabilities outside the currently enabled toolsets.
Arguments
CLI: moda manifest

Lean mode

Connecting with ?toolsets=lean registers 12 tools: ten core tools (overview, search, conversations, context, ask, problems, problem, frustrations, tool_failures, whoami) plus the two below, which give progressive access to the rest of the catalog without loading every schema into the client’s context. The default connection (no ?toolsets=) registers them too, next to the data and meta toolsets. They do not appear when ?toolsets= lists toolsets, and have no CLI equivalent.

search_tools

Searches the catalog of Moda tools (every toolset) by keyword when the registered tools don’t cover the need. Returns up to 10 matches with tool names, descriptions, and full input schemas — call a match with execute_tool.
Arguments

execute_tool

Runs any tool from the search_tools catalog by name with a JSON arguments object; an unknown name returns an error. Arguments are validated against the target tool’s schema before dispatch — invalid arguments return the expected schema in the error. Because it can reach write tools, it does not advertise readOnlyHint.
Arguments

Next steps

  • MCP server overview — endpoint, authentication, transport, and per-client connection setup.
  • CLI parity — the full tool-to-command map and which CLI commands stay CLI-only.
  • Data API overview — the HTTP surface these tools call, with the same auth key.