MCP server - Moda

Moda’s MCP server is a hosted, remote Model Context Protocol server that exposes every remote-capable moda CLI command as an MCP tool, 1:1 — 53 tools calling the same Data API, control-plane, and ingest endpoints the CLI calls. It runs stateless on Cloudflare Workers: every request carries its own API key, and the server stores no credentials and keeps no session state. Each tool’s manifest entry names the CLI command it mirrors (dev.moda/cli_command), so anything you know about a moda command transfers directly.

This server lets your tools query Moda. The dashboard’s MCP servers page is the reverse direction — it registers your agents’ MCP servers so Moda can observe them.

Endpoint

https://moda-mcp.modas.workers.dev/mcp

The transport is Streamable HTTP. One endpoint serves both the stateless MCP 2026-07-28 core and 2025-era legacy Streamable HTTP clients; there is no SSE-only transport and no session to establish or resume. A fresh server instance is built per request with your API key bound to it. An unauthenticated health check lives at /health:

curl https://moda-mcp.modas.workers.dev/health

Output

{
  "service": "moda-mcp",
  "version": "0.1.0",
  "endpoint": "/mcp",
  "transport": "streamable-http (MCP 2026-07-28 + 2025 legacy compat)",
  "authentication": "Send your Moda API key on every request: Authorization: Bearer moda_sk_... (or x-api-key). Keys: https://moda.dev/settings or `moda provision`.",
  "docs": "https://docs.moda.dev/mcp/overview"
}

Authentication

Every request carries an API key (called an ingestion key in the dashboard) in a header — Authorization: Bearer moda_sk_... preferred, or x-api-key. Unlike the Data API and Ingestion API, which each read only one of those headers, the MCP server accepts either.

Keys travel in headers only — the server never accepts a key in the URL, so it cannot leak into logs, browser history, or MCP client config screenshots of the endpoint field. Authentication is per request: there is no login step, no session, and no server-side key storage. The tenant is embedded in the signed key, so every tool call is scoped to that key’s tenant and nothing can re-point it.

Get a key from the dashboard at Settings → Ingestion keys (shown once at creation), or mint one with the CLI: moda provision for headless environments, or moda init during project setup. See Authentication for key management. A connection without a key still initializes and lists tools; calling any tool then returns an in-band error with setup instructions (where to get a key, how to configure the header) instead of a transport failure, so agents and client UIs surface exactly what to fix. An invalid or revoked key returns the same kind of in-band guidance on every call.

Connect from clients

claude mcp add --transport http moda https://moda-mcp.modas.workers.dev/mcp \
  --header "Authorization: Bearer $MODA_API_KEY"

{
  "mcpServers": {
    "moda": {
      "url": "https://moda-mcp.modas.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer moda_sk_..."
      }
    }
  }
}

{
  "servers": {
    "moda": {
      "type": "http",
      "url": "https://moda-mcp.modas.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer moda_sk_..."
      }
    }
  }
}

npx mcp-remote https://moda-mcp.modas.workers.dev/mcp \
  --header "Authorization: Bearer $MODA_API_KEY"

Clients that only speak stdio (Claude Desktop among them) connect through mcp-remote, which proxies stdio to the remote endpoint. In every snippet, the endpoint URL also accepts a ?toolsets= query parameter to shrink the tool surface — see below.

Toolsets

The 53 tools are grouped into 6 toolsets, mirroring the CLI’s command areas:

Toolset	Tools	Covers
`data`	22	Production data and intelligence: `overview`, `search`, `conversations`, `context`, `world_state`, `audit`, `step_scores`, `frustrations`, `emotions`, `hallucinations`, `tool_failures`, `problems`, `investigate`, `ask`, …
`fixes`	11	The fix lifecycle: `fixes`, `fix_start`, `fix`, `fix_verify`, `fix_packet`, `fix_submit`, `fix_mark_applied`, `fix_dismiss`, …
`prompts`	6	Prompt management: `prompts_sync`, `prompts_diff`, `prompts_promote`, `prompts_ab`, `prompts_propose`, `replay_run_status`
`skills`	7	Skill generation and proposals: `skills_gen`, `skills_status`, `skills_list`, `skills_push`, `skills_proposals`, …
`harness`	3	Remote harness state: `harness_sync`, `harness_delete`, `harness_analyze_status`
`meta`	4	Connection diagnostics: `whoami`, `doctor`, `status`, `manifest`

By default the endpoint serves the full catalog. Append ?toolsets= with a comma-separated list to filter:

https://moda-mcp.modas.workers.dev/mcp?toolsets=data,fixes

meta is always included even when not requested — whoami, doctor, status, and manifest are the connection-diagnosis surface. Unknown toolset names are ignored; if nothing valid remains, the full catalog is served. Tools are registered in deterministic name order, so client prompt caches stay warm across requests.

Lean mode

?toolsets=lean serves 12 tools: the 10 core tools (overview, search, conversations, context, ask, problems, problem, frustrations, tool_failures, whoami) plus two catalog meta-tools:

search_tools — keyword-searches the full 53-tool catalog and returns matching names, descriptions, and input schemas.
execute_tool — runs any cataloged tool by name with a JSON arguments object, validated against the target tool’s schema before dispatch.

This is progressive disclosure: agents keep a small prompt footprint for the common flows and reach the long tail on demand. Because execute_tool can reach write tools, it does not advertise a read-only annotation.

Prompts, resources, and instructions

On connect, the server publishes instructions that teach the Moda data model (conversations, clusters, detections, problems, fixes, prompts, skills) and the canonical investigation flows — overview → problems → problem → context, search → context, fix_start → fix → fix_verify — so agents chain tools correctly instead of guessing at entity relationships.

Investigation prompts

Five MCP prompts package Moda’s investigation playbooks as slash-commands in clients that support them:

Prompt	Arguments	What it does
`triage-frustrations`	`days_back`, `topic` (optional)	Finds and ranks user-frustration hotspots, with transcript evidence and one concrete next action per hotspot.
`hallucination-audit`	`days_back` (optional)	Audits contradicted agent outputs: rule breakdown, worst conversations, and whether a prompt fix is warranted.
`debug-tool-failures`	`tool_name` (optional)	Works a failing tool from overview to root cause: failure subtypes, representative transcripts, and the fix path.
`investigate-conversation`	`conversation_id` (required)	Deep-dives one conversation: transcript, world state, signals, and step scores.
`weekly-agent-health`	—	Produces the weekly health report: KPIs, deltas, top problems, and the fix queue.

Conversation transcripts as resources

The resource template moda://conversations/{conversation_id} returns a windowed markdown transcript of one ingested conversation (5 messages centered on the latest). Search-style tools return conversation ids; clients can attach or preview the transcript by id without spending a tool call. For a specific window, use the context tool with msg_index and window.

Result shape

Tool results are JSON by default. Heavy read tools accept response_format: "concise" | "detailed"; concise returns a compact markdown rendering instead of the full payload.
Results are capped at roughly 25k tokens. Oversized results are truncated with an explicit hint to narrow the query (limit, days_back, time_range, an id) — never silently cut.
Unknown ids return an empty result plus a warning, not an error, matching the Data API’s convention.
Every read tool carries a readOnlyHint: true annotation (plus idempotentHint); write tools declare themselves non-read-only, so clients can gate them behind approval.
Errors come back as recovery instructions — what failed, why, and what to do next — never a bare status code.
Transcript excerpts, user quotes, and world-state values inside results are end-user data from your production traffic. The server quarantines them under untrusted_data in structured results and fences them in resource markdown, so agents treat them as data, never as instructions.

CLI-only commands

Not every moda command is a tool. Commands that open a browser, manage local credentials, or read and write your repo (moda init, moda provision, moda auth *, moda harness scan, moda workspace, …) stay CLI-only. The manifest tool returns the full tool-to-command map with the reason each CLI-only command is excluded, and CLI parity documents the complete list.

On the roadmap: OAuth 2.1 resource-server authentication and a listing in the official MCP registry. Header-based API key authentication is the supported path today.

Next steps

MCP tool reference — every tool with its parameters and example output.
CLI parity — the 1:1 tool-to-command map and which commands stay CLI-only.
CLI overview — the same surface from the terminal, and how to mint API keys.
Data API overview — the HTTP API behind the data toolset.

​Endpoint

​Authentication

​Connect from clients

​Toolsets

​Lean mode

​Prompts, resources, and instructions

​Investigation prompts

​Conversation transcripts as resources

​Result shape

​CLI-only commands

​Next steps

Endpoint

Authentication

Connect from clients

Toolsets

Lean mode

Prompts, resources, and instructions

Investigation prompts

Conversation transcripts as resources

Result shape

CLI-only commands

Next steps