Skip to main content
Complete reference for the 53 tools on the hosted Moda MCP server (https://moda-mcp.modas.workers.dev/mcp). Connection setup, authentication, and toolset filtering (?toolsets=data,fixes, ?toolsets=lean) are covered in the MCP server overview; the full 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.
  • 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; prompts_promote, fix_dismiss, and harness_delete additionally advertise destructiveHint: true.
  • 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 conversations 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 conversations 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-conversations

conversations

Lists ingested conversations 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 conversations Message-level keyword/semantic/hybrid search across every ingested conversation, 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 search

context

Returns a windowed transcript of one conversation: 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 context

world_state

Reads the world state Moda tracked for one conversation, in three modes: the default event/summary view, a point-in-time snapshot at a message index, or a frame-by-frame replay. snapshot and replay are mutually exclusive; unknown ids yield an empty-200 payload plus a not-found warning.
Arguments
CLI: moda world-state

audit

Returns the ingestion audit for a conversation id or 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 audit

step_scores

Returns Moda’s per-step quality scores for one conversation: scored steps and segment rollups. A conversation that exists but has not been scored yet returns empty arrays with a warning.
Arguments
CLI: moda step-scores

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. The emotions tool is the multi-family superset of this legacy single-family view.
Arguments
CLI: moda frustrations

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 emotions

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 hallucinations

tool_failures

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

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 tool-failure-detail

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 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 problem

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 problem-feedback

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 conversations 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: three parallel Data API reads (/overview, /tool-failures, /frustrations) synthesized into severity-ranked findings with evidence refs and suggested next tools. Each source is best-effort — an unavailable endpoint becomes a warning and a source_status entry, never an error.
Arguments
CLI: moda investigate

failures

The failure-only variant of investigate: identical three-source fetch and severity ranking, but frustration findings are excluded so only tool-failure (and insufficient-data) findings remain. The /frustrations fetch still runs and reports its availability in source_status/warnings.
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).
Arguments
CLI: moda ask

Fixes

A Fix pairs a candidate change with a replay-gate verdict on held-out production evidence — see Fixes in the dashboard for concepts. The pipeline is advance-on-poll: nothing progresses server-side between requests, so wait: true and fixes_drive drive the pipeline rather than merely watch it. All fix tools accept tenant_id (string, optional): the tenant to operate on, defaulting to the tenant embedded in the signed API key — required only for legacy unsigned keys. Fix mutations are sent exactly once, never retried.

fixes

Lists the tenant’s ranked queue of Fixes (id, MODA-FIX short ref, status, fix type, status reason) with cursor pagination, optionally filtered by status. An empty queue means nothing is drafted yet — create fixes with fix_start or fixes_draft_batch.
Arguments
CLI: moda fixes

fixes_draft_batch

Batch-drafts Fixes for the tenant’s top-ranked fixable problems in one server-side call (the backend scans up to 100 ranked problems) and returns the drafted fixes plus per-problem skip reasons. Creation only — drive the drafted fixes with fixes_drive afterwards.
Arguments
CLI: moda fixes draft-batch

fixes_drive

Snapshots the fix queue and round-robins one advance step per active fix per pass — fair progress, so a slow gate never starves the others. A bounded reinterpretation of the CLI’s hours-long drive: it runs at most max_passes passes per call and reports stragglers — call it again to continue. coverage_truncated plus warnings report when the snapshot could not be proven complete, with the exact remedy for each case.
Arguments
CLI: moda fixes drive

fix

Reads one Fix — status, gate result, candidate ref, PR info — and, with wait: true, drives the advance-on-poll pipeline (each poll POSTs one advance step, so wait turns the read into a write). Waiting stops at a resting status or at max_wait_seconds, returning the current state with a timed-out warning — call again to continue. data.next_steps points at the status-appropriate follow-up tool.
Arguments
CLI: moda fix

fix_start

Drafts a Fix for one problem and, with wait: true, drives scope → propose → gate to a resting status, attaching the fix packet fail-soft. Without wait it returns the drafted fix immediately — advance it later with fix (wait: true) or fixes_drive.
Arguments
CLI: moda fix start

fix_packet

Fetches the moda.fix_packet.v1 document for a fix verbatim — diagnosis, evidence, and any candidate blocks (tool-description rewrite, drafted SKILL.md, or a minimal skill edit), also surfaced as findings. Unlike the CLI, this server writes no files: write the candidate text from the packet payload yourself if you want a diffable copy, then confirm with fix_mark_applied.
Arguments
CLI: moda fix —packet

fix_verify

Enqueues a gate + control run for a fix’s candidate — the stored one, or an inline replacement via candidate_content — then by default drives advance-on-poll until the gate verdict lands. VERIFIED with a pass verdict succeeds; GATE_FAILED returns an error with best-effort per-case findings for the fail-to-pass loop; anything else (inconclusive, blocked, a lapsed wait) is degraded, never a pass. A concurrent verify can supersede this run — a warning flags when the reported verdict belongs to a different gate run.
Arguments
CLI: moda fix verify

fix_checkout

Resolves a prompt fix’s candidate content and returns everything a local checkout needs: the target path, the full candidate text, the branch convention (moda/fix/<shortref-lowercase>), the PR magic word (Fixes MODA-FIX-<SHORTREF>), and the candidate version id. This server writes nothing — you write content to path and run git yourself. It refuses artifact fixes (TOOL_SCHEMA/SKILL — use fix_packet + fix_mark_applied) and fixes without a proposed candidate, with the recovery path in each error.
Arguments
CLI: moda fix checkout

fix_submit

Hands a fix back for delivery: channel pr has the backend open the draft PR (the response carries prUrl/prBranch — no local git anywhere), while channel local_ref records your own branch name server-side so landing it with the magic word in the PR body confirms the fix via the merge webhook.
Arguments
CLI: moda fix submit

fix_mark_applied

Confirms you applied a fix’s candidate in your own infrastructure — the no-GitHub delivery path: the fix flips straight to SHIPPED, mark_fixed feedback is posted, and the problem enters fixed-monitoring (HELD after 14 clean days, REGRESSED on reopen). Idempotent server-side: repeating it on a confirmed fix is a duplicate no-op flagged as a warning.
Arguments
CLI: moda fix mark-applied

fix_dismiss

Dismisses a fix with a required reason, recorded as problem feedback that steers future drafting and ranking. Destructive — dismissal removes it from the active queue; prefer fix_mark_applied when you actually shipped the change.
Arguments
CLI: moda fix dismiss

Prompt management

The prompt tools are the code-first prompt workflow with local file discovery replaced by inline content: prompt bodies travel as arguments, and the returned key → {promptId, versionId} mapping plus content hashes is the lockfile replacement — persist it client-side. moda prompts init, status, and --watch are local-file workflows and stay CLI-only. The prompt tools accept tenant_id where noted, with the same semantics as the fix tools.

prompts_sync

Pushes prompt definitions (content inline) to the Moda prompt registry, minting new versions for changed content, and returns the server’s synced list plus each prompt’s content hash computed with the CLI’s exact canonicalization. The sync is a full push with no explicit delete list: keys absent from prompts are conveyed as implicitly removed, so send the complete set every time.
Arguments
CLI: moda prompts sync

prompts_diff

Previews what a sync would change by running the same POST /prompts/sync with dryRun forced to true — the server-computed replacement for moda prompts status/diff, which compare local file hashes against a local lockfile. Never writes registry versions.
Arguments
CLI: moda prompts status / diff

prompts_promote

Points a registry label (dev, staging, or prod) at a specific prompt version — the final step after prompts_sync, prompts_ab, or prompts_propose hands you a winning versionId. Promoting overwrites the label’s current assignment, and a prod promotion redirects live traffic immediately, so confirm the version first.
Arguments
CLI: moda prompts promote

prompts_ab

Runs a baseline-vs-candidate prompt comparison over a replay set: both arms travel inline as content strings. The replay set comes from at most one of set_id (reuse), conversation_ids (one case per conversation), or auto_generate — the default when all three are omitted. MCP-shaped async: wait defaults to false, returning {replaySetId, runId} to poll with replay_run_status. Deliberate deviation from the CLI: promote_primary defaults to false here (the CLI defaults it to true), so a comparison never promotes the winning arm unless explicitly requested.
Arguments
CLI: moda prompts ab

prompts_propose

Turns a completed A/B run’s failures into a server-generated revised candidate, registered as a new unlabeled prompt version — the CLI’s --out file write becomes the returned content (plus versionId, contentHash, changelog, risks, and repair/holdout case ids). gate: true chains an automatic candidate-vs-baseline replay on the same set: baseline_content is then required inline, and promote_on_win promotes to prod only on a strict candidate win of a completed run. If the gate exceeds max_wait_seconds you get the in-flight status with a warning: finish with replay_run_status, then promote manually with prompts_promote.
Arguments
CLI: moda prompts propose

replay_run_status

Fetches the latest state of a replay-set comparison run — status, per-arm pass counts and rates, per-case results — plus a formatted verdict (strict pass-count delta, same wording as moda prompts ab). Poll it after prompts_ab or prompts_propose returned a queued runId until run.status is completed, skipped, or error.
Arguments
CLI: moda prompts ab (the poll step of --wait)

Skills

Moda distills recurring agent behavior into skill files. The MCP skill tools exchange content inline: they return SKILL.md text and accept it as arguments — installing files (.claude/skills/<id>/SKILL.md, .cursor/rules/<id>.mdc) and pruning via .moda/skills.yml is the client’s job.

skills_gen

Kicks off a tenant-wide skill generation run: it clusters recent SDK sessions, distills candidate skills, and optionally replays and improves them. Every option you omit is left to the backend default (the CLI materializes its own defaults client-side; this tool does not). Generation takes minutes — poll skills_status with the returned run id rather than passing wait_for_completion.
Arguments
CLI: moda skills gen

skills_status

Reports the status, counters, and outcome of a skill generation run: pass run_id for that run’s detail (including event breadcrumbs), or omit it to read the tenant’s latest run. An unknown run_id returns found: false with a warning rather than an error.
Arguments
CLI: moda skills status

skills_list

Fetches the tenant’s generated skills with their full SKILL.md content. This is the server half of moda skills pull: it returns content only — writing files is the client’s job.
Arguments
CLI: moda skills pull

skills_push

Pushes user-authored skills (SKILL.md content inline) to the Moda skill registry, minting new versions for changed content. This is moda skills sync with local .claude/skills/**/SKILL.md discovery replaced by arguments; the CLI’s managed AGENTS.md upsert is a local file write and stays CLI-only. Unchanged content is a server-side no-op.
Arguments
CLI: moda skills sync

skills_proposals

Lists skill proposals — PR-ready skill candidates produced by generation runs — with their status and metadata. status defaults to ready_for_pr on the wire exactly like the CLI, and status: "all" drops the filter entirely.
Arguments
CLI: moda skills proposals

skills_proposal

Fetches a single skill proposal including its full SKILL.md content. This is the fetch half of moda skills proposal apply: the client applies the content itself (write the file, or adapt it for another agent), then acknowledges with skills_proposal_mark_applied.
Arguments
CLI: moda skills proposal apply (fetch step)

skills_proposal_mark_applied

Acknowledges that a skill proposal’s content has been applied client-side, moving it out of the ready queue (the request records appliedBy: "moda-mcp"; the CLI sends moda-cli). Call it only after the client actually wrote the SKILL.md fetched with skills_proposal — marking without applying loses the reminder that the proposal is pending.
Arguments
CLI: moda skills proposal apply (mark-applied step)

Harness

The harness tools cover the server-side halves of the harness workflow: uploading, deleting, and reading hosted analysis runs. Producing the graph and report requires the local repo, so moda harness scan/analyze/approve/validate-report stay CLI-side.

harness_sync

Uploads a harness graph — and optionally an approved analysis report (the CLI’s --from-report form) — to the tenant’s harness registry. The backend’s 2,000,000-byte graph limit is enforced client-side before the POST, and dry_run previews without writing.
Arguments
CLI: moda harness sync

harness_delete

Permanently deletes a harness from the tenant — including every synced version, agent, artifact, and relationship under it — and returns the server’s deleted counts. There is no undo, which is why the CLI demands --yes and this tool demands confirm: true.
Arguments
CLI: moda harness delete

harness_analyze_status

Reads the status, progress, and (when completed) results of a hosted harness analysis run. Starting a remote analysis requires a source snapshot built from the local repo, so kicking one off is CLI-only (moda harness analyze --remote prints the run id this tool takes); this is the read half that moda harness pull uses. Server-controlled progress strings are sanitized of ANSI/control characters before being returned.
Arguments
CLI: moda harness pull

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 fix 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 conversation/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 instead of 53: ten core tools (overview, search, conversations, context, ask, problems, problem, frustrations, tool_failures, whoami) plus the two below, which give progressive access to the full catalog without loading every schema into the client’s context. They only appear in lean mode and have no CLI equivalent.

search_tools

Searches the complete catalog of Moda tools by keyword when the tools listed in lean mode 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 full Moda catalog by name with a JSON arguments object. 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.