> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moda.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect any MCP client to Moda's hosted MCP server, which exposes every remote-capable moda CLI command as a tool authenticated per request with your API key.

Moda's MCP server is a hosted, remote [Model Context Protocol](https://modelcontextprotocol.io) 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](/cli/overview) 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.

<Note>
  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.
</Note>

## 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`:

```bash theme={"dark"}
curl https://moda-mcp.modas.workers.dev/health
```

```json Output theme={"dark"}
{
  "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](/data-api/overview) and [Ingestion API](/ingestion/http-api), which each read only one of those headers, the MCP server accepts either.

<Warning>
  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.
</Warning>

Get a key from the dashboard at **Settings → Ingestion keys** (shown once at creation), or mint one with the CLI: [`moda provision`](/cli/overview#headless-provisioning-moda-provision) for headless environments, or `moda init` during project setup. See [Authentication](/administration/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

<CodeGroup>
  ```bash Claude Code theme={"dark"}
  claude mcp add --transport http moda https://moda-mcp.modas.workers.dev/mcp \
    --header "Authorization: Bearer $MODA_API_KEY"
  ```

  ```json Cursor (~/.cursor/mcp.json) theme={"dark"}
  {
    "mcpServers": {
      "moda": {
        "url": "https://moda-mcp.modas.workers.dev/mcp",
        "headers": {
          "Authorization": "Bearer moda_sk_..."
        }
      }
    }
  }
  ```

  ```json VS Code (.vscode/mcp.json) theme={"dark"}
  {
    "servers": {
      "moda": {
        "type": "http",
        "url": "https://moda-mcp.modas.workers.dev/mcp",
        "headers": {
          "Authorization": "Bearer moda_sk_..."
        }
      }
    }
  }
  ```

  ```bash Claude Desktop / stdio-only clients theme={"dark"}
  npx mcp-remote https://moda-mcp.modas.workers.dev/mcp \
    --header "Authorization: Bearer $MODA_API_KEY"
  ```
</CodeGroup>

Clients that only speak stdio (Claude Desktop among them) connect through [`mcp-remote`](https://www.npmjs.com/package/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](/mcp/parity) documents the complete list.

<Note>
  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.
</Note>

## Next steps

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